iOS Developer Library

Developer

CoreBluetooth Framework Reference CBCentralManager Class Reference

Options
Deployment Target:

On This Page
Language:

CBCentralManager

Inheritance


Conforms To


Import Statement


Swift

import CoreBluetooth

Objective-C

@import CoreBluetooth;

Availability


Available in iOS 5.0 and later.

CBCentralManager objects are used to manage discovered or connected remote peripheral devices (represented by CBPeripheral objects), including scanning for, discovering, and connecting to advertising peripherals.

Before you call CBCentralManager methods, the state of the central manager object must be powered on, as indicated by the CBCentralManagerStatePoweredOn constant. This state indicates that the central device (your iPhone or iPad, for instance) supports Bluetooth low energy and that Bluetooth is on and available to use.

  • Initializes the central manager with a specified delegate and dispatch queue.

    Declaration

    Swift

    convenience init!(delegate delegate: CBCentralManagerDelegate!, queue queue: dispatch_queue_t!)

    Objective-C

    - (instancetype)initWithDelegate:(id<CBCentralManagerDelegate>)delegate queue:(dispatch_queue_t)queue

    Parameters

    delegate

    The delegate to receive the central events.

    queue

    The dispatch queue to use to dispatch the central role events. If the value is nil, the central manager dispatches central role events using the main queue.

    Return Value

    Returns a newly initialized central manager.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later.

  • Initializes the central manager with specified delegate, dispatch queue, and initialization options.

    Declaration

    Swift

    init!(delegate delegate: CBCentralManagerDelegate!, queue queue: dispatch_queue_t!, options options: [NSObject : AnyObject]!)

    Objective-C

    - (instancetype)initWithDelegate:(id<CBCentralManagerDelegate>)delegate queue:(dispatch_queue_t)queue options:(NSDictionary *)options

    Parameters

    delegate

    The delegate to receive the central events.

    queue

    The dispatch queue to use to dispatch the central role events. If the value is nil, the central manager dispatches central role events using the main queue.

    options

    An optional dictionary containing initialization options for a central manager. For available options, see Central Manager Initialization Options.

    Return Value

    Returns a newly initialized central manager.

    Discussion

    This method is the designated initializer for the CBCentralManager class.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later.

  • Establishes a local connection to a peripheral.

    Declaration

    Swift

    func connectPeripheral(_ peripheral: CBPeripheral!, options options: [NSObject : AnyObject]!)

    Objective-C

    - (void)connectPeripheral:(CBPeripheral *)peripheral options:(NSDictionary *)options

    Parameters

    peripheral

    The peripheral to which the central is attempting to connect.

    options

    A dictionary to customize the behavior of the connection. For available options, see Peripheral Connection Options.

    Discussion

    If a local connection to a peripheral is successfully established, the central manager object calls the centralManager:didConnectPeripheral: method of its delegate object. If the connection attempt fails, the central manager object calls the centralManager:didFailToConnectPeripheral:error: method of its delegate object instead. Attempts to connect to a peripheral do not time out. To explicitly cancel a pending connection to a peripheral, call the cancelPeripheralConnection: method. Pending connection attempts are also canceled automatically when peripheral is deallocated.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later.

  • Cancels an active or pending local connection to a peripheral.

    Declaration

    Swift

    func cancelPeripheralConnection(_ peripheral: CBPeripheral!)

    Objective-C

    - (void)cancelPeripheralConnection:(CBPeripheral *)peripheral

    Parameters

    peripheral

    The peripheral to which the central manager is either trying to connect or has already connected.

    Discussion

    This method is nonblocking, and any CBPeripheral class commands that are still pending to peripheral may or may not complete. Because other apps may still have a connection to the peripheral, canceling a local connection does not guarantee that the underlying physical link is immediately disconnected. From the app’s perspective, however, the peripheral is considered disconnected, and the central manager object calls the centralManager:didDisconnectPeripheral:error: method of its delegate object.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later.

  • Retrieves a list of the peripherals currently connected to the system.

    Deprecation Statement

    Use the retrieveConnectedPeripheralsWithServices: method instead.

    Declaration

    Objective-C

    - (void)retrieveConnectedPeripherals

    Discussion

    Upon retrieving the list of connected peripherals, the central manager object calls the centralManager:didRetrieveConnectedPeripherals: method of its delegate object. If there are no peripherals currently connected to the system, the central manager object passes an empty array of peripherals to the centralManager:didRetrieveConnectedPeripherals: method. Note that the list of connected peripherals can include those that are connected by other apps and that will need to be connected locally using the connectPeripheral:options: method before they can be used.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Availability

    Available in iOS 5.0 and later.

    Deprecated in iOS 7.0.

  • Returns a list of the peripherals (containing any of the specified services) currently connected to the system.

    Declaration

    Swift

    func retrieveConnectedPeripheralsWithServices(_ serviceUUIDs: [AnyObject]!) -> [AnyObject]!

    Objective-C

    - (NSArray *)retrieveConnectedPeripheralsWithServices:(NSArray *)serviceUUIDs

    Parameters

    serviceUUIDs

    A list of service UUIDs (represented by CBUUID objects).

    Return Value

    A list of the peripherals that are currently connected to the system and that contain any of the services specified in the serviceUUID parameter.

    Discussion

    The list of connected peripherals can include those that are connected by other apps and that will need to be connected locally using the connectPeripheral:options: method before they can be used.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later.

  • Retrieves a list of known peripherals by their UUIDs.

    Deprecation Statement

    Use the retrievePeripheralsWithIdentifiers: method instead.

    Declaration

    Objective-C

    - (void)retrievePeripherals:(NSArray *)peripheralUUIDs

    Parameters

    peripheralUUIDs

    An array of CFUUIDRef objects from which CBPeripheral objects can be retrieved. Because CBUUID objects represent Bluetooth-specific universally unique identifiers (UUIDs) (used for Bluetooth GATT attributes such as services and characteristics), CBPeripheral objects use standard CFUUIDRef UUIDs as their unique identifiers.

    Discussion

    This method retrieves a list of peripherals that the central manager is able to match to the provided UUIDs. Upon retrieving the list of known peripherals, the central manager object calls the centralManager:didRetrievePeripherals: method of its delegate object. If no matches are made, the central manager object passes an empty array of peripherals to the centralManager:didRetrievePeripherals: method.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Availability

    Available in iOS 5.0 and later.

    Deprecated in iOS 7.0.

  • Returns a list of known peripherals by their identifiers.

    Declaration

    Swift

    func retrievePeripheralsWithIdentifiers(_ identifiers: [AnyObject]!) -> [AnyObject]!

    Objective-C

    - (NSArray *)retrievePeripheralsWithIdentifiers:(NSArray *)identifiers

    Parameters

    identifiers

    A list of peripheral identifiers (represented by NSUUID objects) from which CBPeripheral objects can be retrieved.

    Return Value

    A list of peripherals that the central manager is able to match to the provided identifiers.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later.

  • Scans for peripherals that are advertising services.

    Declaration

    Swift

    func scanForPeripheralsWithServices(_ serviceUUIDs: [AnyObject]!, options options: [NSObject : AnyObject]!)

    Objective-C

    - (void)scanForPeripheralsWithServices:(NSArray *)serviceUUIDs options:(NSDictionary *)options

    Parameters

    serviceUUIDs

    An array of CBUUID objects that the app is interested in. In this case, each CBUUID object represents the UUID of a service that a peripheral is advertising.

    options

    An optional dictionary specifying options to customize the scan. For available options, see Peripheral Scanning Options.

    Discussion

    You can provide an array of CBUUID objects—representing service UUIDs—in the serviceUUIDs parameter. When you do, the central manager returns only peripherals that advertise the services you specify (recommended). If the serviceUUIDs parameter is nil, all discovered peripherals are returned regardless of their supported services (not recommended). If the central manager is already scanning with different parameters, the provided parameters replace them. When the central manager object discovers a peripheral, it calls the centralManager:didDiscoverPeripheral:advertisementData:RSSI: method of its delegate object.

    Apps that have specified the bluetooth-central background mode are allowed to scan while in the background. That said, they must explicitly scan for one or more services by specifying them in the serviceUUIDs parameter. The CBCentralManagerOptionShowPowerAlertKey scan option is ignored while scanning in the background.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later.

  • Asks the central manager to stop scanning for peripherals.

    Declaration

    Swift

    func stopScan()

    Objective-C

    - (void)stopScan

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later.

  • state state Property

    Returns the current state of the central manager. (read-only)

    Declaration

    Swift

    var state: CBCentralManagerState { get }

    Objective-C

    @property(readonly) CBCentralManagerState state

    Discussion

    When a central manager object is initially created, the default value of this property is CBCentralManagerStateUnknown. As the central manager’s state changes, the central manager updates the value of this property and calls the centralManagerDidUpdateState: delegate method. For a list of the possible values representing the state of the central manager, see Central Manager State.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later.

  • delegate delegate Property

    The delegate object you want to receive central events.

    Declaration

    Swift

    weak var delegate: CBCentralManagerDelegate!

    Objective-C

    @property(weak, nonatomic) id< CBCentralManagerDelegate > delegate

    Discussion

    For information about how to implement your central manager delegate, see CBCentralManagerDelegate Protocol Reference.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later.

  • Keys used to pass options to the initWithDelegate:queue:options: method.

    Declaration

    Swift

    let CBCentralManagerOptionShowPowerAlertKey: String let CBCentralManagerOptionRestoreIdentifierKey: String

    Objective-C

    NSString *const CBCentralManagerOptionShowPowerAlertKey; NSString *const CBCentralManagerOptionRestoreIdentifierKey;

    Constants

    • CBCentralManagerOptionShowPowerAlertKey

      CBCentralManagerOptionShowPowerAlertKey

      A Boolean value that specifies whether the system should display a warning dialog to the user if Bluetooth is powered off when the central manager is instantiated.

      The value for this key is an NSNumber object. If the key is not specified, the default value is NOfalse.

      Available in iOS 7.0 and later.

    • CBCentralManagerOptionRestoreIdentifierKey

      CBCentralManagerOptionRestoreIdentifierKey

      A string (an instance of NSString) containing a unique identifier (UID) for the central manager that is being instantiated.

      The system uses this UID to identify a specific central manager. As a result, the UID must remain the same for subsequent executions of the app in order for the central manager to be successfully restored.

      Available in iOS 7.0 and later.

  • Keys used to pass options to the scanForPeripheralsWithServices:options: method.

    Declaration

    Swift

    let CBCentralManagerScanOptionAllowDuplicatesKey: String let CBCentralManagerScanOptionSolicitedServiceUUIDsKey: String

    Objective-C

    NSString *const CBCentralManagerScanOptionAllowDuplicatesKey; NSString *const CBCentralManagerScanOptionSolicitedServiceUUIDsKey;

    Constants

    • CBCentralManagerScanOptionAllowDuplicatesKey

      CBCentralManagerScanOptionAllowDuplicatesKey

      A Boolean value that specifies whether the scan should run without duplicate filtering.

      The value for this key is an NSNumber object. If YEStrue, filtering is disabled and a discovery event is generated each time the central receives an advertising packet from the peripheral. Disabling this filtering can have an adverse effect on battery life and should be used only if necessary. If NOfalse, multiple discoveries of the same peripheral are coalesced into a single discovery event. If the key is not specified, the default value is NOfalse.

      Available in iOS 5.0 and later.

    • CBCentralManagerScanOptionSolicitedServiceUUIDsKey

      CBCentralManagerScanOptionSolicitedServiceUUIDsKey

      An array (an instance of NSArray) of service UUIDs (represented by CBUUID objects) that you want to scan for.

      Specifying this scan option causes the central manager to also scan for peripherals soliciting any of the services contained in the array.

      Available in iOS 7.0 and later.

  • Keys used to pass options to the connectPeripheral:options: method.

    Declaration

    Swift

    let CBConnectPeripheralOptionNotifyOnConnectionKey: String let CBConnectPeripheralOptionNotifyOnDisconnectionKey: String let CBConnectPeripheralOptionNotifyOnNotificationKey: String

    Objective-C

    NSString *const CBConnectPeripheralOptionNotifyOnConnectionKey; NSString *const CBConnectPeripheralOptionNotifyOnDisconnectionKey; NSString *const CBConnectPeripheralOptionNotifyOnNotificationKey;

    Constants

    • CBConnectPeripheralOptionNotifyOnConnectionKey

      CBConnectPeripheralOptionNotifyOnConnectionKey

      A Boolean value that specifies whether the system should display an alert for a given peripheral if the app is suspended when a successful connection is made.

      The value for this key is an NSNumber object. This key is useful for apps that have not specified the bluetooth-central background mode and cannot display their own alert. If more than one app has requested notification for a given peripheral, the one that was most recently in the foreground receives the alert. If the key is not specified, the default value is NOfalse.

      Available in iOS 6.0 and later.

    • CBConnectPeripheralOptionNotifyOnDisconnectionKey

      CBConnectPeripheralOptionNotifyOnDisconnectionKey

      A Boolean value that specifies whether the system should display a disconnection alert for a given peripheral if the app is suspended at the time of the disconnection.

      The value for this key is an NSNumber object. This key is useful for apps that have not specified the bluetooth-central background mode and cannot display their own alert. If more than one app has requested notification for a given peripheral, the one that was most recently in the foreground receives the alert. If the key is not specified, the default value is NOfalse.

      Available in iOS 5.0 and later.

    • CBConnectPeripheralOptionNotifyOnNotificationKey

      CBConnectPeripheralOptionNotifyOnNotificationKey

      A Boolean value that specifies whether the system should display an alert for all notifications received from a given peripheral if the app is suspended at the time.

      The value for this key is an NSNumber object. This key is useful for apps that have not specified the bluetooth-central background mode and cannot display their own alert. If more than one app has requested notification for a given peripheral, the one that was most recently in the foreground receives the alert. If the key is not specified, the default value is NOfalse.

      Available in iOS 6.0 and later.

  • Values representing the current state of a central manager object.

    Declaration

    Swift

    enum CBCentralManagerState : Int { case Unknown case Resetting case Unsupported case Unauthorized case PoweredOff case PoweredOn }

    Objective-C

    typedef enum { CBCentralManagerStateUnknown = 0, CBCentralManagerStateResetting, CBCentralManagerStateUnsupported, CBCentralManagerStateUnauthorized, CBCentralManagerStatePoweredOff, CBCentralManagerStatePoweredOn, } CBCentralManagerState;

    Constants

    • Unknown

      CBCentralManagerStateUnknown

      The current state of the central manager is unknown; an update is imminent.

      Available in iOS 5.0 and later.

    • Resetting

      CBCentralManagerStateResetting

      The connection with the system service was momentarily lost; an update is imminent.

      Available in iOS 5.0 and later.

    • Unsupported

      CBCentralManagerStateUnsupported

      The platform does not support Bluetooth low energy.

      Available in iOS 5.0 and later.

    • Unauthorized

      CBCentralManagerStateUnauthorized

      The app is not authorized to use Bluetooth low energy.

      Available in iOS 5.0 and later.

    • PoweredOff

      CBCentralManagerStatePoweredOff

      Bluetooth is currently powered off.

      Available in iOS 5.0 and later.

    • PoweredOn

      CBCentralManagerStatePoweredOn

      Bluetooth is currently powered on and available to use.

      Available in iOS 5.0 and later.

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 5.0 and later.