Diff: ble/DiscoveredCharacteristic.h

Revision:

1184:1589830dbdb7

Parent:

1180: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;
 };