CBPeripheralManager Class Reference

Inherits from
Conforms to
Availability
Available in iOS 6.0 and later.
Companion guide
Declared in
CBPeripheralManager.h
CBPeripheralManagerConstants.h
Related sample code

Overview

CBPeripheralManager objects are used to manage published services within the local peripheral device’s Generic Attribute Profile (GATT) database and to advertise these services to central devices (represented by CBCentral objects). While a service is in the database, it is visible to, and can be accessed by, any connected central. That said, if your app has not specified the bluetooth-peripheral background mode, the contents of its services become disabled when it is in the background or in a suspended state; any remote central trying to access the service’s characteristic value or characteristic descriptors receives an error.

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

Tasks

Initializing a Peripheral Manager

Monitoring the State of a Peripheral Manager

Adding and Removing Services

Managing Advertising

Sending Updates of a Characteristic’s Value

Responding to Read and Write Requests

Setting Connection Latency

Properties

delegate

The delegate object specified to receive peripheral events.

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

For information about how to implement your peripheral manager delegate, see CBPeripheralManagerDelegate Protocol Reference.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

isAdvertising

A Boolean value indicating whether the peripheral is currently advertising data. (read-only)

@property(readonly) BOOL isAdvertising
Discussion

YES if the peripheral is currently advertising data as a result of you successfully calling the startAdvertising: method. NO if the peripheral is not currently advertising data.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

state

The current state of the peripheral manager. (read-only)

@property(readonly) CBPeripheralManagerState state
Discussion

When a peripheral manager object is initially created, the default value of this property is CBPeripheralManagerStateUnknown. As the peripheral manager’s state changes, the peripheral manager updates the value of this property and calls the peripheralManagerDidUpdateState: method of its delegate object. For a list of the possible values representing the state of the peripheral manager, see “Peripheral Manager State.”

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

Class Methods

authorizationStatus

Returns the app’s authorization status for sharing data while in the background state.

+ (CBPeripheralAuthorizationStatus)authorizationStatus
Return Value

A value indicating whether the app is authorized to share data using Bluetooth services while in the background. For a list of the possible values, see “Peripheral Manager Authorization Status.”

Discussion

The authorization status of a given app is managed by the system and determined by several factors. Apps must be explicitly authorized to share data using Bluetooth services while in the background state. The system automatically displays a request for user authorization when your app first attempts to use Bluetooth services to share data.

Calling this method does not prompt the user for access. Instead, you use this method to detect restricted access and simply hide any affected UI features from the user.

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

Instance Methods

addService:

Publishes a service and any of its associated characteristics and characteristic descriptors to the local GATT database.

- (void)addService:(CBMutableService *)service
Parameters
service

The service you want to publish.

Discussion

When you add a service to the database, the peripheral manager calls the peripheralManager:didAddService:error: method of its delegate object. If the service contains any included services, you must publish them first.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

initWithDelegate:queue:

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

- (id)initWithDelegate:(id<CBPeripheralManagerDelegate>)delegate queue:(dispatch_queue_t)queue
Parameters
delegate

The delegate to receive the peripheral role events.

queue

The dispatch queue for dispatching the peripheral role events. If the value is nil, the peripheral manager dispatches peripheral role events using the main queue.

Return Value

Returns a newly initialized peripheral manager.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

initWithDelegate:queue:options:

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

- (id)initWithDelegate:(id<CBPeripheralManagerDelegate>)delegate queue:(dispatch_queue_t)queue options:(NSDictionary *)options
Parameters
delegate

The delegate to receive the peripheral role events.

queue

The dispatch queue for dispatching the peripheral role events. If the value is nil, the peripheral manager dispatches peripheral role events using the main queue.

options

An optional dictionary containing initialization options for a peripheral manager. For available options, see “Peripheral Manager Initialization Options.”

Return Value

Returns a newly initialized peripheral manager.

Discussion

This method is the designated initializer for the CBPeripheralManager class.

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

removeAllServices

Removes all published services from the local GATT database.

- (void)removeAllServices
Discussion

Because the GATT database is shared among apps on the local peripheral device, this method removes only the services that you have added using the addService: method. Any services that have been published by other apps on the local peripheral device are not removed from the GATT database.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

removeService:

Removes a specified published service from the local GATT database.

