CBPeripheralDelegate Protocol Reference

Conforms to
NSObject
Framework
/System/Library/Framework/CoreBluetooth.framework
Availability
Available in iOS 5.0 and later.
Declared in
CBPeripheral.h
Related sample code

Overview

The delegate of a CBPeripheral object must adopt the CBPeripheralDelegate protocol. The delegate uses this protocol’s methods to monitor the discovery, exploration, and interaction of a remote peripheral’s services and properties. There are no required methods in this protocol.

Tasks

Discovering Services

Discovering Characteristics and Characteristic Descriptors

Retrieving Characteristic and Characteristic Descriptor Values

Writing Characteristic and Characteristic Descriptor Values

Managing Notifications for a Characteristic’s Value

Retrieving a Peripheral’s Received Signal Strength Indicator (RSSI) Data

Monitoring Changes to a Peripheral’s Name or Services

Instance Methods

peripheral:didDiscoverCharacteristicsForService:error:

Invoked when you discover the characteristics of a specified service.

- (void)peripheral:(CBPeripheral *)peripheral didDiscoverCharacteristicsForService:(CBService *)service error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

service

The service that the characteristics belong to.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the discoverCharacteristics:forService: method. If the characteristics of the specified service are successfully discovered, you can access them through the service's characteristics property. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheral:didDiscoverDescriptorsForCharacteristic:error:

Invoked when you discover the descriptors of a specified characteristic.

- (void)peripheral:(CBPeripheral *)peripheral didDiscoverDescriptorsForCharacteristic:(CBCharacteristic *)characteristic error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

characteristic

The characteristic that the characteristic descriptors belong to.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the discoverDescriptorsForCharacteristic: method. If the characteristic descriptors of the specified characteristic are successfully discovered, you can access them through the characteristic’s descriptors property. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheral:didDiscoverIncludedServicesForService:error:

Invoked when you discover the included services of a specified service.

- (void)peripheral:(CBPeripheral *)peripheral didDiscoverIncludedServicesForService:(CBService *)service error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

service

The CBService object containing the included service.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when you app calls the discoverIncludedServices:forService: method. If the included services of the specified service are successfully discovered, you can access them through the service’s includedServices property. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheral:didDiscoverServices:

Invoked when you discover the peripheral’s available services.

- (void)peripheral:(CBPeripheral *)peripheral didDiscoverServices:(NSError *)error
Parameters
peripheral

The peripheral that the services belong to.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the discoverServices: method. If the services of the peripheral are successfully discovered, you can access them through the peripheral’s services property. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheral:didUpdateNotificationStateForCharacteristic:error:

Invoked when the peripheral receives a request to start or stop providing notifications for a specified characteristic’s value.

- (void)peripheral:(CBPeripheral *)peripheral didUpdateNotificationStateForCharacteristic:(CBCharacteristic *)characteristic error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

characteristic

The characteristic for which notifications of its value are to be configured.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the setNotifyValue:forCharacteristic: method. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheral:didUpdateValueForCharacteristic:error:

Invoked when you retrieve a specified characteristic’s value, or when the peripheral device notifies your app that the characteristic’s value has changed.

- (void)peripheral:(CBPeripheral *)peripheral didUpdateValueForCharacteristic:(CBCharacteristic *)characteristic error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

characteristic

The characteristic whose value has been retrieved.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the readValueForCharacteristic: method, or when the peripheral notifies your app that the value of the characteristic for which notifications and indications are enabled (via a successful call to setNotifyValue:forCharacteristic:) has changed. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheral:didUpdateValueForDescriptor:error:

Invoked when you retrieve a specified characteristic descriptor’s value.

- (void)peripheral:(CBPeripheral *)peripheral didUpdateValueForDescriptor:(CBDescriptor *)descriptor error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

descriptor

The characteristic descriptor whose value has been retrieved.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the readValueForDescriptor: method. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheral:didWriteValueForCharacteristic:error:

Invoked when you write data to a characteristic’s value.

- (void)peripheral:(CBPeripheral *)peripheral didWriteValueForCharacteristic:(CBCharacteristic *)characteristic error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

characteristic

The characteristic whose value has been written.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked only when your app calls the writeValue:forCharacteristic:type: method with the CBCharacteristicWriteWithResponse constant specified as the write type. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheral:didWriteValueForDescriptor:error:

Invoked when you write data to a characteristic descriptor’s value.

- (void)peripheral:(CBPeripheral *)peripheral didWriteValueForDescriptor:(CBDescriptor *)descriptor error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

descriptor

The characteristic descriptor whose value has been written.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the writeValue:forDescriptor: method. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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

peripheralDidInvalidateServices:

Invoked when a peripheral’s services have changed.

- (void)peripheralDidInvalidateServices:(CBPeripheral *)peripheral
Parameters
peripheral

The peripheral providing this information.

Discussion

Whenever any service of a peripheral changes, this method is invoked and all services that are visible to the app are invalidated. As a result, to access any services that are available on the peripheral, you must rediscover them via the discoverServices: method.

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

peripheralDidUpdateName:

Invoked when a peripheral’s name changes.

- (void)peripheralDidUpdateName:(CBPeripheral *)peripheral
Parameters
peripheral

The peripheral providing this information.

Discussion

The method is invoked whenever the peripheral device’s Generic Access Profile (GAP) device name has changed. Since a peripheral device can change its GAP device name, you can implement this method if your app needs to display the current name of the peripheral device.

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

peripheralDidUpdateRSSI:error:

Invoked when you retrieve the value of the peripheral’s current RSSI while it is connected to the central manager.

- (void)peripheralDidUpdateRSSI:(CBPeripheral *)peripheral error:(NSError *)error
Parameters
peripheral

The peripheral providing this information.

error

If an error occurred, the cause of the failure.

Discussion

This method is invoked when your app calls the readRSSI method. If successful, the error parameter is nil. If unsuccessful, the error parameter returns the cause of the failure.

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


© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)

Did this document help you? Yes It's good, but... Not helpful...