CBCentralManager Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreBluetooth.framework
Availability
Available in iOS 5.0 and later.
Companion guide
Declared in
CBCentralManager.h
CBCentralManagerConstants.h
Related sample code

Overview

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.

Tasks

Initializing a Central Manager

Establishing or Canceling Connections with Peripherals

Retrieving Lists of Peripherals

Scanning or Stopping Scans of Peripherals

Monitoring Properties

Properties

delegate

The delegate object you want to receive central events.

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

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

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCentralManager.h

state

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

@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.”

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCentralManager.h

Instance Methods

cancelPeripheralConnection:

Cancels an active or pending local connection to a peripheral.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCentralManager.h

connectPeripheral:options:

Establishes a local connection to a peripheral.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCentralManager.h

initWithDelegate:queue:

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

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

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCentralManager.h

initWithDelegate:queue:options:

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

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

Availability
  • Available in iOS 7.0 and later.
Declared In
CBCentralManager.h

retrieveConnectedPeripheralsWithServices:

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

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

Availability
  • Available in iOS 7.0 and later.
Declared In
CBCentralManager.h

retrievePeripheralsWithIdentifiers:

Returns a list of known peripherals by their identifiers.

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

Availability
  • Available in iOS 7.0 and later.
Declared In
CBCentralManager.h

scanForPeripheralsWithServices:options:

Scans for peripherals that are advertising services.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
CBCentralManager.h

stopScan

Asks the central manager to stop scanning for peripherals.

- (void)stopScan
Availability
  • Available in iOS 5.0 and later.
Declared In
CBCentralManager.h

Constants

Central Manager Initialization Options

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

NSString *const CBCentralManagerOptionShowPowerAlertKey;
NSString *const CBCentralManagerOptionRestoreIdentifierKey;
Constants
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 NO.

Available in iOS 7.0 and later.

Declared in CBCentralManagerConstants.h.

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.

Declared in CBCentralManagerConstants.h.

Peripheral Scanning Options

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

NSString *const CBCentralManagerScanOptionAllowDuplicatesKey;
NSString *const CBCentralManagerScanOptionSolicitedServiceUUIDsKey;
Constants
CBCentralManagerScanOptionAllowDuplicatesKey

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

The value for this key is an NSNumber object. If YES, 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 NO, multiple discoveries of the same peripheral are coalesced into a single discovery event. If the key is not specified, the default value is NO.

Available in iOS 5.0 and later.

Declared in CBCentralManagerConstants.h.

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.

Declared in CBCentralManagerConstants.h.

Peripheral Connection Options

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

NSString *const CBConnectPeripheralOptionNotifyOnConnectionKey;
NSString *const CBConnectPeripheralOptionNotifyOnDisconnectionKey;
NSString *const CBConnectPeripheralOptionNotifyOnNotificationKey;
Constants
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 NO.

Available in iOS 6.0 and later.

Declared in CBCentralManagerConstants.h.

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

Available in iOS 5.0 and later.

Declared in CBCentralManagerConstants.h.

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

Available in iOS 6.0 and later.

Declared in CBCentralManagerConstants.h.

Central Manager State

Values representing the current state of a central manager object.

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

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

Available in iOS 5.0 and later.

Declared in CBCentralManager.h.

CBCentralManagerStateResetting

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

Available in iOS 5.0 and later.

Declared in CBCentralManager.h.

CBCentralManagerStateUnsupported

The platform does not support Bluetooth low energy.

Available in iOS 5.0 and later.

Declared in CBCentralManager.h.

CBCentralManagerStateUnauthorized

The app is not authorized to use Bluetooth low energy.

Available in iOS 5.0 and later.

Declared in CBCentralManager.h.

CBCentralManagerStatePoweredOff

Bluetooth is currently powered off.

Available in iOS 5.0 and later.

Declared in CBCentralManager.h.

CBCentralManagerStatePoweredOn

Bluetooth is currently powered on and available to use.

Available in iOS 5.0 and later.

Declared in CBCentralManager.h.