- (void)removeService:(CBMutableService *)service
Parameters
service

The service you want to remove.

Discussion

Because the GATT database is shared among apps on the local peripheral device, more than one instance of a service may exist in the database. As a result, this method removes only the instance of the service that your app added to the database (using the addService: method). If the service is included by any other services, you must remove them first.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

respondToRequest:withResult:

Responds to a read or write request from a connected central.

- (void)respondToRequest:(CBATTRequest *)request withResult:(CBATTError)result
Parameters
request

The read or write request that was received from the connected central. For more information about read and write requests, see CBATTRequest Class Reference.

result

The result of attempting to fulfill the request. For a list of possible results, see Core Bluetooth Constants Reference.

Discussion

When the peripheral manager receives a request (represented as a CBATTRequest object) from a connected central to read or write a characteristic’s value, it calls the peripheralManager:didReceiveReadRequest: or peripheralManager:didReceiveWriteRequests: method of its delegate object. Each time one of these delegate methods is called, you call this method to respond to the corresponding read or write request.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

setDesiredConnectionLatency:forCentral:

Sets the desired connection latency for an existing connection to a central device.

- (void)setDesiredConnectionLatency:(CBPeripheralManagerConnectionLatency)latency forCentral:(CBCentral *)central
Parameters
latency

The desired connection latency. For a list of the possible connection latency values that you may set for the peripheral manager, see “Peripheral Manager Connection Latency.”

central

The central that the peripheral manager is currently connected to.

Discussion

The latency of a peripheral-central connection controls how frequently messages can be exchanged between the peripheral and the central to which the peripheral is connected. By setting a desired connection latency, you manage the relationship between the frequency with which data is exchanged and the resulting battery performance of the peripheral device. When you call this method to set the connection latency, note that connection latency changes are not guaranteed. And so, the resultant latency may vary. If you do not explicitly set a latency, the connection latency is set to the latency that was chosen by the central device when the connection was first established. Typically, it is not necessary to change the connection latency.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

startAdvertising:

Advertises peripheral manager data.

- (void)startAdvertising:(NSDictionary *)advertisementData
Parameters
advertisementData

An optional dictionary containing the data you want to advertise. The possible keys of an advertisementData dictionary are detailed in CBCentralManagerDelegate Protocol Reference. That said, only two of the keys are supported for peripheral manager objects: CBAdvertisementDataLocalNameKey and CBAdvertisementDataServiceUUIDsKey.

Discussion

When you start advertising peripheral data, the peripheral manager calls the peripheralManagerDidStartAdvertising:error: method of its delegate object.

Data advertising is done on a “best effort” basis, because space is limited and there may be multiple apps advertising simultaneously. While your app is in the foreground, it can use up to 28 bytes of space in the initial advertisement data for any combination of the supported advertising data keys. If this space is used up, there are an additional 10 bytes of space in the scan response that can be used only for the local name (represented by the value of the CBAdvertisementDataLocalNameKey key). Note that these sizes do not include the 2 bytes of header information that are required for each new data type. Any service universally unique identifiers (UUIDs) contained in the value of the CBAdvertisementDataServiceUUIDsKey key that do not fit in the allotted space are added to a special “overflow” area; they can be discovered only by an iOS device that is explicitly scanning for them. While your app is in the background, the local name is not advertised and all service UUIDs are placed in the overflow area. The exact format of advertising and response data is defined in the Bluetooth 4.0 specification, Volume 3, Part C, Section 11.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

stopAdvertising

Stops advertising peripheral manager data.

- (void)stopAdvertising
Discussion

Call this method when you no longer want to advertise peripheral manager data.

Availability
  • Available in iOS 6.0 and later.
Declared In
CBPeripheralManager.h

updateValue:forCharacteristic:onSubscribedCentrals:

Sends an updated characteristic value to one or more subscribed centrals, via a notification or indication.

- (BOOL)updateValue:(NSData *)value forCharacteristic:(CBMutableCharacteristic *)characteristic onSubscribedCentrals:(NSArray *)centrals
Parameters
value

The characteristic value you want to send via a notification or indication.

characteristic

The characteristic whose value has changed.

centrals

A list of centrals (represented by CBCentral objects) that have subscribed to receive updates of the characteristic’s value. If nil, all subscribed centrals are updated. Centrals that have not subscribed to a characteristic’s value are ignored.

