ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Copy edit DiscoveredCharacteristic.h 

Make minor copy edits, mostly for active voice and American English.
pull/5392/head
Amanda Butler 2017-11-07 15:52:43 -06:00 committed by GitHub
parent c9931f3643
commit 08ba159cf6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 61 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
features/FEATURE_BLE/ble/DiscoveredCharacteristic.h
View File

@ -36,8 +36,8 @@
/** /**
* Representation of a characteristic discovered. * Representation of a characteristic discovered.
* *
* Instances of this class are generated by the GattClient discovery procedure * The GattClient discovery procedure initiated with
* initiated with GattClient::launchServiceDiscovery(). * GattClient::launchServiceDiscovery() generates instances of this class.
* *
* It exposes the main attributes of the discovered characteristic: * It exposes the main attributes of the discovered characteristic:
* - The UUID of the characteristic, it can be retrieved by a call to the * - 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 * It important to note that the value of the characteristic - if it is
* accessible - is not fetched at discovery time. * 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. * the descriptors of the characteristic discovered.
* *
* Reading a discovered characteristic can be accomplished in two different * 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 * 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 * 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 * 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. * GattReadCallbackParams.
* *
* Another overload (read(uint16_t, const GattClient::ReadCallback_t&)) of the * 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 * 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 * convenience came at the expense of dynamic memory usage for the time of the
* transaction. * transaction.
* *
* Similarly, two versions of the write() API are exposed. One where the user * Similarly, two versions of the write() API are exposed. One where the user
* has to register a callback handling write response via the function * has to register a callback handling write response through the function
* GattClient::onDataWritten() and another one which accept a completion * GattClient::onDataWritten() and another one that accepts a completion
* callback in input. * 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(). * peer server by using the function writeWoResponse().
* *
* Finally descriptors of the characteristic can be discovered by invoking the * Finally, descriptors of the characteristic can be discovered by invoking the
* function discoverDescriptors which is a shorthand for calling * function discoverDescriptors, which is shorthand for calling
* GattClient::discoverCharacteristicDescriptors. That discovery is necessary to * 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). * by writing on the Client Characteristic Configuration Descriptor (CCCD).
*/ */
class DiscoveredCharacteristic { class DiscoveredCharacteristic {
@ -96,47 +96,47 @@ public:
* Permits broadcasts of the characteristic value using the character * Permits broadcasts of the characteristic value using the character
* the Server Characteristic Configuration Descriptor. * 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. * Characteristic Configuration Descriptor.
*/ */
uint8_t _broadcast :1; 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; 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). * (write without response).
*/ */
uint8_t _writeWoResp :1; 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; uint8_t _write :1;
/** /**
* If set the server can emit notifications of the Characteristic Value * If set, the server can emit notifications of the Characteristic Value
* (without client acknowledgement). * (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. * Characteristic Configuration Descriptor.
*/ */
uint8_t _notify :1; 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). * (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. * Characteristic Configuration Descriptor.
*/ */
uint8_t _indicate :1; 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; uint8_t _authSignedWrite :1;
@ -171,7 +171,7 @@ public:
/** /**
* Return the value of the write without response property. * 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. * commands and false otherwise.
* *
* @see _writeWoResp * @see _writeWoResp
@ -184,7 +184,7 @@ public:
/** /**
* Return the value of the write property. * 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. * false otherwise.
* *
* @see _write * @see _write
@ -201,7 +201,7 @@ public:
* can be configured to notify the characteristic value to a given * can be configured to notify the characteristic value to a given
* client and false otherwise. * 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. * acknowledgement from the client.
* *
* @see _notify * @see _notify
@ -219,7 +219,7 @@ public:
* client and false otherwise. * client and false otherwise.
* *
* @note unlike notification the indication procedure does require * @note unlike notification the indication procedure does require
* acknowledgement from the client. * acknowledgment from the client.
* *
* @see _indicate * @see _indicate
*/ */
@ -231,7 +231,7 @@ public:
/** /**
* Return the value of the authenticated signed writes property. * 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. * and false otherwise.
*/ */
bool authSignedWrite(void) const bool authSignedWrite(void) const
@ -242,8 +242,8 @@ public:
/** /**
* Equal to operator for DiscoveredCharacteristic::Properties_t. * Equal to operator for DiscoveredCharacteristic::Properties_t.
* *
* @param[in] lhs The left 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 * @param[in] rhs The right hand side of the equality expression.
* *
* @return true if operands are equals and false otherwise. * @return true if operands are equals and false otherwise.
*/ */
@ -284,8 +284,8 @@ public:
* of the characteristic. * of the characteristic.
* *
* Read responses will be passed to the callback registered in * Read responses will be passed to the callback registered in
* GattClient::onDataRead(). Read responses to read requests initiated by * GattClient::onDataRead(). Read responses to read requests that this function
* this function call will have their GattReadCallbackParams::connHandle * call initiates will have their GattReadCallbackParams::connHandle
* field equal to the value returned by getConnectionHandle() and their * field equal to the value returned by getConnectionHandle() and their
* GattReadCallbackParams::handle field equal to the value returned by * GattReadCallbackParams::handle field equal to the value returned by
* getValueHandle(). * getValueHandle().
@ -310,7 +310,7 @@ public:
* - where the read operation begin. * - where the read operation begin.
* *
* @param[in] onRead Completion callback which will accept the response of * @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. * in memory after the call.
* *
* @return BLE_ERROR_NONE if a read has been initiated. * @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 * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
* properties. * 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. * dynamic memory to store the use completion callback.
*/ */
ble_error_t read( ble_error_t read(
@ -331,8 +331,8 @@ public:
/** /**
* Perform a write without response procedure. * Perform a write without response procedure.
* *
* @note Write without responses are not acknowledged by the server and * @note The server does not acknowledge write without responses.
* therefore won't generate any event on the client side. * Therefore, they won't generate any event on the client side.
* *
* @param[in] length The amount of data being written. * @param[in] length The amount of data being written.
* @param[in] value The bytes being written. * @param[in] value The bytes being written.
@ -355,20 +355,20 @@ public:
* invoked with the descriptor discovered as parameter. When the process * invoked with the descriptor discovered as parameter. When the process
* ends, the callback onTermination is invoked. * ends, the callback onTermination is invoked.
* *
* @param[in] onDescriptorDiscovered Callback invoked when a descriptor is * @param[in] onDescriptorDiscovered Callback is invoked when a descriptor is
* discovered * 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; * @return BLE_ERROR_NONE if descriptor discovery is launched successfully;
* else an appropriate error. * else an appropriate error.
* *
* @note This function is a shorthand for * @note This function is shorthand for
* GattClient::discoverCharacteristicDescriptors therefore * GattClient::discoverCharacteristicDescriptors; therefore,
* GattClient::isCharacteristicDescriptorDiscoveryActive can be used to * GattClient::isCharacteristicDescriptorDiscoveryActive can be used to
* determine if the descriptor discovery and * determine the descriptor discovery and
* GattClient::terminateCharacteristicDescriptorDiscovery can be used to * GattClient::terminateCharacteristicDescriptorDiscovery can be used to
* ends the discovery process. * end the discovery process.
*/ */
ble_error_t discoverDescriptors( ble_error_t discoverDescriptors(
const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered, const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered,
@ -378,16 +378,16 @@ public:
/** /**
* Initiate a write procedure of the characteristic value. * 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 * 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(). * GattClient::onDataWritten().
* *
* Similarly to read responses, responses to write request of this * Similarly to read responses, responses to write request of this
* characteristic can be identified by their connection handle ( * 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 ( * 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(). * returned by getValueHandle().
* *
* @param[in] length The amount of data being written. * @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 * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
* properties. * 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. * on the number of bytes to write and the MTU size.
*/ */
ble_error_t write(uint16_t length, const uint8_t *value) const; 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. * Initiate a write procedure of the characteristic value.
* *
* Same as write(uint16_t, const uint8_t *) const but accept a completion * Same as write(uint16_t, const uint8_t *) const but accepts a completion
* callback which will be invoked when the server response is received. * callback, which is invoked when the server response is received.
* *
* @param[in] length The amount of bytes to write. * @param[in] length The amount of bytes to write.
* @param[in] value The bytes to write. * @param[in] value The bytes to write.
@ -492,13 +492,13 @@ public:
/** /**
* Return the last attribute handle of the characteristic definition. * Return the last attribute handle of the characteristic definition.
* *
* The attribute layout of a characteristic definition is as follows: * The attribute layout of a characteristic definition is:
* - Declaration attribute (see #getDeclHandle) * - Declaration attribute (see #getDeclHandle).
* - Value attribute (see #getValueHandle) * - Value attribute (see #getValueHandle).
* - Zero or more characteristic descriptors attribute. * - Zero or more characteristic descriptors attribute.
* *
* The last attribute handle is used internally to discover characteristic * 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]. * LastHandle].
* *
* @return The last handle of this characteristic definition. * @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() 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 const GattClient* getGattClient() const
{ {
@ -534,7 +534,7 @@ public:
* @brief Get the connection handle to the GattServer containing this * @brief Get the connection handle to the GattServer containing this
* characteristic. * characteristic.
* *
* @return Connection handle to the GattServer which contain this * @return Connection handle to the GattServer, which contains this
* characteristic. * characteristic.
*/ */
Gap::Handle_t getConnectionHandle() const Gap::Handle_t getConnectionHandle() const