Matthew Lister
BLE_API
Diff: ble/GapAdvertisingData.h
- 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