Return Value

YES if the update is successfully sent to the subscribed central or centrals. NO if the update is not successfully sent because the underlying transmit queue is full.

Discussion

You use this method to send updates of a characteristic’s value—through a notification or indication—to selected centrals that have subscribed to that characteristic’s value. If the method returns NO because the underlying transmit queue is full, the peripheral manager calls the peripheralManagerIsReadyToUpdateSubscribers: method of its delegate object when more space in the transmit queue becomes available. After this delegate method is called, you may resend the update.

If the length of the value parameter exceeds the length of the maximumUpdateValueLength property of a subscribed CBCentral, the value parameter is truncated accordingly.

Availability
  • Available in iOS 6.0 and later.
See Also
  • peripheralManager:central:didSubscribeToCharacteristic:
  • peripheralManager:central:didUnsubscribeFromCharacteristic:
Declared In
CBPeripheralManager.h

Constants

Peripheral Manager Initialization Options

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

NSString *const CBPeripheralManagerOptionShowPowerAlertKey;
NSString *const CBPeripheralManagerOptionRestoreIdentifierKey;
Constants
CBPeripheralManagerOptionShowPowerAlertKey

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

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

Available in iOS 7.0 and later.

Declared in CBPeripheralManagerConstants.h.

CBPeripheralManagerOptionRestoreIdentifierKey

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

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

Available in iOS 7.0 and later.

Declared in CBPeripheralManagerConstants.h.

Peripheral Manager State

Values representing the current state of the peripheral manager.

typedef enum {
   CBPeripheralManagerStateUnknown = 0,
   CBPeripheralManagerStateResetting,
   CBPeripheralManagerStateUnsupported,
   CBPeripheralManagerStateUnauthorized,
   CBPeripheralManagerStatePoweredOff,
   CBPeripheralManagerStatePoweredOn,
} CBPeripheralManagerState;
Constants
CBPeripheralManagerStateUnknown

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

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerStateResetting

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

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerStateUnsupported

The platform doesn't support the Bluetooth low energy peripheral/server role.

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerStateUnauthorized

The app is not authorized to use the Bluetooth low energy peripheral/server role.

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerStatePoweredOff

Bluetooth is currently powered off.

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerStatePoweredOn

Bluetooth is currently powered on and is available to use.

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

Peripheral Manager Connection Latency

Values representing the connection latency of the peripheral manager.

typedef enum {
   CBPeripheralManagerConnectionLatencyLow = 0,
   CBPeripheralManagerConnectionLatencyMedium,
   CBPeripheralManagerConnectionLatencyHigh,
} CBPeripheralManagerConnectionLatency;
Constants
CBPeripheralManagerConnectionLatencyLow

Rapid communication has priority over battery life.

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerConnectionLatencyMedium

A balance exits between communication frequency and battery life.

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerConnectionLatencyHigh

Extending battery life has priority over rapid communication.

Available in iOS 6.0 and later.

Declared in CBPeripheralManager.h.

Peripheral Manager Authorization Status

Values representing the current authorization state of the peripheral manager.

typedef enum {
   CBPeripheralManagerAuthorizationStatusNotDetermined = 0,
   CBPeripheralManagerAuthorizationStatusRestricted,
   CBPeripheralManagerAuthorizationStatusDenied,
   CBPeripheralManagerAuthorizationStatusAuthorized,
} CBPeripheralManagerAuthorizationStatus;
Constants
CBPeripheralManagerAuthorizationStatusNotDetermined

The user has not yet made a choice regarding whether this app can share data using Bluetooth services while in the background state.

Available in iOS 7.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerAuthorizationStatusRestricted

This app is not authorized to share data using Bluetooth services while in the background state. The user cannot change this app’s status, possibly due to active restrictions such as parental controls being in place.

Available in iOS 7.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerAuthorizationStatusDenied

The user explicitly denied this app from sharing data using Bluetooth services while in the background state.

Available in iOS 7.0 and later.

Declared in CBPeripheralManager.h.

CBPeripheralManagerAuthorizationStatusAuthorized

This app is authorized to share data using Bluetooth services while in the background state.

Available in iOS 7.0 and later.

Declared in CBPeripheralManager.h.