Rtos API example
DiscoveredCharacteristic Class Reference
[Client]
Representation of a characteristic discovered. More...
#include <DiscoveredCharacteristic.h>
Inherited by discovery_control_block_t::characteristic_t.
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. | |
ble_error_t | read (uint16_t offset, const GattClient::ReadCallback_t &onRead) const |
Initiate a read of the characteristic value and pass the response to its completion callback. | |
ble_error_t | writeWoResponse (uint16_t length, const uint8_t *value) const |
Perform a write without response procedure. | |
ble_error_t | discoverDescriptors (const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered, const CharacteristicDescriptorDiscovery::TerminationCallback_t &onTermination) const |
Initiate a discovery of the characteristic descriptors. | |
ble_error_t | write (uint16_t length, const uint8_t *value) const |
Initiate a write procedure of the characteristic value. | |
ble_error_t | write (uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t &onWrite) const |
Initiate a write procedure of the characteristic value. | |
const UUID & | getUUID (void) const |
Get the UUID of the discovered characteristic. | |
const Properties_t & | getProperties (void) const |
Get the properties of this characteristic. | |
GattAttribute::Handle_t | getDeclHandle (void) const |
Get the declaration handle of this characteristic. | |
GattAttribute::Handle_t | getValueHandle (void) const |
Get the attribute handle of the characteristic value. | |
GattAttribute::Handle_t | getLastHandle (void) const |
Return the last attribute handle of the characteristic definition. | |
GattClient * | getGattClient () |
Get the GattClient, which can operate on this characteristic. | |
const GattClient * | getGattClient () const |
Get the GattClient, which can operate on this characteristic. | |
Gap::Handle_t | getConnectionHandle () const |
Get the connection handle to the GattServer containing this characteristic. | |
Protected Attributes | |
GattClient * | gattc |
Pointer to the underlying GattClient for this DiscoveredCharacteristic object. | |
UUID | uuid |
Discovered characteristic's UUID. | |
Properties_t | props |
Hold the configured properties of the discovered characteristic. | |
GattAttribute::Handle_t | declHandle |
Value handle of the discovered characteristic's declaration attribute. | |
GattAttribute::Handle_t | valueHandle |
Value handle of the discovered characteristic's value attribute. | |
GattAttribute::Handle_t | lastHandle |
Value handle of the discovered characteristic's last attribute. | |
Gap::Handle_t | connHandle |
Handle of the connection where the characteristic was discovered. | |
Friends | |
bool | operator== (const DiscoveredCharacteristic &lhs, const DiscoveredCharacteristic &rhs) |
"Equal to" operator for DiscoveredCharacteristic. | |
bool | operator!= (const DiscoveredCharacteristic &lhs, const DiscoveredCharacteristic &rhs) |
"Not equal to" operator for DiscoveredCharacteristic. |
Detailed Description
Representation of a characteristic discovered.
The GattClient discovery procedure initiated with 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 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 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 GattClient::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 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 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 89 of file DiscoveredCharacteristic.h.
Member Function Documentation
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 GattClient::discoverCharacteristicDescriptors; therefore, GattClient::isCharacteristicDescriptorDiscoveryActive can be used to determine the descriptor discovery and GattClient::terminateCharacteristicDescriptorDiscovery can be used to end the discovery process.
Definition at line 154 of file DiscoveredCharacteristic.cpp.
Gap::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 540 of file DiscoveredCharacteristic.h.
GattAttribute::Handle_t getDeclHandle | ( | void | ) | 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 475 of file DiscoveredCharacteristic.h.
const GattClient* getGattClient | ( | void | ) | const |
Get the GattClient, which can operate on this characteristic.
- Returns:
- The GattClient, which can operate on this characteristic.
Definition at line 528 of file DiscoveredCharacteristic.h.
GattClient* getGattClient | ( | void | ) |
Get the GattClient, which can operate on this characteristic.
- Returns:
- The GattClient, which can operate on this characteristic.
Definition at line 518 of file DiscoveredCharacteristic.h.
GattAttribute::Handle_t getLastHandle | ( | void | ) | 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].
- Returns:
- The last handle of this characteristic definition.
- Note:
- This function is public for informative purposes.
Definition at line 508 of file DiscoveredCharacteristic.h.
const Properties_t& getProperties | ( | void | ) | const |
Get the properties of this characteristic.
- Returns:
- The set of properties of this characteristic.
Definition at line 455 of file DiscoveredCharacteristic.h.
const UUID& getUUID | ( | void | ) | const |
Get the UUID of the discovered characteristic.
- Returns:
- The UUID of this characteristic.
Definition at line 445 of file DiscoveredCharacteristic.h.
GattAttribute::Handle_t getValueHandle | ( | void | ) | 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 487 of file DiscoveredCharacteristic.h.
ble_error_t read | ( | uint16_t | offset, |
const GattClient::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.
Definition at line 69 of file DiscoveredCharacteristic.cpp.
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 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.
Definition at line 21 of file DiscoveredCharacteristic.cpp.
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 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.
Definition at line 81 of file DiscoveredCharacteristic.cpp.
ble_error_t write | ( | uint16_t | length, |
const uint8_t * | value, | ||
const GattClient::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.
Definition at line 143 of file DiscoveredCharacteristic.cpp.
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.
Definition at line 95 of file DiscoveredCharacteristic.cpp.
Friends And Related Function Documentation
bool operator!= | ( | const DiscoveredCharacteristic & | lhs, |
const DiscoveredCharacteristic & | rhs | ||
) | [friend] |
"Not equal to" operator for DiscoveredCharacteristic.
- Parameters:
-
[in] lhs The right hand side of the expression. [in] rhs The left hand side of the expression.
- Returns:
- true if operands are not equal and false otherwise.
Definition at line 573 of file DiscoveredCharacteristic.h.
bool operator== | ( | const DiscoveredCharacteristic & | lhs, |
const DiscoveredCharacteristic & | rhs | ||
) | [friend] |
"Equal to" operator for DiscoveredCharacteristic.
- Parameters:
-
[in] lhs The left hand side of the equality expression. [in] rhs The right hand side of the equality expression.
- Returns:
- true if operands are equals and false otherwise.
Definition at line 553 of file DiscoveredCharacteristic.h.
Field Documentation
Gap::Handle_t connHandle [protected] |
Handle of the connection where the characteristic was discovered.
Definition at line 628 of file DiscoveredCharacteristic.h.
GattAttribute::Handle_t declHandle [protected] |
Value handle of the discovered characteristic's declaration attribute.
Definition at line 613 of file DiscoveredCharacteristic.h.
GattClient* gattc [protected] |
Pointer to the underlying GattClient for this DiscoveredCharacteristic object.
Definition at line 595 of file DiscoveredCharacteristic.h.
GattAttribute::Handle_t lastHandle [protected] |
Value handle of the discovered characteristic's last attribute.
Definition at line 623 of file DiscoveredCharacteristic.h.
Properties_t props [protected] |
Hold the configured properties of the discovered characteristic.
- See also:
- Properties_t.
Definition at line 608 of file DiscoveredCharacteristic.h.
Discovered characteristic's UUID.
Definition at line 601 of file DiscoveredCharacteristic.h.
GattAttribute::Handle_t valueHandle [protected] |
Value handle of the discovered characteristic's value attribute.
Definition at line 618 of file DiscoveredCharacteristic.h.
Generated on Sun Jul 17 2022 08:25:40 by 1.7.2