CBCentralManager Class Reference

Inherits from	NSObject
Conforms to	NSObject (NSObject)
Framework	/System/Library/Frameworks/CoreBluetooth.framework
Availability	Available in iOS 5.0 and later.
Declared in	CBCentralManager.h
Related sample code	BTLE Central Peripheral Transfer CoreBluetooth Temperature Sensor

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

Related Sample Code

BTLE Central Peripheral Transfer

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 are canceled automatically when peripheral is deallocated.

Availability

Available in iOS 5.0 and later.

Related Sample Code

CoreBluetooth Temperature Sensor

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 its 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

retrieveConnectedPeripherals

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

- (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 via the connectPeripheral:options: method before they can be used.

Availability

Available in iOS 5.0 and later.

Declared In

CBCentralManager.h

retrievePeripherals:

Retrieves a list of known peripherals by their UUIDs.

- (void)retrievePeripherals:(NSArray *)peripheralUUIDs

Parameters

peripheralUUIDs: An array of CFUUIDRef objects from which CBPeripheral objects can be retrieved. Since 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.

Availability

Available in iOS 5.0 and later.

Declared In

CBCentralManager.h

scanForPeripheralsWithServices:options:

Scans for peripherals that are advertising service(s).

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

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 services that the app is interested in (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.

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

Peripheral Scanning Option

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

NSString *const CBCentralManagerScanOptionAllowDuplicatesKey;

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, multiple discoveries of the same peripheral are coalesced into a single discovery event. If NO, filtering is disabled. Disabling this filtering can have an adverse effect on battery life and should be used only if necessary. If the key is not specified, the default value is YES.

Available in iOS 5.0 and later.

Declared in CBCentralManager.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 a 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 CBCentralManager.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 a NSNumber. 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 CBCentralManager.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 a 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 CBCentralManager.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.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.