YMSCBCharacteristic Class Reference

Inherits from	NSObject
Declared in	YMSCBCharacteristic.h YMSCBCharacteristic.m

Overview

Base class for defining a Bluetooth LE characteristic.

YMSCBCharacteristic holds an instance of CBCharacteristic (cbCharacteristic).

This class is typically instantiated by a subclass of YMSCBService. The property cbCharacteristic is set in [YMSCBService syncCharacteristics:]

Properties

`name`

Human-friendly name for this BLE characteristic.

@property (atomic, strong) NSString *name

Discussion

Human-friendly name for this BLE characteristic.

Declared In

YMSCBCharacteristic.h

`uuid`

Characterisic CBUUID.

@property (atomic, strong) CBUUID *uuid

Discussion

Characterisic CBUUID.

Declared In

YMSCBCharacteristic.h

`cbCharacteristic`

Pointer to actual CBCharacterisic.

@property (atomic, strong) CBCharacteristic *cbCharacteristic

Discussion

Pointer to actual CBCharacterisic.

Declared In

YMSCBCharacteristic.h

`parent`

Pointer to parent peripheral.

@property (nonatomic, weak) YMSCBPeripheral *parent

Discussion

Pointer to parent peripheral.

Declared In

YMSCBCharacteristic.h

`offset`

Absolute address value. May turn into an offset value if base address is supported in the future for this class.

@property (atomic, strong) NSNumber *offset

Discussion

Absolute address value. May turn into an offset value if base address is supported in the future for this class.

Declared In

YMSCBCharacteristic.h

`descriptors`

Holds instances of YMSCBDescriptor

@property (atomic, strong) NSArray *descriptors

Discussion

Holds instances of YMSCBDescriptor

Declared In

YMSCBCharacteristic.h

`notificationStateCallback`

Notification state callback

@property (atomic, copy) YMSCBWriteCallbackBlockType notificationStateCallback

Discussion

Notification state callback

Declared In

YMSCBCharacteristic.h

`discoverDescriptorsCallback`

Callback for descriptors that are discovered.

@property (atomic, copy) YMSCBDiscoverDescriptorsCallbackBlockType discoverDescriptorsCallback

Discussion

Callback for descriptors that are discovered.

Declared In

YMSCBCharacteristic.h

`readCallbacks`

FIFO queue for reads.

@property (atomic, strong) NSMutableArray *readCallbacks

Discussion

FIFO queue for reads.

Each element is a block of type YMSCBReadCallbackBlockType.

Declared In

YMSCBCharacteristic.h

`writeCallbacks`

FIFO queue for writes.

@property (atomic, strong) NSMutableArray *writeCallbacks

Discussion

FIFO queue for writes.

Each element is a block of type YMSCBWriteCallbackBlockType.

Declared In

YMSCBCharacteristic.h

Callback Handler Methods

`– executeNotificationStateCallback:`

Handler method to process notificationStateCallback.

- (void)executeNotificationStateCallback:(NSError *)error

Parameters

`error`	Error object, if failed.

Discussion

Handler method to process notificationStateCallback.

Declared In

YMSCBCharacteristic.h

`– executeReadCallback:error:`

Handler method to process first callback in readCallbacks.

- (void)executeReadCallback:(NSData *)data error:(NSError *)error

Parameters

`data`	Value returned from read request.
`error`	Error object, if failed.

Discussion

Handler method to process first callback in readCallbacks.

Declared In

YMSCBCharacteristic.h

`– executeWriteCallback:`

Handler method to process first callback in writeCallbacks.

- (void)executeWriteCallback:(NSError *)error

Parameters

`error`	Error object, if failed.

Discussion

Handler method to process first callback in writeCallbacks.

Declared In

YMSCBCharacteristic.h

Initializing a YMSCBCharacteristic

`– initWithName:parent:uuid:offset:`

Constructor.

- (instancetype)initWithName:(NSString *)oName parent:(YMSCBPeripheral *)pObj uuid:(CBUUID *)oUUID offset:(int)addrOffset

Parameters

