Representation of a characteristic discovered. More...

#include <DiscoveredCharacteristic.h>

Data Structures
struct	Properties_t
	Properties of a discovered characteristic. More...

Public Member Functions
ble_error_t	read (uint16_t offset=0) const
	Initiate a read of the characteristic value. More...

ble_error_t	read (uint16_t offset, const ble::ReadCallback_t &onRead) const
	Initiate a read of the characteristic value and pass the response to its completion callback. More...

ble_error_t	writeWoResponse (uint16_t length, const uint8_t *value) const
	Perform a write without response procedure. More...

ble_error_t	discoverDescriptors (const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered, const CharacteristicDescriptorDiscovery::TerminationCallback_t &onTermination) const
	Initiate a discovery of the characteristic descriptors. More...

ble_error_t	write (uint16_t length, const uint8_t *value) const
	Initiate a write procedure of the characteristic value. More...

ble_error_t	write (uint16_t length, const uint8_t *value, const ble::WriteCallback_t &onWrite) const
	Initiate a write procedure of the characteristic value. More...

const UUID &	getUUID () const
	Get the UUID of the discovered characteristic. More...

const Properties_t &	getProperties () const
	Get the properties of this characteristic. More...

GattAttribute::Handle_t	getDeclHandle () const
	Get the declaration handle of this characteristic. More...

GattAttribute::Handle_t	getValueHandle () const
	Get the attribute handle of the characteristic value. More...

GattAttribute::Handle_t	getLastHandle () const
	Return the last attribute handle of the characteristic definition. More...

ble::GattClient *	getGattClient ()
	Get the ble::GattClient, which can operate on this characteristic. More...

const ble::GattClient *	getGattClient () const
	Get the ble::GattClient, which can operate on this characteristic. More...

ble::connection_handle_t	getConnectionHandle () const
	Get the connection handle to the GattServer containing this characteristic. More...

Protected Attributes
ble::GattClient *	gattc
	Pointer to the underlying ble::GattClient for this DiscoveredCharacteristic object. More...

UUID	uuid
	Discovered characteristic's UUID. More...

Properties_t	props
	Hold the configured properties of the discovered characteristic. More...

GattAttribute::Handle_t	declHandle
	Value handle of the discovered characteristic's declaration attribute. More...

GattAttribute::Handle_t	valueHandle
	Value handle of the discovered characteristic's value attribute. More...

GattAttribute::Handle_t	lastHandle
	Value handle of the discovered characteristic's last attribute. More...

ble::connection_handle_t	connHandle
	Handle of the connection where the characteristic was discovered. More...

Detailed Description

Representation of a characteristic discovered.

The ble::GattClient discovery procedure initiated with ble::GattClient::launchServiceDiscovery() generates instances of this class.

It exposes the main attributes of the discovered characteristic:

The UUID of the characteristic, it can be retrieved by a call to the function getUUID(). This UUID is the type of the characteristic.
Attribute Handles of the characteristic are present as the triplet declaration handle, value handle and last handle. The value handle is used to read or write the content of the characteristic.
The properties contain the set of operations the characteristic can handle, for instance being read or written.

It important to note that the value of the characteristic - if it is accessible - is not fetched at discovery time.

The main operations the class offers are reading, writing and discovering the descriptors of the characteristic discovered.

Reading a discovered characteristic can be accomplished in two different fashions:

If the user has a callback registered for the data read operation in the ble::GattClient, then a call to the read(uint16_t) function will initiate a read of the characteristic. Results of the operation will be pass on the callback registered by ble::GattClient::onDataRead(), which processes all the responses to read requests. The read request for a given characteristic can be identified by the connection handle and the attribute handle, which are present in GattReadCallbackParams.

Another overload (read(uint16_t, const ble::ReadCallback_t&)) of the read function accepts a completion callback as a last parameter. That completion callback will be invoked automatically once the response to the read request for that given characteristic has been received. However, convenience came at the expense of dynamic memory usage for the time of the transaction.

Similarly, two versions of the write() API are exposed. One where the user has to register a callback handling write response through the function ble::GattClient::onDataWritten() and another one that accepts a completion callback in input.

It is also possible to send a write command, which is not acknowledged by the peer server by using the function writeWoResponse().

Finally, descriptors of the characteristic can be discovered by invoking the function discoverDescriptors, which is shorthand for calling ble::GattClient::discoverCharacteristicDescriptors. That discovery is necessary to enable or disable characteristic notification or indication that is achieved by writing on the Client Characteristic Configuration Descriptor (CCCD).

Definition at line 94 of file gatt/DiscoveredCharacteristic.h.

Member Function Documentation

◆ read() [1/2]

ble_error_t read ( uint16_t offset = 0 ) const

Initiate a read of the characteristic value.

The characteristic value is read in its entirety from the value attribute of the characteristic.

Read responses will be passed to the callback registered in ble::GattClient::onDataRead(). Read responses to read requests that this function call initiates will have their GattReadCallbackParams::connHandle field equal to the value returned by getConnectionHandle() and their GattReadCallbackParams::handle field equal to the value returned by getValueHandle().

Parameters

[in]

offset

The position - in the characteristic value bytes stream

where the read operation begin. This parameter is optional.

Returns: BLE_ERROR_NONE if a read has been initiated.; BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid.; BLE_STACK_BUSY if some client procedure is already in progress.; BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.

◆ read() [2/2]

ble_error_t read	(	uint16_t	offset,
		const ble::ReadCallback_t &	onRead
	)		const

