just a fork

Fork of BLE_API by Bluetooth Low Energy

Revision:
1179:4ab722f8dca0
Parent:
1172:4aad76f757e6
Child:
1183:1589830dbdb7
--- a/ble/GapAdvertisingData.h	Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GapAdvertisingData.h	Wed Apr 06 19:15:30 2016 +0100
@@ -24,125 +24,125 @@
 
 #define GAP_ADVERTISING_DATA_MAX_PAYLOAD        (31)
 
-/**
- * @brief This class provides several helper functions to generate properly
- *        formatted GAP Advertising and Scan Response data payloads.
- *
- * @note See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18
- *       for further information on Advertising and Scan Response data.
- *
- * @par Advertising and Scan Response Payloads
- *      Advertising data and Scan Response data are organized around a set of
- *      data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core
- *      Specification v4.0, Vol. 3, Part C, Sections 11 and 18).
- *
- * @par
- *      Each AD type has its own standardized assigned number, as defined
- *      by the Bluetooth SIG:
- *      https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile.
- *
- * @par
- *      For convenience, all appropriate AD types are encapsulated
- *      in GapAdvertisingData::DataType.
- *
- * @par
- *      Before the AD Types and their payload (if any) can be inserted into
- *      the Advertising or Scan Response frames, they need to be formatted as
- *      follows:
- *
- * @li @c Record length (1 byte).
- * @li @c AD Type (1 byte).
- * @li @c AD payload (optional; only present if record length > 1).
- *
- * @par
- *      This class takes care of properly formatting the payload, performs
- *      some basic checks on the payload length, and tries to avoid common
- *      errors like adding an exclusive AD field twice in the Advertising
- *      or Scan Response payload.
- *
- * @par EXAMPLE
- *
- * @code
- *
- * // ToDo
- *
- * @endcode
- */
+/**************************************************************************/
+/*!
+    \brief
+    This class provides several helper functions to generate properly
+    formatted GAP Advertising and Scan Response data payloads.
+
+    \note
+    See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18
+    for further information on Advertising and Scan Response data.
+
+    \par Advertising and Scan Response Payloads
+    Advertising data and Scan Response data are organized around a set of
+    data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core
+    Specification v4.0, Vol. 3, Part C, Sections 11 and 18).
+
+    \par
+    Each AD type has its own standardized assigned number, as defined
+    by the Bluetooth SIG:
+    https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
+
+    \par
+    For convenience, all appropriate AD types are encapsulated
+    in GapAdvertisingData::DataType.
+
+    \par
+    Before the AD Types and their payload (if any) can be inserted into
+    the Advertising or Scan Response frames, they need to be formatted as
+    follows:
+
+    \li \c Record length (1 byte).
+    \li \c AD Type (1 byte).
+    \li \c AD payload (optional; only present if record length > 1).
+
+    \par
+    This class takes care of properly formatting the payload, performs
+    some basic checks on the payload length, and tries to avoid common
+    errors like adding an exclusive AD field twice in the Advertising
+    or Scan Response payload.
+
+    \par EXAMPLE
+
+    \code
+
+    // ToDo
+
+    \endcode
+*/
+/**************************************************************************/
 class GapAdvertisingData
 {
 public:
+    /**********************************************************************/
     /*!
-     * @brief A list of Advertising Data types commonly used by peripherals.
-     *        These AD types are used to describe the capabilities of the
-     *        peripheral, and are inserted inside the advertising or scan
-     *        response payloads.
-     *
-     * @par Source
-     *
-     * @li @c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 11, 18.
-     * @li @c https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile.
-     */
+        \brief
+        A list of Advertising Data types commonly used by peripherals.
+        These AD types are used to describe the capabilities of the
+        peripheral, and are inserted inside the advertising or scan
+        response payloads.
+
+        \par Source
+        \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 11, 18
+        \li \c https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
+    */
+    /**********************************************************************/
     enum DataType_t {
-        FLAGS                              = 0x01, /**< Flags, refer to GapAdvertisingData::Flags_t. */
-        INCOMPLETE_LIST_16BIT_SERVICE_IDS  = 0x02, /**< Incomplete list of 16-bit Service IDs. */
-        COMPLETE_LIST_16BIT_SERVICE_IDS    = 0x03, /**< Complete list of 16-bit Service IDs. */
-        INCOMPLETE_LIST_32BIT_SERVICE_IDS  = 0x04, /**< Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0). */
-        COMPLETE_LIST_32BIT_SERVICE_IDS    = 0x05, /**< Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0). */
-        INCOMPLETE_LIST_128BIT_SERVICE_IDS = 0x06, /**< Incomplete list of 128-bit Service IDs. */
-        COMPLETE_LIST_128BIT_SERVICE_IDS   = 0x07, /**< Complete list of 128-bit Service IDs. */
-        SHORTENED_LOCAL_NAME               = 0x08, /**< Shortened Local Name. */
-        COMPLETE_LOCAL_NAME                = 0x09, /**< Complete Local Name. */
-        TX_POWER_LEVEL                     = 0x0A, /**< TX Power Level (in dBm). */
-        DEVICE_ID                          = 0x10, /**< Device ID. */
-        SLAVE_CONNECTION_INTERVAL_RANGE    = 0x12, /**< Slave Connection Interval Range. */
-        LIST_128BIT_SOLICITATION_IDS       = 0x15, /**< List of 128 bit service UUIDs the device is looking for. */
-        SERVICE_DATA                       = 0x16, /**< Service Data. */
-        APPEARANCE                         = 0x19, /**< Appearance, refer to GapAdvertisingData::Appearance_t. */
-        ADVERTISING_INTERVAL               = 0x1A, /**< Advertising Interval. */
-        MANUFACTURER_SPECIFIC_DATA         = 0xFF  /**< Manufacturer Specific Data. */
+        FLAGS                              = 0x01, /**< \ref *Flags */
+        INCOMPLETE_LIST_16BIT_SERVICE_IDS  = 0x02, /**< Incomplete list of 16-bit Service IDs */
+        COMPLETE_LIST_16BIT_SERVICE_IDS    = 0x03, /**< Complete list of 16-bit Service IDs */
+        INCOMPLETE_LIST_32BIT_SERVICE_IDS  = 0x04, /**< Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0) */
+        COMPLETE_LIST_32BIT_SERVICE_IDS    = 0x05, /**< Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0) */
+        INCOMPLETE_LIST_128BIT_SERVICE_IDS = 0x06, /**< Incomplete list of 128-bit Service IDs */
+        COMPLETE_LIST_128BIT_SERVICE_IDS   = 0x07, /**< Complete list of 128-bit Service IDs */
+        SHORTENED_LOCAL_NAME               = 0x08, /**< Shortened Local Name */
+        COMPLETE_LOCAL_NAME                = 0x09, /**< Complete Local Name */
+        TX_POWER_LEVEL                     = 0x0A, /**< TX Power Level (in dBm) */
+        DEVICE_ID                          = 0x10, /**< Device ID */
+        SLAVE_CONNECTION_INTERVAL_RANGE    = 0x12, /**< Slave Connection Interval Range */
+        LIST_128BIT_SOLICITATION_IDS       = 0x15, /**< List of 128 bit service UUIDs the device is looking for */
+        SERVICE_DATA                       = 0x16, /**< Service Data */
+        APPEARANCE                         = 0x19, /**< \ref Appearance */
+        ADVERTISING_INTERVAL               = 0x1A, /**< Advertising Interval */
+        MANUFACTURER_SPECIFIC_DATA         = 0xFF  /**< Manufacturer Specific Data */
     };
-    /**
-     * Type alias for GapAdvertisingData::DataType_t.
-     *
-     * @deprecated  This type alias will be dropped in future releases.
-     */
-    typedef enum DataType_t DataType;
+    typedef enum DataType_t DataType; /* Deprecated type alias. This may be dropped in a future release. */
+
+    /**********************************************************************/
+    /*!
+        \brief
+        A list of values for the FLAGS AD Type.
 
-    /**
-     *  @brief A list of values for the FLAGS AD Type.
-     *
-     *  @note You can use more than one value in the FLAGS AD Type (ex.
-     *        LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED).
-     *
-     *  @par Source
-     *
-     *  @li @c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1.
-     */
+        \note
+        You can use more than one value in the FLAGS AD Type (ex.
+        LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED).
+
+        \par Source
+        \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1
+    */
+    /**********************************************************************/
     enum Flags_t {
-        LE_LIMITED_DISCOVERABLE = 0x01, /**< Peripheral device is discoverable for a limited period of time. */
+        LE_LIMITED_DISCOVERABLE = 0x01, /**< *Peripheral device is discoverable for a limited period of time. */
         LE_GENERAL_DISCOVERABLE = 0x02, /**< Peripheral device is discoverable at any moment. */
         BREDR_NOT_SUPPORTED     = 0x04, /**< Peripheral device is LE only. */
         SIMULTANEOUS_LE_BREDR_C = 0x08, /**< Not relevant - central mode only. */
         SIMULTANEOUS_LE_BREDR_H = 0x10  /**< Not relevant - central mode only. */
     };
-    /**
-     * Type alias for GapAdvertisingData::Flags_t.
-     *
-     * @deprecated  This type alias will be dropped in future releases.
-     */
-    typedef enum Flags_t Flags;
+    typedef enum Flags_t Flags; /* Deprecated type alias. This may be dropped in a future release. */
 
-    /**
-     *  @brief
-     *  A list of values for the APPEARANCE AD Type, which describes the
-     *  physical shape or appearance of the device.
-     *
-     *  @par Source
-     *
-     *  @li @c Bluetooth Core Specification Supplement, Part A, Section 1.12.
-     *  @li @c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 12.2.
-     *  @li @c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml.
-     */
+    /**********************************************************************/
+    /*!
+        \brief
+        A list of values for the APPEARANCE AD Type, which describes the
+        physical shape or appearance of the device.
+
+        \par Source
+        \li \c Bluetooth Core Specification Supplement, Part A, Section 1.12
+        \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 12.2
+        \li \c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml
+    */
+    /**********************************************************************/
     enum Appearance_t {
         UNKNOWN                                        = 0,     /**< Unknown or unspecified appearance type. */
         GENERIC_PHONE                                  = 64,    /**< Generic Phone. */
@@ -194,22 +194,14 @@
         OUTDOOR_LOCATION_POD                           = 5187,  /**< Outdoor Location Pod. */
         OUTDOOR_LOCATION_AND_NAVIGATION_POD            = 5188   /**< Outdoor Location and Navigation Pod. */
     };
-    /**
-     * Type alias for GapAdvertisingData::Appearance_t.
-     *
-     * @deprecated  This type alias will be dropped in future releases.
-     */
-    typedef enum Appearance_t Appearance;
+    typedef enum Appearance_t Appearance; /* Deprecated type alias. This may be dropped in a future release. */
 
-    /**
-     * Empty constructor.
-     */
     GapAdvertisingData(void) : _payload(), _payloadLen(0), _appearance(GENERIC_TAG) {
         /* empty */
     }
 
     /**
-     * Adds advertising data based on the specified AD type (see GapAdvertisingData::DataType_t).
+     * Adds advertising data based on the specified AD type (see DataType).
      * If the supplied AD type is already present in the advertising
      * payload, then the value is updated.
      *
@@ -230,14 +222,14 @@
      */
     ble_error_t addData(DataType_t advDataType, const uint8_t *payload, uint8_t len)
     {
-        /* Find field */
+        // find field
         uint8_t* field = findField(advDataType);
 
         if (field) {
-            /* Field type already exist, either add to field or replace */
+            // Field type already exist, either add to field or replace
             return addField(advDataType, payload, len, field);
         } else {
-            /* Field doesn't exists, insert new */
+            // field doesn't exists, insert new
             return appendField(advDataType, payload, len);
         }
     }
@@ -257,14 +249,14 @@
      */
     ble_error_t updateData(DataType_t advDataType, const uint8_t *payload, uint8_t len)
     {
-        /* Find field */
+        // find field
         uint8_t* field = findField(advDataType);
 
         if (field) {
-            /* Field type already exist, replace field contents */
+            // Field type already exist, replace field contents
             return updateField(advDataType, payload, len, field);
         } else {
-            /* field doesn't exists, return an error */
+            // field doesn't exists, return an error
             return BLE_ERROR_UNSPECIFIED;
         }
     }
@@ -276,7 +268,7 @@
      *           The APPEARANCE value to add.
      *
      * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
-     *         advertising buffer to overflow, else BLE_ERROR_NONE.
+     * advertising buffer to overflow, else BLE_ERROR_NONE.
      */
     ble_error_t addAppearance(Appearance appearance = GENERIC_TAG) {
         _appearance = appearance;
@@ -285,17 +277,16 @@
 
     /**
      * Helper function to add FLAGS data to the advertising payload.
-     *
-     * @param[in]  flags
-     *               LE_LIMITED_DISCOVERABLE
-     *                 The peripheral is discoverable for a limited period of time.
-     *               LE_GENERAL_DISCOVERABLE
-     *                 The peripheral is permanently discoverable.
-     *               BREDR_NOT_SUPPORTED
-     *                 This peripheral is a Bluetooth Low Energy only device (no EDR support).
+     * @param  flags
+     *           LE_LIMITED_DISCOVERABLE
+     *             The peripheral is discoverable for a limited period of time.
+     *           LE_GENERAL_DISCOVERABLE
+     *             The peripheral is permanently discoverable.
+     *           BREDR_NOT_SUPPORTED
+     *             This peripheral is a Bluetooth Low Energy only device (no EDR support).
      *
      * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
-     *         advertising buffer to overflow, else BLE_ERROR_NONE.
+     * advertising buffer to overflow, else BLE_ERROR_NONE.
      */
     ble_error_t addFlags(uint8_t flags = LE_GENERAL_DISCOVERABLE) {
         return addData(GapAdvertisingData::FLAGS, &flags, 1);
@@ -305,7 +296,7 @@
      * Helper function to add TX_POWER_LEVEL data to the advertising payload.
      *
      * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
-     *         advertising buffer to overflow, else BLE_ERROR_NONE.
+     * advertising buffer to overflow, else BLE_ERROR_NONE.
      */
     ble_error_t addTxPower(int8_t txPower) {
         /* To Do: Basic error checking to make sure txPower is in range. */
@@ -321,40 +312,30 @@
     }
 
     /**
-     * Access the current payload.
-     *
-     * @return A pointer to the current payload.
+     * Returns a pointer to the current payload.
      */
     const uint8_t *getPayload(void) const {
         return _payload;
     }
 
     /**
-     * Get the current payload length.
-     *
-     * @return The current payload length (0..31 bytes).
+     * Returns the current payload length (0..31 bytes).
      */
     uint8_t     getPayloadLen(void) const {
         return _payloadLen;
     }
 
     /**
-     * Get the current appearance value.
-     *
-     * @return The 16-bit appearance value for this device.
+     * Returns the 16-bit appearance value for this device.
      */
     uint16_t    getAppearance(void) const {
         return (uint16_t)_appearance;
     }
 
     /**
-     * Search advertisement data for a specific field.
-     *
-     * @param[in] type
-     *              The type of the field to find.
-     *
-     * @return A pointer to the first element in the field if found, NULL otherwise.
-     *         Where the first element is the length of the field.
+     * Search advertisement data for field.
+     * Returns pointer to the first element in the field if found, NULL otherwise.
+     * Where the first element is the length of the field.
      */
     const uint8_t* findField(DataType_t type) const {
         return findField(type);
@@ -362,19 +343,7 @@
 
 private:
     /**
-     * Append advertising data based on the specified AD type (see
-     * GapAdvertisingData::DataType_t).
-     *
-     * @param[in] advDataType
-     *              The type of the new data.
-     * @param[in] payload
-     *              A pointer to the data to be appended to the advertising
-     *              payload.
-     * @param[in] len
-     *              The length of th data pointed to by @p payload.
-     *
-     * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
-     *         advertising buffer to overflow, else BLE_ERROR_NONE.
+     * Append advertising data based on the specified AD type (see DataType)
      */
     ble_error_t appendField(DataType advDataType, const uint8_t *payload, uint8_t len)
     {
@@ -400,15 +369,11 @@
 
     /**
      * Search advertisement data for field.
-     *
-     * @param[in] type
-     *              The type of the data to find.
-     *
-     * @return A pointer to the first element in the field if found, NULL
-     *         otherwise. Where the first element is the length of the field.
+     * Returns pointer to the first element in the field if found, NULL otherwise.
+     * Where the first element is the length of the field.
      */
     uint8_t* findField(DataType_t type) {
-        /* Scan through advertisement data */
+        // scan through advertisement data
         for (uint8_t idx = 0; idx < _payloadLen; ) {
             uint8_t fieldType = _payload[idx + 1];
 
@@ -416,11 +381,11 @@
                 return &_payload[idx];
             }
 
-            /* Advance to next field */
+            // advance to next field
             idx += _payload[idx] + 1;
         }
 
-        /* Field not found */
+        // field not found
         return NULL;
     }
 
@@ -428,17 +393,6 @@
      * Given the a pointer to a field in the advertising payload it replaces
      * the existing data in the field with the supplied data.
      *
-     * @param[in] advDataType
-     *              The type of the new data.
-     * @param[in] payload
-     *              A pointer to the data to be added to the advertising
-     *              payload.
-     * @param[in] len
-     *              The length of th data pointed to by @p payload.
-     * @param[in] field
-     *              A pointer to the field of type @p advDataType in the
-     *              advertising buffer.
-     *
      * When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
      * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
      * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
@@ -446,14 +400,14 @@
      * supplied value is appended to the values previously added to the
      * payload.
      *
-     * @return BLE_ERROR_NONE on success.
+     * Returns BLE_ERROR_NONE on success.
      */
     ble_error_t addField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field)
     {
         ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW;
 
         switch(advDataType) {
-            /* These fields will have the new data appended if there is sufficient space */
+            // These fields will have the new data appended if there is sufficient space
             case INCOMPLETE_LIST_16BIT_SERVICE_IDS:
             case COMPLETE_LIST_16BIT_SERVICE_IDS:
             case INCOMPLETE_LIST_32BIT_SERVICE_IDS:
@@ -461,13 +415,11 @@
             case INCOMPLETE_LIST_128BIT_SERVICE_IDS:
             case COMPLETE_LIST_128BIT_SERVICE_IDS:
             case LIST_128BIT_SOLICITATION_IDS: {
-                /* Check if data fits */
+                // check if data fits
                 if ((_payloadLen + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
-                    /*
-                     * Make room for new field by moving the remainder of the
-                     * advertisement payload "to the right" starting after the
-                     * TYPE field.
-                     */
+                    // make room for new field by moving the remainder of the
+                    // advertisement payload "to the right" starting after the
+                    // TYPE field.
                     uint8_t* end = &_payload[_payloadLen];
 
                     while (&field[1] < end) {
@@ -475,12 +427,12 @@
                         end--;
                     }
 
-                    /* Insert new data */
+                    // insert new data
                     for (uint8_t idx = 0; idx < len; idx++) {
                         field[2 + idx] = payload[idx];
                     }
 
-                    /* Increment lengths */
+                    // increment lengths
                     field[0] += len;
                     _payloadLen += len;
 
@@ -489,7 +441,7 @@
 
                 break;
             }
-            /* These fields will be overwritten with the new value */
+            //  These fields will be overwritten with the new value
             default: {
                 result = updateField(advDataType, payload, len, field);
 
@@ -503,26 +455,14 @@
     /**
      * Given the a pointer to a field in the advertising payload it replaces
      * the existing data in the field with the supplied data.
-     *
-     * @param[in] advDataType
-     *              The type of the data to be updated.
-     * @param[in] payload
-     *              A pointer to the data to be updated to the advertising
-     *              payload.
-     * @param[in] len
-     *              The length of th data pointed to by @p payload.
-     * @param[in] field
-     *              A pointer to the field of type @p advDataType in the
-     *              advertising buffer.
-     *
-     * @return BLE_ERROR_NONE on success.
+     * Returns BLE_ERROR_NONE on success.
      */
     ble_error_t updateField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field)
     {
         ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW;
         uint8_t dataLength = field[0] - 1;
 
-        /* New data has same length, do in-order replacement */
+        // new data has same length, do in-order replacement
         if (len == dataLength) {
             for (uint8_t idx = 0; idx < dataLength; idx++) {
                 field[2 + idx] = payload[idx];
@@ -530,19 +470,19 @@
 
             result = BLE_ERROR_NONE;
         } else {
-            /* Check if data fits */
+            // check if data fits
             if ((_payloadLen - dataLength + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
 
-                /* Remove old field */
+                // remove old field
                 while ((field + dataLength + 2) < &_payload[_payloadLen]) {
                     *field = field[dataLength + 2];
                     field++;
                 }
 
-                /* Reduce length */
+                // reduce length
                 _payloadLen -= dataLength + 2;
 
-                /* Add new field */
+                // add new field
                 result = appendField(advDataType, payload, len);
             }
         }
@@ -550,18 +490,9 @@
         return result;
     }
 
-    /**
-     * The advertising data buffer
-     */
     uint8_t  _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD];
-    /**
-     * The length of the data added to the advertising buffer.
-     */
     uint8_t  _payloadLen;
-    /**
-     * Appearance value.
-     */
     uint16_t _appearance;
 };
 
-#endif /* ifndef __GAP_ADVERTISING_DATA_H__ */
\ No newline at end of file
+#endif // ifndef __GAP_ADVERTISING_DATA_H__
\ No newline at end of file