CBPeripheralManagerDelegate Protocol Reference

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

Overview

The delegate of a CBPeripheralManager object must adopt the CBPeripheralManagerDelegate protocol, a protocol consisting of numerous optional methods and one required method. The protocol’s optional methods are used by the delegate to verify publishing and advertising, and to monitor read, write, and subscription requests from remote central devices. The protocol’s required method, which indicates whether the peripheral manager is available, is called when the peripheral manager’s state is updated.

Tasks

Monitoring Changes to the Peripheral Manager’s State

Adding Services

Advertising Peripheral Data

Monitoring Subscriptions to Characteristic Values

Receiving Read and Write Requests

Instance Methods

peripheralManager:central:didSubscribeToCharacteristic:

Invoked when a remote central device subscribes to a characteristic’s value.

- (void)peripheralManager:(CBPeripheralManager *)peripheral central:(CBCentral *)central didSubscribeToCharacteristic:(CBCharacteristic *)characteristic
Parameters
peripheral

The peripheral manager providing this information.

central

The remote central device that subscribed to the characteristic’s value.

characteristic

The characteristic whose value has been subscribed to.

Discussion

This method is invoked when a remote central device subscribes to the value of one of the local peripheral’s characteristics, by enabling notifications or indications on the characteristic’s value. You should use the invocation of this method as a cue to start sending the subscribed central updates as the characteristic’s value changes. To send updated characteristic values to subscribed centrals, use the updateValue:forCharacteristic:onSubscribedCentrals: method of the CBPeripheralManager class.

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

peripheralManager:central:didUnsubscribeFromCharacteristic:

Invoked when a remote central device unsubscribes from a characteristic’s value.

- (void)peripheralManager:(CBPeripheralManager *)peripheral central:(CBCentral *)central didUnsubscribeFromCharacteristic:(CBCharacteristic *)characteristic
Parameters
peripheral

The peripheral manager providing this information.

central

The remote central device that subscribed to the characteristic’s value.

characteristic

The characteristic whose value has been unsubscribed from.

Discussion

This method is invoked when a remote central device unsubscribes from the value of one of the local peripheral’s characteristics, by disabling notifications or indications on the characteristic’s value. You should use the invocation of this method as a cue to stop sending the subscribed central updates as the characteristic’s value changes.

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

peripheralManager:didAddService:error:

Invoked when you publish a service, and any of its associated characteristics and characteristic descriptors, to the local Generic Attribute Profile (GATT) database.

- (void)peripheralManager:(CBPeripheralManager *)peripheral didAddService:(CBService *)service error:(NSError *)error
Parameters
peripheral

The peripheral manager providing this information.

service

The service that was added to the local GATT database.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the addService: method to publish a service to the local peripheral’s GATT database. If the service is successfully published to the local database, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheralManager:didReceiveReadRequest:

Invoked when a local peripheral device receives an Attribute Protocol (ATT) read request for a characteristic that has a dynamic value.

- (void)peripheralManager:(CBPeripheralManager *)peripheral didReceiveReadRequest:(CBATTRequest *)request
Parameters
peripheral

The peripheral manager providing this information.

request

A CBATTRequest object that represents a request to read a characteristic’s value.

Discussion

Each time this method is invoked, you call the respondToRequest:withResult: method of the CBPeripheralManager class exactly once to respond to the read request.

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

peripheralManager:didReceiveWriteRequests:

Invoked when a local peripheral device receives an Attribute Protocol (ATT) write request for a characteristic that has a dynamic value.

- (void)peripheralManager:(CBPeripheralManager *)peripheral didReceiveWriteRequests:(NSArray *)requests
Parameters
peripheral

The peripheral manager providing this information.

requests

A list of one or more CBATTRequest objects, each representing a request to write the value of a characteristic.

Discussion

In the same way that you respond to a read request, each time this method is invoked, you call the respondToRequest:withResult: method of the CBPeripheralManager class exactly once. If the requests parameter contains multiple requests, treat them as you would a single request—if any individual request cannot be fulfilled, you should not fulfill any of them. Instead, call the respondToRequest:withResult: method immediately, and provide a result that indicates the cause of the failure.

When you respond to a write request, note that the first parameter of the respondToRequest:withResult: method expects a single CBATTRequest object, even though you received an array of them from the peripheralManager:didReceiveWriteRequests: method. To respond properly, pass in the first request of the requests array.

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

peripheralManager:willRestoreState:

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

- (void)peripheralManager:(CBPeripheralManager *)peripheral willRestoreState:(NSDictionary *)dict
Parameters
peripheral

The peripheral manager providing this information.

dict

A dictionary containing information about the peripheral manager that was preserved by the system at the time the app was terminated. For the available keys to this dictionary, see “Peripheral 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.

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

peripheralManagerDidStartAdvertising:error:

Invoked when you start advertising the local peripheral device’s data.

- (void)peripheralManagerDidStartAdvertising:(CBPeripheralManager *)peripheral error:(NSError *)error
Parameters
peripheral

The peripheral manager providing this information.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the startAdvertising: method to begin advertising the local peripheral device’s data. If successful, the error parameter is nil. If there is a problem advertising the data, the error parameter returns the cause of the failure.

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

peripheralManagerDidUpdateState:

Invoked when the peripheral manager's state is updated. (required)

- (void)peripheralManagerDidUpdateState:(CBPeripheralManager *)peripheral
Parameters
peripheral

The peripheral 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 local peripheral device. Issue commands to the peripheral manager only when the state of the peripheral manager is powered on, as indicated by the CBPeripheralManagerStatePoweredOn constant. A state with a value lower than CBPeripheralManagerStatePoweredOn implies that advertising has stopped and that any connected centrals have been disconnected. If the state moves below CBPeripheralManagerStatePoweredOff, advertising has stopped and must be explicitly restarted. In addition, the local database is cleared and all services must be explicitly added again. For a complete list and discussion of the possible values representing the state of the peripheral manager, see the CBPeripheralManagerState enumeration in CBPeripheralManager Class Reference.

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

peripheralManagerIsReadyToUpdateSubscribers:

Invoked when a local peripheral device is again ready to send characteristic value updates. (required)

- (void)peripheralManagerIsReadyToUpdateSubscribers:(CBPeripheralManager *)peripheral
Parameters
peripheral

The peripheral manager providing this information.

Discussion

When a call to the updateValue:forCharacteristic:onSubscribedCentrals: method fails because the underlying queue used to transmit the updated characteristic value is full, the peripheralManagerIsReadyToUpdateSubscribers: method is invoked when more space in the transmit queue becomes available. You can then implement this delegate method to resend the value.

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

Constants

Peripheral Manager State Restoration Options

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

NSString *const CBPeripheralManagerRestoredStateServicesKey;
NSString *const CBPeripheralManagerRestoredStateAdvertisementDataKey;
Constants
CBPeripheralManagerRestoredStateServicesKey

An array (an instance of NSArray) of CBMutableService objects that contains all of the services that were published to the local peripheral’s database at the time the app was terminated by the system.

All the information about a service is restored, including any included services, characteristics, characteristic descriptors, and subscribed centrals.

Available in iOS 7.0 and later.

Declared in CBPeripheralManagerConstants.h.

CBPeripheralManagerRestoredStateAdvertisementDataKey

A dictionary (an instance of NSDictionary) containing the data that the peripheral manager was advertising at the time the app was terminated by the system.

Available in iOS 7.0 and later.

Declared in CBPeripheralManagerConstants.h.