`oName`	characteristic name
`pObj`	parent peripheral
`oUUID`	characteristic CBUUID
`addrOffset`	characteristic absolute address (it’s not really an offset)

Discussion

Constructor.

Note: addrOffset is really an absolute address here in implementation. TBD whether this should be considered an API bug or possibly an API change where a base address is supported in this method (and class). For now leaving as is until feedback is provided (please use the issue tracker on GitHub.)

https://github.com/kickingvegas/YmsCoreBluetooth/issues

Declared In

YMSCBCharacteristic.h

Changing the notification state

`– setNotifyValue:withBlock:`

Set notification value of cbCharacteristic.

- (void)setNotifyValue:(BOOL)notifyValue withBlock:(void ( ^ ) ( NSError *error ))notifyStateCallback

Parameters

`notifyValue`	Set notification enable.
`notifyStateCallback`	Callback to execute upon change in notification state.

Discussion

Set notification value of cbCharacteristic.

When notifyValue is YES, then cbCharacterisic is set to notify upon any changes to its value. When notifyValue is NO, then no notifications are sent.

An implementation of the method [YMSCBService notifyCharacteristicHandler:error:] is used to handle updates to cbCharacteristic. Note that notification handling is done at the YMSCBService level via method handler and not by callback blocks. The reason for this is opinion: It is more convenient to write a method handler to deal with non-deterministic, asynchronous notification events than it is with blocks.

Declared In

YMSCBCharacteristic.h

Issuing a Write Request

`– writeValue:withBlock:`

Issue write with value data and execute callback block writeCallback upon response.

- (void)writeValue:(NSData *)data withBlock:(void ( ^ ) ( NSError *error ))writeCallback

Parameters

`data`	The value to be written
`writeCallback`	Callback block to execute upon response.

Discussion

Issue write with value data and execute callback block writeCallback upon response.

The callback block writeCallback has one argument: error:

error is populated with the returned error object from the delegate method peripheral:didWriteValueForCharacteristic:error: implemented in YMSCBPeripheral.

Declared In

YMSCBCharacteristic.h

`– writeByte:withBlock:`

Issue write with byte val and execute callback block writeCallback upon response.

- (void)writeByte:(int8_t)val withBlock:(void ( ^ ) ( NSError *error ))writeCallback

Parameters

`val`	Byte value to be written
`writeCallback`	Callback block to execute upon response.

Discussion

Issue write with byte val and execute callback block writeCallback upon response.

The callback block writeCallback has one argument: error:

error is populated with the returned error object from the delegate method peripheral:didWriteValueForCharacteristic:error: implemented in YMSCBPeripheral.

Declared In

YMSCBCharacteristic.h

Issuing a Read Request

`– readValueWithBlock:`

Issue read and execute callback block readCallback upon response.

- (void)readValueWithBlock:(void ( ^ ) ( NSData *data , NSError *error ))readCallback

Parameters

`readCallback`	Callback block to execute upon response.

Discussion

Issue read and execute callback block readCallback upon response.

The callback block readCallback has two arguments: data and error:

data is populated with the value property of [YMSCBCharacteristic cbCharacteristic].
error is populated with the returned error object from the delegate method peripheral:didUpdateValueForCharacteristic:error: implemented in YMSCBPeripheral.

Declared In

YMSCBCharacteristic.h

Discover Descriptors

`– discoverDescriptorsWithBlock:`

Discover descriptors for this characteristic.

- (void)discoverDescriptorsWithBlock:(void ( ^ ) ( NSArray *ydescriptors , NSError *error ))callback

Parameters

`callback`	Callback block to execute upon response for discovered descriptors.

Discussion

Discover descriptors for this characteristic.

Declared In

YMSCBCharacteristic.h

`– handleDiscoveredDescriptorsResponse:withError:`

Handler method for discovered descriptors.

- (void)handleDiscoveredDescriptorsResponse:(NSArray *)ydescriptors withError:(NSError *)error

Parameters

`ydescriptors`	Array of YMSCBDescriptor instances.
`error`	Error object, if failure.

Discussion

Handler method for discovered descriptors.

Declared In

YMSCBCharacteristic.h