CBCentralManagerDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/CoreBluetooth.framework
Availability
Available in OS X v10.7 and later.
Companion guide
Declared in
CBAdvertisementData.h
CBCentralManager.h
Related sample code

Overview

The CBCentralManagerDelegate protocol defines the methods that a delegate of a CBCentralManager object must adopt. The optional methods of the protocol allow the delegate to monitor the discovery, connectivity, and retrieval of peripheral devices. The only required method of the protocol indicates the availability of the central manager, and is called when the central manager’s state is updated.

Tasks

Monitoring Connections with Peripherals

Discovering and Retrieving Peripherals

Monitoring Changes to the Central Manager’s State

Instance Methods

centralManager:didConnectPeripheral:

Invoked when a connection is successfully created with a peripheral.

- (void)centralManager:(CBCentralManager *)central didConnectPeripheral:(CBPeripheral *)peripheral
Parameters
central

The central manager providing this information.

peripheral

The peripheral that has been connected to the system.

Discussion

This method is invoked when a call to connectPeripheral:options: is successful. You typically implement this method to set the peripheral’s delegate and to discover its services.

Availability
  • Available in OS X v10.7 and later.
Declared In
CBCentralManager.h

centralManager:didDisconnectPeripheral:error:

Invoked when an existing connection with a peripheral is torn down.

- (void)centralManager:(CBCentralManager *)central didDisconnectPeripheral:(CBPeripheral *)peripheral error:(NSError *)error
Parameters
central

The central manager providing this information.

peripheral

The peripheral that has been disconnected.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when a peripheral connected via the connectPeripheral:options: method is disconnected. If the disconnection was not initiated by cancelPeripheralConnection:, the cause is detailed in error. After this method is called, no more methods are invoked on the peripheral device’s CBPeripheralDelegate object.

Note that when a peripheral is disconnected, all of its services, characteristics, and characteristic descriptors are invalidated.

Availability
  • Available in OS X v10.7 and later.
Declared In
CBCentralManager.h

centralManager:didDiscoverPeripheral:advertisementData:RSSI:

Invoked when the central manager discovers a peripheral while scanning.

- (void)centralManager:(CBCentralManager *)central didDiscoverPeripheral:(CBPeripheral *)peripheral advertisementData:(NSDictionary *)advertisementData RSSI:(NSNumber *)RSSI
Parameters
central

The central manager providing the update.

peripheral

The discovered peripheral.

advertisementData

A dictionary containing any advertisement data.

RSSI

The current received signal strength indicator (RSSI) of the peripheral, in decibels.

Discussion

The advertisement data can be accessed through the keys listed in “Advertisement Data Retrieval Keys.” You must retain a local copy of the peripheral if any command is to be performed on it. In use cases where it makes sense for your app to automatically connect to a peripheral that is located within a certain range, you can use RSSI data to determine the proximity of a discovered peripheral device.

Availability
  • Available in OS X v10.7 and later.
Declared In
CBCentralManager.h

centralManager:didFailToConnectPeripheral:error:

Invoked when the central manager fails to create a connection with a peripheral.

- (void)centralManager:(CBCentralManager *)central didFailToConnectPeripheral:(CBPeripheral *)peripheral error:(NSError *)error
Parameters
central

The central manager providing this information.

peripheral

The peripheral that failed to connect.

error

The cause of the failure.

Discussion

This method is invoked when a connection initiated via the connectPeripheral:options: method fails to complete. Because connection attempts do not time out, a failed connection usually indicates a transient issue, in which case you may attempt to connect to the peripheral again.

Availability
  • Available in OS X v10.7 and later.
Declared In
CBCentralManager.h

centralManager:didRetrieveConnectedPeripherals:

Invoked when the central manager retrieves a list of peripherals currently connected to the system.

- (void)centralManager:(CBCentralManager *)central didRetrieveConnectedPeripherals:(NSArray *)peripherals
Parameters
central

The central manager providing this information.

peripherals

The array of all peripherals currently connected to the system.

Discussion

This method returns the result of a retrieveConnectedPeripherals call. Since the array of currently connected peripherals can include those connected to the system by other apps, you typically implement this method to reconnect the peripherals in which your app is interested.

Availability
  • Available in OS X v10.7 and later.
Declared In
CBCentralManager.h

centralManager:didRetrievePeripherals:

Invoked when the central manager retrieves a list of known peripherals.

