YMSCBCentralManager Class Reference

Inherits from	NSObject
Conforms to	CBCentralManagerDelegate
Declared in	YMSCBCentralManager.h YMSCBCentralManager.m

Overview

Base class for defining a Bluetooth LE central.

YMSCBCentralManager holds an instance of CBCentralManager (manager) and implements the CBCentralManagerDelgate messages sent by manager.

This class provides ObjectiveC block-based callback support for peripheral scanning and retrieval.

YMSCBCentralManager is intended to be subclassed: the subclass would in turn be written to handle the set of BLE peripherals of interest to the application.

The subclass is typically implemented (though not necessarily) as a singleton, so that there is only one instance of CBCentralManager that is used by the application.

All discovered BLE peripherals are stored in the array ymsPeripherals.

Legacy Note: This class was previously named YMSCBAppService.

Properties

`delegate`

Pointer to delegate.

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

Discussion

Pointer to delegate.

The delegate object will be sent CBCentralManagerDelegate messages received by manager.

Declared In

YMSCBCentralManager.h

`manager`

The CBCentralManager object.

@property (atomic, strong) CBCentralManager *manager

Discussion

The CBCentralManager object.

In typical practice, there is only one instance of CBCentralManager and it is located in a singleton instance of YMSCBCentralManager. This class listens to CBCentralManagerDelegate messages sent by manager, which in turn forwards those messages to delegate.

Declared In

YMSCBCentralManager.h

`knownPeripheralNames`

Array of NSStrings to search to match CBPeripheral instances.

@property (atomic, strong) NSArray *knownPeripheralNames

Discussion

Array of NSStrings to search to match CBPeripheral instances.

Used in conjunction with isKnownPeripheral:. This value is typically initialized using initWithKnownPeripheralNames:queue:.

Declared In

YMSCBCentralManager.h

`isScanning`

Flag to determine if manager is scanning.

@property (atomic, assign) BOOL isScanning

Discussion

Flag to determine if manager is scanning.

Declared In

YMSCBCentralManager.h

`ymsPeripherals`

Array of YMSCBPeripheral instances.

@property (atomic, readonly, strong) NSArray *ymsPeripherals

Discussion

Array of YMSCBPeripheral instances.

This array holds all YMSCBPeripheral instances discovered or retrieved by manager.

Declared In

YMSCBCentralManager.h

`count`

Count of ymsPeripherals.

@property (atomic, readonly, assign) NSUInteger count

Discussion

Count of ymsPeripherals.

Declared In

YMSCBCentralManager.h

`version`

API version.

@property (atomic, readonly, assign) NSString *version

Discussion

API version.

Declared In

YMSCBCentralManager.h

`discoveredCallback`

Peripheral Discovered Callback

@property (atomic, copy) YMSCBDiscoverCallbackBlockType discoveredCallback

Discussion

Peripheral Discovered Callback

Declared In

YMSCBCentralManager.h

`retrievedCallback`

Peripheral Retreived Callback

@property (atomic, copy) YMSCBRetrieveCallbackBlockType retrievedCallback

Discussion

Peripheral Retreived Callback

Declared In

YMSCBCentralManager.h

`useStoredPeripherals`

If YES, then discovered peripheral UUIDs are stored in standardUserDefaults.

@property (atomic, assign) BOOL useStoredPeripherals

Discussion

If YES, then discovered peripheral UUIDs are stored in standardUserDefaults.

Declared In

YMSCBCentralManager.h

Initializing YMSCBCentralManager

`– initWithKnownPeripheralNames:queue:delegate:`

Constructor with array of known peripheral names.

- (instancetype)initWithKnownPeripheralNames:(NSArray *)nameList queue:(dispatch_queue_t)queue delegate:(id<CBCentralManagerDelegate>)delegate

Parameters

`nameList`	Array of peripheral names of type NSString.
`queue`	The dispatch queue to use to dispatch the central role events. If its value is nil, the central manager dispatches central role events using the main queue.
`delegate`	Delegate of this class instance.

Discussion

Constructor with array of known peripheral names.

By default, this constructor will not use stored peripherals from standardUserDefaults.

Declared In

YMSCBCentralManager.h

