iOS Developer Library

Developer

CBPeripheralManagerDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

CBPeripheralManagerDelegate

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.

Inheritance


Not Applicable

Import Statement


Swift

import CoreBluetooth

Objective-C

@import CoreBluetooth;

Availability


Available in iOS 6.0 and later.
  • Invoked when the peripheral manager's state is updated. (required)

    Declaration

    Swift

    func peripheralManagerDidUpdateState(_ peripheral: CBPeripheralManager!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func peripheralManager(_ peripheral: CBPeripheralManager!, willRestoreState dict: [NSObject : AnyObject]!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    optional func peripheralManager(_ peripheral: CBPeripheralManager!, didAddService service: CBService!, error error: NSError!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func peripheralManagerDidStartAdvertising(_ peripheral: CBPeripheralManager!, error error: NSError!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func peripheralManager(_ peripheral: CBPeripheralManager!, central central: CBCentral!, didSubscribeToCharacteristic characteristic: CBCharacteristic!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func peripheralManager(_ peripheral: CBPeripheralManager!, central central: CBCentral!, didUnsubscribeFromCharacteristic characteristic: CBCharacteristic!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func peripheralManagerIsReadyToUpdateSubscribers(_ peripheral: CBPeripheralManager!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func peripheralManager(_ peripheral: CBPeripheralManager!, didReceiveReadRequest request: CBATTRequest!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func peripheralManager(_ peripheral: CBPeripheralManager!, didReceiveWriteRequests requests: [AnyObject]!)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreBluetooth;

    Swift

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    let CBPeripheralManagerRestoredStateServicesKey: NSString! let CBPeripheralManagerRestoredStateAdvertisementDataKey: NSString!

    Objective-C

    NSString *const CBPeripheralManagerRestoredStateServicesKey; NSString *const CBPeripheralManagerRestoredStateAdvertisementDataKey;

    Constants

    • CBPeripheralManagerRestoredStateServicesKey

      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.

    • CBPeripheralManagerRestoredStateAdvertisementDataKey

      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.