- (void)centralManager:(CBCentralManager *)central didRetrievePeripherals:(NSArray *)peripherals
Parameters
central

The central manager providing this information.

peripherals

An array of peripherals currently known by the central manager.

Discussion

This method returns the result of a call to retrievePeripherals: with an array of the peripherals that the central manager was able to match to the provided universally unique identifiers (UUIDs). You typically implement this method to reconnect to a known peripheral.

Availability
  • Available in OS X v10.7 and later.
Declared In
CBCentralManager.h

centralManager:willRestoreState:

Invoked when the central manager is about to be restored by the system.

- (void)centralManager:(CBCentralManager *)central willRestoreState:(NSDictionary *)dict
Parameters
central

The central manager providing this information.

dict

A dictionary containing information about the central manager that was preserved by the system at the time the app was terminated. For the available keys to this dictionary, see “Central Manager State Restoration Options.”

Discussion

For apps that opt in to the state preservation and restoration feature of Core Bluetooth, this is the first method invoked when your app is relaunched into the background to complete some Bluetooth-related task. Use this method to synchronize the state of your app with the state of the Bluetooth system.

Availability
  • Available in OS X v10.9 and later.
Declared In
CBCentralManager.h

centralManagerDidUpdateState:

Invoked when the central manager’s state is updated. (required)

- (void)centralManagerDidUpdateState:(CBCentralManager *)central
Parameters
central

The central manager whose state has changed.

Discussion

You implement this required method to ensure that Bluetooth low energy is supported and available to use on the central device. You should issue commands to the central manager only when the state of the central manager is powered on, as indicated by the CBCentralManagerStatePoweredOn constant. A state with a value lower than CBCentralManagerStatePoweredOn implies that scanning has stopped and that any connected peripherals have been disconnected. If the state moves below CBCentralManagerStatePoweredOff, all CBPeripheral objects obtained from this central manager become invalid and must be retrieved or discovered again. For a complete list and discussion of the possible values representing the state of the central manager, see the CBCentralManagerState enumeration in CBCentralManager Class Reference.

Availability
  • Available in OS X v10.7 and later.
Declared In
CBCentralManager.h

Constants

Advertisement Data Retrieval Keys

Keys to specify in an advertisementData dictionary.

NSString *const CBAdvertisementDataLocalNameKey;
NSString *const CBAdvertisementDataManufacturerDataKey;
NSString *const CBAdvertisementDataServiceDataKey;
NSString *const CBAdvertisementDataServiceUUIDsKey;
NSString *const CBAdvertisementDataOverflowServiceUUIDsKey;
NSString *const CBAdvertisementDataTxPowerLevelKey;
NSString *const CBAdvertisementDataIsConnectable;
NSString *const CBAdvertisementDataSolicitedServiceUUIDsKey;
Constants
CBAdvertisementDataLocalNameKey

A string (an instance of NSString) containing the local name of a peripheral.

Available in OS X v10.7 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataManufacturerDataKey

A NSData object containing the manufacturer data of a peripheral.

Available in OS X v10.7 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataServiceDataKey

A dictionary containing service-specific advertisement data.

The keys are CBUUID objects, representing CBService UUIDs. The values are NSData objects, representing service-specific data.

Available in OS X v10.7 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataServiceUUIDsKey

An array of service UUIDs.

Available in OS X v10.7 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataOverflowServiceUUIDsKey

An array of one or more CBUUID objects, representing CBService UUIDs that were found in the “overflow” area of the advertisement data.

Due to the nature of the data stored in this area, UUIDs listed here are “best effort” and may not always be accurate. For details about the overflow area of advertisement data, see the startAdvertising: method in CBPeripheralManager Class Reference.

Available in OS X v10.9 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataTxPowerLevelKey

A number (an instance of NSNumber) containing the transmit power of a peripheral.

This key and value are available if the broadcaster (peripheral) provides its Tx power level in its advertising packet. Using the RSSI value and the Tx power level, it is possible to calculate path loss.

Available in OS X v10.7 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataIsConnectable

A Boolean value that indicates whether the advertising event type is connectable.

The value for this key is an NSNumber object. You can use this value to determine whether a peripheral is connectable at a particular moment.

Available in OS X v10.9 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataSolicitedServiceUUIDsKey

An array of one or more CBUUID objects, representing CBService UUIDs.

Available in OS X v10.9 and later.

Declared in CBAdvertisementData.h.