`– initWithKnownPeripheralNames:queue:useStoredPeripherals:delegate:`

Constructor with array of known peripheral names.

- (instancetype)initWithKnownPeripheralNames:(NSArray *)nameList queue:(dispatch_queue_t)queue useStoredPeripherals:(BOOL)useStore delegate:(id<CBCentralManagerDelegate>)delegate

Parameters

`nameList`	Array of peripheral names of type NSString.
`queue`	The dispatch queue to use to dispatch the central role events. If its value is nil, the central manager dispatches central role events using the main queue.
`useStore`	If YES, then discovered peripheral UUIDs are stored in standardUserDefaults.
`delegate`	Delegate of this class instance.

Discussion

Constructor with array of known peripheral names.

Declared In

YMSCBCentralManager.h

Peripheral Management

`– isKnownPeripheral:`

Determines if peripheral is known by this app service.

- (BOOL)isKnownPeripheral:(CBPeripheral *)peripheral

Parameters

`peripheral`	found or retrieved peripheral

Return Value

YES is peripheral is to be managed by this app service.

Discussion

Determines if peripheral is known by this app service.

Used in conjunction with knownPeripheralNames.

Declared In

YMSCBCentralManager.h

`– handleFoundPeripheral:`

Handler for discovered or found peripheral. This method is to be overridden.

- (void)handleFoundPeripheral:(CBPeripheral *)peripheral

Parameters

`peripheral`	CoreBluetooth peripheral instance

Discussion

Handler for discovered or found peripheral. This method is to be overridden.

Declared In

YMSCBCentralManager.h

`– peripheralAtIndex:`

Returns the YSMCBPeripheral instance from ymsPeripherals at index.

- (YMSCBPeripheral *)peripheralAtIndex:(NSUInteger)index

Parameters

`index`	An index within the bounds of ymsPeripherals.

Discussion

Returns the YSMCBPeripheral instance from ymsPeripherals at index.

Declared In

YMSCBCentralManager.h

`– addPeripheral:`

Add YMSCBPeripheral instance to ymsPeripherals.

- (void)addPeripheral:(YMSCBPeripheral *)yperipheral

Parameters

`yperipheral`	Instance of YMSCBPeripheral

Discussion

Add YMSCBPeripheral instance to ymsPeripherals.

Declared In

YMSCBCentralManager.h

`– removePeripheral:`

Remove yperipheral in ymsPeripherals and from standardUserDefaults if stored.

- (void)removePeripheral:(YMSCBPeripheral *)yperipheral

Parameters

`yperipheral`	Instance of YMSCBPeripheral

Discussion

Remove yperipheral in ymsPeripherals and from standardUserDefaults if stored.

Declared In

YMSCBCentralManager.h

`– removePeripheralAtIndex:`

Remove YMSCBPeripheral instance at index

- (void)removePeripheralAtIndex:(NSUInteger)index

Parameters

`index`	The index from which to remove the object in ymsPeripherals. The value must not exceed the bounds of the array.

Discussion

Remove YMSCBPeripheral instance at index

Declared In

YMSCBCentralManager.h

`– removeAllPeripherals`

Remove all YMSCBPeripheral instances

- (void)removeAllPeripherals

Discussion

Remove all YMSCBPeripheral instances

Declared In

YMSCBCentralManager.h

`– findPeripheral:`

Find YMSCBPeripheral instance matching peripheral

- (YMSCBPeripheral *)findPeripheral:(CBPeripheral *)peripheral

Parameters

`peripheral`	peripheral corresponding with YMSCBPeripheral

Return Value

instance of YMSCBPeripheral

Discussion

Find YMSCBPeripheral instance matching peripheral

Declared In

YMSCBCentralManager.h

Scanning for Peripherals

`– startScan`

Start CoreBluetooth scan for peripherals. This method is to be overridden.

- (void)startScan

Discussion

Start CoreBluetooth scan for peripherals. This method is to be overridden.

The implementation of this method in a subclass must include the call to scanForPeripheralsWithServices:options:

Declared In

YMSCBCentralManager.h

`– scanForPeripheralsWithServices:options:`

Wrapper around the method scanForPeripheralWithServices:options: in CBCentralManager.

