Rtos API example
GapAdvertisingData Class Reference
[Gap]
GAP advertising data builder. More...
#include <GapAdvertisingData.h>
Detailed Description
GAP advertising data builder.
Advertising data are used by broadcaster or peripheral to advertise state about the device. This class offers the function to add and update states present in an advertisement payload.
After construction, the advertising payload contained in the instance of GapAdvertisingData is empty. Adding new states and named fields can be achieved by invoking the function addData(), and updating existing state involves calling the function updateData().
Fields present in the payload can be retrieved by a call to the function findField.
This class includes shorthand for the most common fields:
- FLAGS: addFlags().
- APPEARANCE: addAppearance().
- TX_POWER_LEVEL: addTxPower().
Gap ⪆ static const uint8_t device_name[] = "HRM"; // construct an empty advertising payload GapAdvertisingData advertising_data; // set the flags of the advertising device advertising_data.addFlags( GapAdvertisingData::LE_GENERAL_DISCOVERABLE | GapAdvertisingData::BREDR_NOT_SUPPORTED ); // set the advertised name of the device advertising_data.addData( GapAdvertisingData::COMPLETE_LOCAL_NAME, device_name, sizeof(device_name) ); // update the advertising data of the gap payload gap.setAdvertisingPayload(advertising_data);
- Note:
- See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18 for further information on advertising and scan response data.
- 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).
- Each AD type has its own standardized assigned number, as the Bluetooth SIG defines: https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile.
- For convenience, all appropriate AD types are encapsulated in GapAdvertisingData::DataType.
- 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:
Record
length (1 byte).AD
Type (1 byte).AD
payload (optional; only present if record length > 1).
- This class takes care of properly formatting the payload, performs some basic checks on the payload length and tries to avoid common errors such as adding an exclusive AD field twice in the advertising or scan response payload.
Definition at line 113 of file GapAdvertisingData.h.
Member Typedef Documentation
typedef enum Appearance_t Appearance |
Alias for GapAdvertisingData::Appearance_t.
Definition at line 532 of file GapAdvertisingData.h.
typedef enum DataType_t DataType |
Alias for GapAdvertisingData::DataType_t.
Definition at line 220 of file GapAdvertisingData.h.
Alias for GapAdvertisingData::Flags_t.
Definition at line 266 of file GapAdvertisingData.h.
Member Enumeration Documentation
enum Appearance_t |
Enumeration of values for the DataType_t::APPEARANCE.
These values describe the physical shape or appearance of the device.
- Source
Bluetooth
Core Specification Supplement, Part A, Section 1.12.Bluetooth
Core Specification 4.0 (Vol. 3), Part C, Section 12.2.https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml.
- Enumerator:
Definition at line 279 of file GapAdvertisingData.h.
enum DataType_t |
List of standard Advertising Data types.
These AD types are used to describe the capabilities of the peripheral and are inserted inside the advertising or scan response payloads.
- Source
Bluetooth
Core Specification 4.0 (Vol. 3), Part C, Section 11, 18.https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile.
- Enumerator:
FLAGS Flags, refer to GapAdvertisingData::Flags_t.
INCOMPLETE_LIST_16BIT_SERVICE_IDS Incomplete list of 16-bit Service IDs.
COMPLETE_LIST_16BIT_SERVICE_IDS Complete list of 16-bit Service IDs.
INCOMPLETE_LIST_32BIT_SERVICE_IDS Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0).
COMPLETE_LIST_32BIT_SERVICE_IDS Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0).
INCOMPLETE_LIST_128BIT_SERVICE_IDS Incomplete list of 128-bit Service IDs.
COMPLETE_LIST_128BIT_SERVICE_IDS Complete list of 128-bit Service IDs.
SHORTENED_LOCAL_NAME Shortened Local Name.
COMPLETE_LOCAL_NAME Complete Local Name.
TX_POWER_LEVEL TX Power Level (in dBm).
DEVICE_ID Device ID.
SLAVE_CONNECTION_INTERVAL_RANGE Slave Connection Interval Range.
LIST_128BIT_SOLICITATION_IDS List of 128-bit service UUIDs the device is looking for.
SERVICE_DATA Service Data.
APPEARANCE Appearance, refer to GapAdvertisingData::Appearance_t.
ADVERTISING_INTERVAL Advertising Interval.
MANUFACTURER_SPECIFIC_DATA Manufacturer Specific Data.
Definition at line 127 of file GapAdvertisingData.h.
enum Flags_t |
Enumeration of allowed flags for DataType_t::FLAGS.
- Note:
- DataType_t::FLAGS may contain several flags that the bitwise and operator (ex.LE_GENERAL_DISCOVERABLE & BREDR_NOT_SUPPORTED) assembled.
- Source
Bluetooth
Core Specification 4.0 (Vol. 3), Part C, Section 18.1.
- Enumerator:
Definition at line 232 of file GapAdvertisingData.h.
Constructor & Destructor Documentation
GapAdvertisingData | ( | void | ) |
Construct a GapAdvertising instance with an empty payload.
Definition at line 537 of file GapAdvertisingData.h.
Member Function Documentation
ble_error_t addAppearance | ( | Appearance | appearance = GENERIC_TAG ) |
Add device appearance in the advertising payload.
- Parameters:
-
[in] appearance The appearance to advertise.
- Returns:
- BLE_ERROR_NONE on success.
- BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow.
- Note:
- This call is equivalent to calling addData() with GapAdvertisingData::APPEARANCE as the field type.
Definition at line 615 of file GapAdvertisingData.h.
ble_error_t addData | ( | DataType_t | advDataType, |
const uint8_t * | payload, | ||
uint8_t | len | ||
) |
Adds a new field into the payload.
If the supplied advertising data type is already present in the advertising payload, then the value is updated.
- Parameters:
-
[in] advDataType The type of the field to add. [in] payload Pointer to the value of the field to add. [in] len Size in bytes of the value to add.
- Returns:
- BLE_ERROR_NONE on success.
- BLE_ERROR_BUFFER_OVERFLOW if the new value causes the advertising buffer to overflow.
- Note:
- When the specified data 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, COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS, the supplied value is appended to the values present in the payload.
Definition at line 563 of file GapAdvertisingData.h.
ble_error_t addFlags | ( | uint8_t | flags = LE_GENERAL_DISCOVERABLE ) |
Add BLE flags in the advertising payload.
- Parameters:
-
[in] flags Bitfield describing the capability of the device. See allowed flags in Flags_t.
- Returns:
- BLE_ERROR_NONE on success.
- BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow.
- Note:
- This call is equivalent to calling addData() with GapAdvertisingData::FLAGS as the field type.
Definition at line 634 of file GapAdvertisingData.h.
ble_error_t addTxPower | ( | int8_t | txPower ) |
Add the advertising TX in the advertising payload.
- Parameters:
-
[in] txPower Transmission power level in dB.
- Returns:
- BLE_ERROR_NONE on success.
- BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the advertising buffer to overflow.
- Note:
- This call is equivalent to calling addData() with GapAdvertisingData::TX_POWER_LEVEL as the field type.
Definition at line 651 of file GapAdvertisingData.h.
void clear | ( | void | ) |
Clears the advertising data payload.
- Postcondition:
- getPayloadLen() returns 0.
Definition at line 662 of file GapAdvertisingData.h.
const uint8_t* findField | ( | DataType_t | type ) | const |
Search advertisement data for a specific field.
- Parameters:
-
[in] type The type of the field to find.
- Returns:
- A pointer to the first element in the field if found. The first element being the length of the field followed by the value of the field.
- NULL if the field is not present in the payload.
Definition at line 709 of file GapAdvertisingData.h.
uint16_t getAppearance | ( | void | ) | const |
Get the appearance set.
If no value has been set, this function returns GENERIC_TAG.
- Returns:
- The appearance value set for this device.
Definition at line 695 of file GapAdvertisingData.h.
const uint8_t* getPayload | ( | void | ) | const |
Get the pointer to the advertising payload bytes.
- Returns:
- A pointer to the payload.
Definition at line 673 of file GapAdvertisingData.h.
uint8_t getPayloadLen | ( | void | ) | const |
Get the payload length.
- Returns:
- The payload length in bytes.
Definition at line 683 of file GapAdvertisingData.h.
ble_error_t updateData | ( | DataType_t | advDataType, |
const uint8_t * | payload, | ||
uint8_t | len | ||
) |
Update a specific field in the advertising payload.
- Parameters:
-
[in] advDataType The type of the field to update. [in] payload Pointer to the updated value of the field. [in] len Size of the new value in bytes.
- Returns:
- BLE_ERROR_NONE returned on success.
- BLE_ERROR_UNSPECIFIED if the specified field is not found,
- BLE_ERROR_BUFFER_OVERFLOW if the new value causes the advertising buffer to overflow.
Definition at line 589 of file GapAdvertisingData.h.
Generated on Sun Jul 17 2022 08:25:40 by 1.7.2