Bkap
/
BLE_API
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of
BLE_API
by 
Bluetooth Low Energy
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