- (void)scanForPeripheralsWithServices:(NSArray *)serviceUUIDs options:(NSDictionary *)options

Parameters

`serviceUUIDs`	An array of CBUUIDs the app is interested in.
`options`	A dictionary to customize the scan, see CBCentralManagerScanOptionAllowDuplicatesKey.

Discussion

Wrapper around the method scanForPeripheralWithServices:options: in CBCentralManager.

If this method is invoked without involving a callback block, you must implement handleFoundPeripheral:.

Declared In

YMSCBCentralManager.h

`– scanForPeripheralsWithServices:options:withBlock:`

Scans for peripherals that are advertising service(s), invoking a callback block for each peripheral that is discovered.

- (void)scanForPeripheralsWithServices:(NSArray *)serviceUUIDs options:(NSDictionary *)options withBlock:(void ( ^ ) ( CBPeripheral *peripheral , NSDictionary *advertisementData , NSNumber *RSSI , NSError *error ))discoverCallback

Parameters

serviceUUIDs

An array of CBUUIDs the app is interested in.

options

A dictionary to customize the scan, see CBCentralManagerScanOptionAllowDuplicatesKey.

discoverCallback

Callback block to execute upon discovery of a peripheral. The parameters of discoverCallback are:

peripheral - the discovered peripheral.
advertisementData - A dictionary containing any advertisement data.
RSSI - The current received signal strength indicator (RSSI) of the peripheral, in decibels.
error - The cause of a failure, if any.

Discussion

Scans for peripherals that are advertising service(s), invoking a callback block for each peripheral that is discovered.

Declared In

YMSCBCentralManager.h

`– stopScan`

Stop CoreBluetooth scan for peripherals.

- (void)stopScan

Discussion

Stop CoreBluetooth scan for peripherals.

Declared In

YMSCBCentralManager.h

Retrieve Peripherals

`– retrievePeripheralsWithIdentifiers:`

Retrieves a list of known peripherals by their UUIDs.

- (NSArray *)retrievePeripheralsWithIdentifiers:(NSArray *)identifiers

Parameters

`identifiers`	A list of NSUUID objects.

Return Value

A list of peripherals.

Discussion

Retrieves a list of known peripherals by their UUIDs.

Declared In

YMSCBCentralManager.h

`– retrieveConnectedPeripheralsWithServices:`

Retrieves a list of the peripherals currently connected to the system and handles them using handleFoundPeripheral:

- (NSArray *)retrieveConnectedPeripheralsWithServices:(NSArray *)serviceUUIDS

Parameters

`serviceUUIDS`	A list of NSUUID services

Return Value

A list of CBPeripheral objects.

Discussion

Retrieves a list of the peripherals currently connected to the system and handles them using handleFoundPeripheral:

Retrieves all peripherals that are connected to the system and implement any of the services listed in serviceUUIDs. Note that this set can include peripherals which were connected by other applications, which will need to be connected locally via connectPeripheral:options: before they can be used.

Declared In

YMSCBCentralManager.h

CBCentralManager manager state handling methods

`– managerPoweredOnHandler`

Handler for when manager state is powered on.

- (void)managerPoweredOnHandler

Discussion

Handler for when manager state is powered on.

Declared In

YMSCBCentralManager.h

`– managerUnknownHandler`

Handler for when manager state is unknown.

- (void)managerUnknownHandler

Discussion

Handler for when manager state is unknown.

Declared In

YMSCBCentralManager.h

`– managerPoweredOffHandler`

Handler for when manager state is powered off

- (void)managerPoweredOffHandler

Discussion

Handler for when manager state is powered off

Declared In

YMSCBCentralManager.h

`– managerResettingHandler`

Handler for when manager state is resetting.

- (void)managerResettingHandler

Discussion

Handler for when manager state is resetting.

Declared In

YMSCBCentralManager.h

`– managerUnauthorizedHandler`

Handler for when manager state is unauthorized.

- (void)managerUnauthorizedHandler

Discussion

Handler for when manager state is unauthorized.

Declared In

YMSCBCentralManager.h

`– managerUnsupportedHandler`

Handler for when manager state is unsupported.

- (void)managerUnsupportedHandler

Discussion

Handler for when manager state is unsupported.

Declared In

YMSCBCentralManager.h