Mbed OS Reference
Loading...
Searching...
No Matches
DiscoveredCharacteristic Class Reference

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 UUIDgetUUID () const
 Get the UUID of the discovered characteristic. More...
 
const Properties_tgetProperties () 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::GattClientgetGattClient ()
 Get the ble::GattClient, which can operate on this characteristic. More...
 
const ble::GattClientgetGattClient () 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::GattClientgattc
 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]offsetThe 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]offsetThe position - in the characteristic value bytes stream
  • where the read operation begin.
[in]onReadCompletion 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]lengthThe amount of data being written.
[in]valueThe 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]onDescriptorDiscoveredCallback is invoked when a descriptor is discovered.
[in]onTerminationCallback 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]lengthThe amount of data being written.
[in]valueThe 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]lengthThe amount of bytes to write.
[in]valueThe bytes to write.
[in]onWriteContinuation 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:

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

Returns
The last handle of this characteristic definition.
Note
This function is public for informative purposes.

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

◆ getGattClient() [1/2]

ble::GattClient * getGattClient ( )

Get the ble::GattClient, which can operate on this characteristic.

Returns
The ble::GattClient, which can operate on this characteristic.

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

◆ getGattClient() [2/2]

const ble::GattClient * getGattClient ( ) const

Get the ble::GattClient, which can operate on this characteristic.

Returns
The ble::GattClient, which can operate on this characteristic.

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

◆ getConnectionHandle()

ble::connection_handle_t getConnectionHandle ( ) const

Get the connection handle to the GattServer containing this characteristic.

Returns
Connection handle to the GattServer, which contains this characteristic.

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

Field Documentation

◆ gattc

ble::GattClient* gattc
protected

Pointer to the underlying ble::GattClient for this DiscoveredCharacteristic object.

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

◆ uuid

UUID uuid
protected

Discovered characteristic's UUID.

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

◆ props

Properties_t props
protected

Hold the configured properties of the discovered characteristic.

See also
Properties_t.

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

◆ declHandle

GattAttribute::Handle_t declHandle
protected

Value handle of the discovered characteristic's declaration attribute.

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

◆ valueHandle

GattAttribute::Handle_t valueHandle
protected

Value handle of the discovered characteristic's value attribute.

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

◆ lastHandle

GattAttribute::Handle_t lastHandle
protected

Value handle of the discovered characteristic's last attribute.

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

◆ connHandle

ble::connection_handle_t connHandle
protected

Handle of the connection where the characteristic was discovered.

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