Cristi Stoican
jgh
Fork of
BLE_API
by 
Bluetooth Low Energy
Diff: ble/DiscoveredCharacteristic.h
- Revision:
- 1183:1589830dbdb7
- Parent:
- 1179:4ab722f8dca0
--- a/ble/DiscoveredCharacteristic.h Wed Apr 06 19:15:34 2016 +0100
+++ b/ble/DiscoveredCharacteristic.h Wed Apr 06 19:15:36 2016 +0100
@@ -28,20 +28,24 @@
* @brief Representation of a characteristic discovered during a GattClient
* discovery procedure (see GattClient::launchServiceDiscovery ).
*
- * @detail Provide detailed informations about a discovered characteristic like:
- * - Its UUID (see #getUUID).
+ * @details Provide detailed informations about a discovered characteristic like:
+ * - Its UUID (see getUUID()).
* - The most important handles of the characteristic definition
- * (see #getDeclHandle, #getValueHandle, #getLastHandle )
- * - Its properties (see #getProperties).
+ * (see getDeclHandle(), getValueHandle(), getLastHandle())
+ * - Its properties (see getProperties()).
* This class also provide functions to operate on the characteristic:
- * - Read the characteristic value (see #read)
- * - Writing a characteristic value (see #write or #writeWoResponse)
+ * - Read the characteristic value (see read())
+ * - Writing a characteristic value (see write() or writeWoResponse())
* - Discover descriptors inside the characteristic definition. These descriptors
* extends the characteristic. More information about descriptor usage is
* available in DiscoveredCharacteristicDescriptor class.
*/
class DiscoveredCharacteristic {
public:
+ /**
+ * Structure that encapsulates the properties of a discovered
+ * characteristic.
+ */
struct Properties_t {
uint8_t _broadcast :1; /**< Broadcasting the value permitted. */
uint8_t _read :1; /**< Reading the value permitted. */
@@ -52,19 +56,81 @@
uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
public:
- bool broadcast(void) const {return _broadcast; }
- bool read(void) const {return _read; }
- bool writeWoResp(void) const {return _writeWoResp; }
- bool write(void) const {return _write; }
- bool notify(void) const {return _notify; }
- bool indicate(void) const {return _indicate; }
- bool authSignedWrite(void) const {return _authSignedWrite;}
+ /**
+ * @brief Check if broadcasting is permitted.
+ *
+ * @return true if broadcasting the value is permitted, and false
+ * otherwise.
+ */
+ bool broadcast(void) const {
+ return _broadcast;
+ }
+
+ /**
+ * @brief Check reading is permitted.
+ *
+ * @return true if reading the value is permitted, and false
+ * otherwise.
+ */
+ bool read(void) const {
+ return _read;
+ }
+
+ /**
+ * @brief Check if writing with Write Command is permitted.
+ *
+ * @return true if writing the value with Write Command is permitted,
+ * false otherwise.
+ */
+ bool writeWoResp(void) const {
+ return _writeWoResp;
+ }
+
+ /**
+ * @brief Check if writing with Write Request is permitted.
+ *
+ * @return true if writing the value with Write Request is permitted,
+ * false otherwise.
+ */
+ bool write(void) const {
+ return _write;
+ }
+
+ /**
+ * @brief Check notifications are permitted.
+ *
+ * @return true if notifications of the value are permitted, false
+ * otherwise.
+ */
+ bool notify(void) const {
+ return _notify;
+ }
+
+ /**
+ * @brief Check if indications are permitted.
+ *
+ * @return true if indications of the value are permitted, false
+ * otherwise.
+ */
+ bool indicate(void) const {
+ return _indicate;
+ }
+
+ /**
+ * @brief Check if writing with Signed Write Command is permitted.
+ *
+ * @return true if writing the value with Signed Write Command is
+ * permitted, false otherwise.
+ */
+ bool authSignedWrite(void) const {
+ return _authSignedWrite;
+ }
/**
* @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t
*
- * @param lhs[in] The left hand side of the equality expression
- * @param rhs[in] 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, false otherwise.
*/
@@ -101,8 +167,9 @@
* than ATT_MTU - 1, this function must be called multiple times with
* appropriate offset to read the complete value.
*
- * @param offset[in] The position - in the characteristic value bytes stream - where
- * the read operation begin.
+ * @param[in] offset
+ * The position - in the characteristic value bytes stream - where
+ * the read operation begin.
*
* @return BLE_ERROR_NONE if a read has been initiated, or
* BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
@@ -115,9 +182,11 @@
* @brief Same as #read(uint16_t) const but allow the user to register a callback
* which will be fired once the read is done.
*
- * @param offset[in] The position - in the characteristic value bytes stream - where
- * the read operation begin.
- * @param onRead[in] Continuation of the read operation
+ * @param[in] offset
+ * The position - in the characteristic value bytes stream - where
+ * the read operation begin.
+ * @param[in] onRead
+ * Continuation of the read operation
*/
ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
@@ -174,12 +243,21 @@
ble_error_t write(uint16_t length, const uint8_t *value) const;
/**
- * Same as #write(uint16_t, const uint8_t *) const but register a callback
+ * Same as write(uint16_t, const uint8_t *) const but register a callback
* which will be called once the data has been written.
*
- * @param[in] length The amount of bytes to write.
- * @param[in] value The bytes to write.
- * @param[in] onRead Continuation callback for the write operation
+ * @param[in] length
+ * The amount of bytes to write.
+ * @param[in] value
+ * The bytes to write.
+ * @param[in] onWrite
+ * Continuation callback for the write operation
+ *
+ * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
+ * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
+ * BLE_STACK_BUSY if some client procedure is already in progress, or
+ * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
+ * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
*/
ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onWrite) const;
@@ -206,7 +284,7 @@
/**
* @brief Get the declaration handle of this characteristic.
- * @detail The declaration handle is the first handle of a characteristic
+ * @details 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
@@ -275,8 +353,10 @@
/**
* @brief "Equal to" operator for DiscoveredCharacteristic
*
- * @param lhs[in] The left hand side of the equality expression
- * @param rhs[in] 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, false otherwise.
*/
@@ -293,10 +373,12 @@
/**
* @brief "Not equal to" operator for DiscoveredCharacteristic
*
- * @param lhs[in] The right hand side of the expression
- * @param rhs[in] The left hand side of the expression
+ * @param[in] lhs
+ * The right hand side of the expression
+ * @param[in] rhs
+ * The left hand side of the expression
*
- * @return true if operands are not equals, false otherwise.
+ * @return true if operands are not equal, false otherwise.
*/
friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
return !(lhs == rhs);
@@ -314,15 +396,37 @@
}
protected:
+ /**
+ * Pointer to the underlying GattClient for this DiscoveredCharacteristic object.
+ */
GattClient *gattc;
protected:
+ /**
+ * Discovered characteristic's UUID.
+ */
UUID uuid;
+ /**
+ * Hold the configured properties of the discovered characteristic.
+ * For more information refer to Properties_t.
+ */
Properties_t props;
+ /**
+ * Value handle of the discovered characteristic's declaration attribute.
+ */
GattAttribute::Handle_t declHandle;
+ /**
+ * Value handle of the discovered characteristic's value attribute.
+ */
GattAttribute::Handle_t valueHandle;
+ /**
+ * Value handle of the discovered characteristic's last attribute.
+ */
GattAttribute::Handle_t lastHandle;
+ /**
+ * Handle for the connection where the characteristic was discovered.
+ */
Gap::Handle_t connHandle;
};