CBCentralManagerDelegate Protocol Reference

Conforms to
NSObject
Framework
/System/Library/Frameworks/CoreBluetooth.framework
Availability
Available in iOS 5.0 and later.
Declared in
CBAdvertisementData.h
CBCentralManager.h
Related sample code

Overview

The delegate of a CBCentralManager object must adopt the CBCentralManagerDelegate protocol. 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 iOS 5.0 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.

Availability
  • Available in iOS 5.0 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 iOS 5.0 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 iOS 5.0 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 connect the peripheral(s) in which your app is interested.

Availability
  • Available in iOS 5.0 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 arrary 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 iOS 5.0 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 iOS 5.0 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;
Constants
CBAdvertisementDataLocalNameKey

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

Available in iOS 5.0 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataManufacturerDataKey

A NSData object containing the manufacturer data of a peripheral.

Available in iOS 5.0 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 any service-specific data.

Available in iOS 5.0 and later.

Declared in CBAdvertisementData.h.

CBAdvertisementDataServiceUUIDsKey

An array of service UUIDs.

Available in iOS 5.0 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 iOS 6.0 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 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 iOS 5.0 and later.

Declared in CBAdvertisementData.h.



© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)

Did this document help you? Yes It's good, but... Not helpful...