Initiate a read of the characteristic value and pass the response to its completion callback.

Parameters

[in]	offset	The position - in the characteristic value bytes stream where the read operation begin.
[in]	onRead	Completion callback which will accept the response of the read request. The callback is copied; it is unnecessary to keep it in memory after the call.

Returns: BLE_ERROR_NONE if a read has been initiated.; BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid.; BLE_STACK_BUSY if some client procedure is already in progress.; BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.

Note: This function is similar to read(uint16_t) const; however, it uses dynamic memory to store the use completion callback.

◆ writeWoResponse()

ble_error_t writeWoResponse	(	uint16_t	length,
		const uint8_t *	value
	)		const

Perform a write without response procedure.

Note: The server does not acknowledge write without responses. Therefore, they won't generate any event on the client side.

Parameters

[in]	length	The amount of data being written.
[in]	value	The bytes being written.

Returns: BLE_ERROR_NONE Successfully started the Write procedure.; BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid.; BLE_STACK_BUSY if some client procedure is already in progress.; BLE_ERROR_NO_MEM if there are no available buffers left to process the request.; BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.

◆ discoverDescriptors()

ble_error_t discoverDescriptors	(	const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &	onDescriptorDiscovered,
		const CharacteristicDescriptorDiscovery::TerminationCallback_t &	onTermination
	)		const

Initiate a discovery of the characteristic descriptors.

When a descriptor is discovered, the callback onDescriptorDiscovered is invoked with the descriptor discovered as parameter. When the process ends, the callback onTermination is invoked.

Parameters

[in]	onDescriptorDiscovered	Callback is invoked when a descriptor is discovered.
[in]	onTermination	Callback is invoked when the discovery process ends.

Returns: BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.

Note: This function is shorthand for ble::GattClient::discoverCharacteristicDescriptors; therefore, ble::GattClient::isCharacteristicDescriptorDiscoveryActive can be used to determine the descriptor discovery and ble::GattClient::terminateCharacteristicDescriptorDiscovery can be used to end the discovery process.

◆ write() [1/2]

ble_error_t write	(	uint16_t	length,
		const uint8_t *	value
	)		const

Initiate a write procedure of the characteristic value.

Unlike write without responses (see writeWoResponse()), an acknowledgment is expected for this procedure. The response of the peer GATT server to the write request is passed to callbacks registered in ble::GattClient::onDataWritten().

Similarly to read responses, responses to write request of this characteristic can be identified by their connection handle ( GattWriteCallbackParams::connHandle), which is equal to the value returned by getConnectionHandle() and their attribute handle ( GattWriteCallbackParams::handle), which is equal to the value returned by getValueHandle().

Parameters

[in]	length	The amount of data being written.
[in]	value	The bytes being written.

Returns: BLE_ERROR_NONE Successfully started the Write procedure.; BLE_ERROR_INVALID_STATE If some internal state about the connection is invalid.; BLE_STACK_BUSY If some client procedure is already in progress.; BLE_ERROR_NO_MEM If there are no available buffers left to process the request.; BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.

Note: Internally, the API uses the write or long write procedure, depending on the number of bytes to write and the MTU size.

◆ write() [2/2]

ble_error_t write	(	uint16_t	length,
		const uint8_t *	value,
		const ble::WriteCallback_t &	onWrite
	)		const

Initiate a write procedure of the characteristic value.

Same as write(uint16_t, const uint8_t *) const but accepts a completion callback, which is invoked when the server response is received.

Parameters

[in]	length	The amount of bytes to write.
[in]	value	The bytes to write.
[in]	onWrite	Continuation callback of the write procedure.

Returns: BLE_ERROR_NONE Successfully started the Write procedure.; BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid.; BLE_STACK_BUSY if some client procedure is already in progress.; BLE_ERROR_NO_MEM if there are no available buffers left to process the request.; BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.

◆ getUUID()

const UUID & getUUID ( ) const

Get the UUID of the discovered characteristic.

Returns: The UUID of this characteristic.

Definition at line 450 of file gatt/DiscoveredCharacteristic.h.

◆ getProperties()

const Properties_t & getProperties ( ) const

Get the properties of this characteristic.

Returns: The set of properties of this characteristic.

Definition at line 460 of file gatt/DiscoveredCharacteristic.h.

◆ getDeclHandle()

GattAttribute::Handle_t getDeclHandle ( ) const

Get the declaration handle of this characteristic.

The declaration handle is the first handle of a characteristic definition. The value accessible at this handle contains the following informations:

The characteristics properties (see Properties_t). This value can be accessed by using getProperties .
The characteristic value attribute handle. This field can be accessed by using getValueHandle .
The characteristic UUID, this value can be accessed by using the function getUUID .

Returns: the declaration handle of this characteristic.

Definition at line 480 of file gatt/DiscoveredCharacteristic.h.

◆ getValueHandle()

GattAttribute::Handle_t getValueHandle ( ) const

Get the attribute handle of the characteristic value.

This handle is used to read or write the value of the characteristic.

Returns: The handle to access the value of this characteristic.

Definition at line 492 of file gatt/DiscoveredCharacteristic.h.

◆ getLastHandle()

GattAttribute::Handle_t getLastHandle ( ) const

Return the last attribute handle of the characteristic definition.

The attribute layout of a characteristic definition is:

Declaration attribute (see getDeclHandle).
Value attribute (see getValueHandle).
Zero or more characteristic descriptors attribute.

The last attribute handle is used internally to discover characteristic descriptors. The discovery operates on the range [ValueHandle + 1 : LastHandle].