iOS Developer Library

Developer

CBPeripheralManager Class Reference

Options
Deployment Target:

On This Page
Language:

CBPeripheralManager

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

Inheritance


Conforms To


Import Statement


import CoreBluetooth @import CoreBluetooth;

Availability


Available in iOS 6.0 and later.
  • Initializes the peripheral manager with a specified delegate and dispatch queue.

    Declaration

    Swift

    init!(delegate delegate: CBPeripheralManagerDelegate!, queue queue: dispatch_queue_t!)

    Objective-C

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    init!(delegate delegate: CBPeripheralManagerDelegate!, queue queue: dispatch_queue_t!, options options: [NSObject : AnyObject]!)

    Objective-C

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later.

  • delegate delegate Property

    The delegate object specified to receive peripheral events.

    Declaration

    Swift

    weak var delegate: CBPeripheralManagerDelegate!

    Objective-C

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

    Discussion

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • state state Property

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

    Declaration

    Swift

    var state: CBPeripheralManagerState { get }

    Objective-C

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    class func authorizationStatus() -> CBPeripheralManagerAuthorizationStatus

    Objective-C

    + (CBPeripheralManagerAuthorizationStatus)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.

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func addService(_ service: CBMutableService!)

    Objective-C

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • Removes a specified published service from the local GATT database.

    Declaration

    Swift

    func removeService(_ service: CBMutableService!)

    Objective-C

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • Removes all published services from the local GATT database.

    Declaration

    Swift

    func removeAllServices()

    Objective-C

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • Advertises peripheral manager data.

    Declaration

    Swift

    func startAdvertising(_ advertisementData: [NSObject : AnyObject]!)

    Objective-C

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • Stops advertising peripheral manager data.

    Declaration

    Swift

    func stopAdvertising()

    Objective-C

    - (void)stopAdvertising

    Discussion

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    var isAdvertising: Bool { get }

    Objective-C

    @property(readonly) BOOL isAdvertising

    Discussion

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    func updateValue(_ value: NSData!, forCharacteristic characteristic: CBMutableCharacteristic!, onSubscribedCentrals centrals: [AnyObject]!) -> Bool

    Objective-C

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

    YEStrue if the update is successfully sent to the subscribed central or centrals. NOfalse 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 NOfalse 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.

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

    See Also

    peripheralManager:central:didSubscribeToCharacteristic:
    peripheralManager:central:didUnsubscribeFromCharacteristic:

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

    Declaration

    Swift

    func setDesiredConnectionLatency(_ latency: CBPeripheralManagerConnectionLatency, forCentral central: CBCentral!)

    Objective-C

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

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    let CBPeripheralManagerOptionShowPowerAlertKey: NSString! let CBPeripheralManagerOptionRestoreIdentifierKey: NSString!

    Objective-C

    NSString *const CBPeripheralManagerOptionShowPowerAlertKey; NSString *const CBPeripheralManagerOptionRestoreIdentifierKey;

    Constants

    • CBPeripheralManagerOptionShowPowerAlertKey

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

      Available in iOS 7.0 and later.

    • CBPeripheralManagerOptionRestoreIdentifierKey

      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.

    Import Statement

  • Values representing the current state of the peripheral manager.

    Declaration

    Swift

    enum CBPeripheralManagerState : Int { case Unknown case Resetting case Unsupported case Unauthorized case PoweredOff case PoweredOn }

    Objective-C

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

    Constants

    • Unknown

      CBPeripheralManagerStateUnknown

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

      Available in iOS 6.0 and later.

    • Resetting

      CBPeripheralManagerStateResetting

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

      Available in iOS 6.0 and later.

    • Unsupported

      CBPeripheralManagerStateUnsupported

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

      Available in iOS 6.0 and later.

    • Unauthorized

      CBPeripheralManagerStateUnauthorized

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

      Available in iOS 6.0 and later.

    • PoweredOff

      CBPeripheralManagerStatePoweredOff

      Bluetooth is currently powered off.

      Available in iOS 6.0 and later.

    • PoweredOn

      CBPeripheralManagerStatePoweredOn

      Bluetooth is currently powered on and is available to use.

      Available in iOS 6.0 and later.

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • Values representing the connection latency of the peripheral manager.

    Declaration

    Swift

    enum CBPeripheralManagerConnectionLatency : Int { case Low case Medium case High }

    Objective-C

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

    Constants

    • Low

      CBPeripheralManagerConnectionLatencyLow

      Rapid communication has priority over battery life.

      Available in iOS 6.0 and later.

    • Medium

      CBPeripheralManagerConnectionLatencyMedium

      A balance exits between communication frequency and battery life.

      Available in iOS 6.0 and later.

    • High

      CBPeripheralManagerConnectionLatencyHigh

      Extending battery life has priority over rapid communication.

      Available in iOS 6.0 and later.

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 6.0 and later.

  • Values representing the current authorization state of the peripheral manager.

    Declaration

    Swift

    enum CBPeripheralManagerAuthorizationStatus : Int { case NotDetermined case Restricted case Denied case Authorized }

    Objective-C

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

    Constants

    • NotDetermined

      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.

    • Restricted

      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.

    • Denied

      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.

    • Authorized

      CBPeripheralManagerAuthorizationStatusAuthorized

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

      Available in iOS 7.0 and later.

    Import Statement

    import CoreBluetooth

    Availability

    Available in iOS 7.0 and later.