mirror of https://github.com/ARMmbed/mbed-os.git
Copy edit DiscoveredCharacteristic.h
Make minor copy edits, mostly for active voice and American English.pull/5392/head
Amanda Butler
GitHub
parent
c9931f3643
commit
08ba159cf6
|
|
@ -36,8 +36,8 @@
|
|||
/**
|
||||
* Representation of a characteristic discovered.
|
||||
*
|
||||
* Instances of this class are generated by the GattClient discovery procedure
|
||||
* initiated with GattClient::launchServiceDiscovery().
|
||||
* 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
|
||||
|
|
@ -51,39 +51,39 @@
|
|||
* It important to note that the value of the characteristic - if it is
|
||||
* accessible - is not fetched at discovery time.
|
||||
*
|
||||
* The main operations offered by the class are reading, writing and discovering
|
||||
* 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
|
||||
* fashion:
|
||||
* 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
|
||||
* 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 process all the responses to
|
||||
* 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
|
||||
* 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 accept a completion callback as a last parameter. That
|
||||
* 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
|
||||
* 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 via the function
|
||||
* GattClient::onDataWritten() and another one which accept a completion
|
||||
* 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
|
||||
* 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 a shorthand for calling
|
||||
* 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 which is achieved
|
||||
* enable or disable characteristic notification or indication that is achieved
|
||||
* by writing on the Client Characteristic Configuration Descriptor (CCCD).
|
||||
*/
|
||||
class DiscoveredCharacteristic {
|
||||
|
|
@ -96,47 +96,47 @@ public:
|
|||
* Permits broadcasts of the characteristic value using the character
|
||||
* the Server Characteristic Configuration Descriptor.
|
||||
*
|
||||
* @note If set descriptors of the characteristic shall contain a Server
|
||||
* @note If set, descriptors of the characteristic contain a Server
|
||||
* Characteristic Configuration Descriptor.
|
||||
*/
|
||||
uint8_t _broadcast :1;
|
||||
|
||||
/**
|
||||
* If set the value of the characteristic can be read.
|
||||
* If set, the value of the characteristic can be read.
|
||||
*/
|
||||
uint8_t _read :1;
|
||||
|
||||
/**
|
||||
* If set the characteristic value can be written by a write command
|
||||
* If set, a write command can write the characteristic value
|
||||
* (write without response).
|
||||
*/
|
||||
uint8_t _writeWoResp :1;
|
||||
|
||||
/**
|
||||
* If set clients can issue requests to write the characteristic.
|
||||
* If set, clients can issue requests to write the characteristic.
|
||||
*/
|
||||
uint8_t _write :1;
|
||||
|
||||
/**
|
||||
* If set the server can emit notifications of the Characteristic Value
|
||||
* (without client acknowledgement).
|
||||
* If set, the server can emit notifications of the Characteristic Value
|
||||
* (without client acknowledgment).
|
||||
*
|
||||
* @note If set descriptors of the characteristic shall contain a Client
|
||||
* @note If set, descriptors of the characteristic contain a Client
|
||||
* Characteristic Configuration Descriptor.
|
||||
*/
|
||||
uint8_t _notify :1;
|
||||
|
||||
/**
|
||||
* If set the server can emit indication of the Characteristic Value
|
||||
* If set, the server can emit indication of the Characteristic Value
|
||||
* (with client acknowledgement).
|
||||
*
|
||||
* @note If set descriptors of the characteristic shall contain a Client
|
||||
* @note If set, descriptors of the characteristic contain a Client
|
||||
* Characteristic Configuration Descriptor.
|
||||
*/
|
||||
uint8_t _indicate :1;
|
||||
|
||||
/**
|
||||
* If set signed write of the Characteristic Value are supported.
|
||||
* If set, signed write of the Characteristic Value is supported.
|
||||
*/
|
||||
uint8_t _authSignedWrite :1;
|
||||
|
||||
|
|
@ -171,7 +171,7 @@ public:
|
|||
/**
|
||||
* Return the value of the write without response property.
|
||||
*
|
||||
* @return true if the characteristic accept write without response
|
||||
* @return true if the characteristic accepts write without response
|
||||
* commands and false otherwise.
|
||||
*
|
||||
* @see _writeWoResp
|
||||
|
|
@ -184,7 +184,7 @@ public:
|
|||
/**
|
||||
* Return the value of the write property.
|
||||
*
|
||||
* @return true if writing the characteristic accept write requests and
|
||||
* @return true if writing the characteristic accepts write requests and
|
||||
* false otherwise.
|
||||
*
|
||||
* @see _write
|
||||
|
|
@ -201,7 +201,7 @@ public:
|
|||
* can be configured to notify the characteristic value to a given
|
||||
* client and false otherwise.
|
||||
*
|
||||
* @note unlike indication the notification procedure does not require
|
||||
* @note unlike indication, the notification procedure does not require
|
||||
* acknowledgement from the client.
|
||||
*
|
||||
* @see _notify
|
||||
|
|
@ -219,7 +219,7 @@ public:
|
|||
* client and false otherwise.
|
||||
*
|
||||
* @note unlike notification the indication procedure does require
|
||||
* acknowledgement from the client.
|
||||
* acknowledgment from the client.
|
||||
*
|
||||
* @see _indicate
|
||||
*/
|
||||
|
|
@ -231,7 +231,7 @@ public:
|
|||
/**
|
||||
* Return the value of the authenticated signed writes property.
|
||||
*
|
||||
* @return true if the characteristic accept authenticated signed write
|
||||
* @return true if the characteristic accepts authenticated signed write
|
||||
* and false otherwise.
|
||||
*/
|
||||
bool authSignedWrite(void) const
|
||||
|
|
@ -242,8 +242,8 @@ public:
|
|||
/**
|
||||
* Equal to operator for DiscoveredCharacteristic::Properties_t.
|
||||
*
|
||||
* @param[in] lhs The left hand side of the equality expression
|
||||
* @param[in] rhs The right hand side of the equality expression
|
||||
* @param[in] lhs The left hand side of the equality expression.
|
||||
* @param[in] rhs The right hand side of the equality expression.
|
||||
*
|
||||
* @return true if operands are equals and false otherwise.
|
||||
*/
|
||||
|
|
@ -284,8 +284,8 @@ public:
|
|||
* of the characteristic.
|
||||
*
|
||||
* Read responses will be passed to the callback registered in
|
||||
* GattClient::onDataRead(). Read responses to read requests initiated by
|
||||
* this function call will have their GattReadCallbackParams::connHandle
|
||||
* 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().
|
||||
|
|
@ -310,7 +310,7 @@ public:
|
|||
* - where the read operation begin.
|
||||
*
|
||||
* @param[in] onRead Completion callback which will accept the response of
|
||||
* the read request. The callback is copied, it is not necessary to keep it
|
||||
* the read request. The callback is copied; it is unnecessary to keep it
|
||||
* in memory after the call.
|
||||
*
|
||||
* @return BLE_ERROR_NONE if a read has been initiated.
|
||||
|
|
@ -320,7 +320,7 @@ public:
|
|||
* @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
|
||||
* properties.
|
||||
*
|
||||
* @note This function is similar to read(uint16_t) const however it uses
|
||||
* @note This function is similar to read(uint16_t) const; however, it uses
|
||||
* dynamic memory to store the use completion callback.
|
||||
*/
|
||||
ble_error_t read(
|
||||
|
|
@ -331,8 +331,8 @@ public:
|
|||
/**
|
||||
* Perform a write without response procedure.
|
||||
*
|
||||
* @note Write without responses are not acknowledged by the server and
|
||||
* therefore won't generate any event on the client side.
|
||||
* @note The server does not acknowledge write without responses.
|
||||
* Therefore, they won't generate any event on the client side.
|
||||
*
|
||||
* @param[in] length The amount of data being written.
|
||||
* @param[in] value The bytes being written.
|
||||
|
|
@ -355,20 +355,20 @@ public:
|
|||
* invoked with the descriptor discovered as parameter. When the process
|
||||
* ends, the callback onTermination is invoked.
|
||||
*
|
||||
* @param[in] onDescriptorDiscovered Callback invoked when a descriptor is
|
||||
* discovered
|
||||
* @param[in] onDescriptorDiscovered Callback is invoked when a descriptor is
|
||||
* discovered.
|
||||
*
|
||||
* @param[in] onTermination Callback invoke when the discovery process ends.
|
||||
* @param[in] onTermination Callback is invoked when the discovery process ends.
|
||||
*
|
||||
* @return BLE_ERROR_NONE if descriptor discovery is launched successfully;
|
||||
* else an appropriate error.
|
||||
*
|
||||
* @note This function is a shorthand for
|
||||
* GattClient::discoverCharacteristicDescriptors therefore
|
||||
* @note This function is shorthand for
|
||||
* GattClient::discoverCharacteristicDescriptors; therefore,
|
||||
* GattClient::isCharacteristicDescriptorDiscoveryActive can be used to
|
||||
* determine if the descriptor discovery and
|
||||
* determine the descriptor discovery and
|
||||
* GattClient::terminateCharacteristicDescriptorDiscovery can be used to
|
||||
* ends the discovery process.
|
||||
* end the discovery process.
|
||||
*/
|
||||
ble_error_t discoverDescriptors(
|
||||
const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered,
|
||||
|
|
@ -378,16 +378,16 @@ public:
|
|||
/**
|
||||
* Initiate a write procedure of the characteristic value.
|
||||
*
|
||||
* Unlike write without responses (see writeWoResponse()) an acknowledgement
|
||||
* Unlike write without responses (see writeWoResponse()), an acknowledgment
|
||||
* is expected for this procedure. The response of the peer GATT server to
|
||||
* the write request will be passed to callbacks registered in
|
||||
* 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 will be equal to the value
|
||||
* GattWriteCallbackParams::connHandle), which is equal to the value
|
||||
* returned by getConnectionHandle() and their attribute handle (
|
||||
* GattWriteCallbackParams::handle) which will be equal to the value
|
||||
* GattWriteCallbackParams::handle), which is equal to the value
|
||||
* returned by getValueHandle().
|
||||
*
|
||||
* @param[in] length The amount of data being written.
|
||||
|
|
@ -402,7 +402,7 @@ public:
|
|||
* @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
|
||||
* properties.
|
||||
*
|
||||
* @note Internally the API use the write or long write procedure depending
|
||||
* @note Internally, the API uses the write or long write procedure, depending
|
||||
* on the number of bytes to write and the MTU size.
|
||||
*/
|
||||
ble_error_t write(uint16_t length, const uint8_t *value) const;
|
||||
|
|
@ -410,8 +410,8 @@ public:
|
|||
/**
|
||||
* Initiate a write procedure of the characteristic value.
|
||||
*
|
||||
* Same as write(uint16_t, const uint8_t *) const but accept a completion
|
||||
* callback which will be invoked when the server response is received.
|
||||
* Same as write(uint16_t, const uint8_t *) const but accepts a completion
|
||||
* callback, which is invoked when the server response is received.
|
||||
*
|
||||
* @param[in] length The amount of bytes to write.
|
||||
* @param[in] value The bytes to write.
|
||||
|
|
@ -492,13 +492,13 @@ public:
|
|||
/**
|
||||
* Return the last attribute handle of the characteristic definition.
|
||||
*
|
||||
* The attribute layout of a characteristic definition is as follows:
|
||||
* - Declaration attribute (see #getDeclHandle)
|
||||
* - Value attribute (see #getValueHandle)
|
||||
* 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 operate on the range [ValueHandle + 1 :
|
||||
* descriptors. The discovery operates on the range [ValueHandle + 1 :
|
||||
* LastHandle].
|
||||
*
|
||||
* @return The last handle of this characteristic definition.
|
||||
|
|
@ -511,9 +511,9 @@ public:
|
|||
}
|
||||
|
||||
/**
|
||||
* Get the GattClient which can operate on this characteristic.
|
||||
* Get the GattClient, which can operate on this characteristic.
|
||||
*
|
||||
* @return The GattClient which can operate on this characteristic.
|
||||
* @return The GattClient, which can operate on this characteristic.
|
||||
*/
|
||||
GattClient* getGattClient()
|
||||
{
|
||||
|
|
@ -521,9 +521,9 @@ public:
|
|||
}
|
||||
|
||||
/**
|
||||
* Get the GattClient which can operate on this characteristic.
|
||||
* Get the GattClient, which can operate on this characteristic.
|
||||
*
|
||||
* @return The GattClient which can operate on this characteristic.
|
||||
* @return The GattClient, which can operate on this characteristic.
|
||||
*/
|
||||
const GattClient* getGattClient() const
|
||||
{
|
||||
|
|
@ -534,7 +534,7 @@ public:
|
|||
* @brief Get the connection handle to the GattServer containing this
|
||||
* characteristic.
|
||||
*
|
||||
* @return Connection handle to the GattServer which contain this
|
||||
* @return Connection handle to the GattServer, which contains this
|
||||
* characteristic.
|
||||
*/
|
||||
Gap::Handle_t getConnectionHandle() const
|
||||
|
|
|
|||
Loading…
Reference in New Issue