Mac Developer Library

Developer

CoreBluetooth Framework Reference CBCentralManagerDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

CBCentralManagerDelegate

Inheritance


Not Applicable

Conforms To


Import Statement


Swift

import CoreBluetooth

Objective-C

@import CoreBluetooth;

Availability


Available in OS X v10.7 and later.

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.

  • Invoked when a connection is successfully created with a peripheral.

    Declaration

    Swift

    optional func centralManager(_ central: CBCentralManager!, didConnectPeripheral peripheral: CBPeripheral!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    optional func centralManager(_ central: CBCentralManager!, didDisconnectPeripheral peripheral: CBPeripheral!, error error: NSError!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    optional func centralManager(_ central: CBCentralManager!, didFailToConnectPeripheral peripheral: CBPeripheral!, error error: NSError!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in OS X v10.7 and later.

  • Invoked when the central manager discovers a peripheral while scanning.

    Declaration

    Swift

    optional func centralManager(_ central: CBCentralManager!, didDiscoverPeripheral peripheral: CBPeripheral!, advertisementData advertisementData: [NSObject : AnyObject]!, RSSI RSSI: NSNumber!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    optional func centralManager(_ central: CBCentralManager!, didRetrieveConnectedPeripherals peripherals: [AnyObject]!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    optional func centralManager(_ central: CBCentralManager!, didRetrievePeripherals peripherals: [AnyObject]!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func centralManagerDidUpdateState(_ central: CBCentralManager!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    optional func centralManager(_ central: CBCentralManager!, willRestoreState dict: [NSObject : AnyObject]!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in OS X v10.9 and later.

  • Keys to specify in an advertisementData dictionary.

    Declaration

    Swift

    let CBAdvertisementDataLocalNameKey: String let CBAdvertisementDataManufacturerDataKey: String let CBAdvertisementDataServiceDataKey: String let CBAdvertisementDataServiceUUIDsKey: String let CBAdvertisementDataOverflowServiceUUIDsKey: String let CBAdvertisementDataTxPowerLevelKey: String let CBAdvertisementDataIsConnectable: String let CBAdvertisementDataSolicitedServiceUUIDsKey: String

    Objective-C

    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

      CBAdvertisementDataLocalNameKey

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

      Available in OS X v10.7 and later.

    • CBAdvertisementDataManufacturerDataKey

      CBAdvertisementDataManufacturerDataKey

      A NSData object containing the manufacturer data of a peripheral.

      Available in OS X v10.7 and later.

    • CBAdvertisementDataServiceDataKey

      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.

    • CBAdvertisementDataServiceUUIDsKey

      CBAdvertisementDataServiceUUIDsKey

      An array of service UUIDs.

      Available in OS X v10.7 and later.

    • CBAdvertisementDataOverflowServiceUUIDsKey

      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.

    • CBAdvertisementDataTxPowerLevelKey

      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.

    • CBAdvertisementDataIsConnectable

      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.

    • CBAdvertisementDataSolicitedServiceUUIDsKey

      CBAdvertisementDataSolicitedServiceUUIDsKey

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

      Available in OS X v10.9 and later.