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.

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.

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

    Declaration

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

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

    Declaration

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

  • delegate Property

    The delegate object specified to receive peripheral events.

    Declaration

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

    Discussion

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

  • state Property

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

    Declaration

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

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

    Declaration

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

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

    Declaration

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

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

    Declaration

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

  • Removes all published services from the local GATT database.

    Declaration

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

  • Advertises peripheral manager data.

    Declaration

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

  • Stops advertising peripheral manager data.

    Declaration

    - (void)stopAdvertising

    Discussion

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

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

    Declaration

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

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

    Declaration

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

    See Also

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

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

    Declaration

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

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

    Declaration

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

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

  • Values representing the current state of the peripheral manager.

    Declaration

    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.

    • CBPeripheralManagerStateResetting

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

    • CBPeripheralManagerStateUnsupported

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

    • CBPeripheralManagerStateUnauthorized

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

    • CBPeripheralManagerStatePoweredOff

      Bluetooth is currently powered off.

    • CBPeripheralManagerStatePoweredOn

      Bluetooth is currently powered on and is available to use.

  • Values representing the connection latency of the peripheral manager.

    Declaration

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

    Constants

    • CBPeripheralManagerConnectionLatencyLow

      Rapid communication has priority over battery life.

    • CBPeripheralManagerConnectionLatencyMedium

      A balance exits between communication frequency and battery life.

    • CBPeripheralManagerConnectionLatencyHigh

      Extending battery life has priority over rapid communication.

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

    Declaration

    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.

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

    • CBPeripheralManagerAuthorizationStatusDenied

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

    • CBPeripheralManagerAuthorizationStatusAuthorized

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