diff --git a/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h b/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h index cce62729ff..effc887851 100644 --- a/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h +++ b/features/FEATURE_BLE/ble/DiscoveredCharacteristic.h @@ -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