Mbed OS Reference
Loading...
Searching...
No Matches
AdvertisingDataBuilder Class Reference

Build advertising data. More...

#include <AdvertisingDataBuilder.h>

Public Member Functions

 AdvertisingDataBuilder (mbed::Span< uint8_t > buffer)
 Advertising data needs a user-provided buffer to store the data. More...
 
 AdvertisingDataBuilder (uint8_t *buffer, size_t buffer_size)
 Advertising data needs a user provided buffer to store the data. More...
 
mbed::Span< const uint8_t > getAdvertisingData () const
 Get the subspan of the buffer containing valid data. More...
 
ble_error_t addData (adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
 Add a new field into the payload. More...
 
ble_error_t replaceData (adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
 Replace a new field into the payload. More...
 
ble_error_t appendData (adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
 Append data to an existing field in the payload. More...
 
ble_error_t removeData (adv_data_type_t advDataType)
 Remove existing date of given type. More...
 
ble_error_t addOrReplaceData (adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
 Adds a new field into the payload. More...
 
ble_error_t addOrAppendData (adv_data_type_t advDataType, mbed::Span< const uint8_t > fieldData)
 Adds a new field into the payload. More...
 
void clear ()
 Clears the advertising data payload. More...
 
ble_error_t setAppearance (adv_data_appearance_t appearance)
 Add device appearance in the advertising payload. More...
 
ble_error_t setFlags (adv_data_flags_t flags=adv_data_flags_t::default_flags)
 Add BLE flags in the advertising payload. More...
 
ble_error_t setTxPowerAdvertised (advertising_power_t txPower)
 Add the advertising TX in the advertising payload. More...
 
ble_error_t setName (const char *name, bool complete=true)
 Add device name to the advertising payload. More...
 
ble_error_t setManufacturerSpecificData (mbed::Span< const uint8_t > data)
 Add manufacturer-specific data to the advertising payload. More...
 
ble_error_t setAdvertisingInterval (adv_interval_t interval)
 Add advertising interval to the payload. More...
 
ble_error_t setConnectionIntervalPreference (conn_interval_t min, conn_interval_t max)
 Add connection interval preferences to the payload. More...
 
ble_error_t setServiceData (UUID service, mbed::Span< const uint8_t > data)
 Add service data data to the advertising payload. More...
 
ble_error_t setLocalServiceList (mbed::Span< const UUID > data, bool complete=true)
 Add local service IDs to the advertising payload. More...
 
ble_error_t setRequestedServiceList (mbed::Span< const UUID > data)
 Add a list of UUIDs of solicited services. More...
 
ble_error_t getData (mbed::Span< const uint8_t > &data, adv_data_type_t advDataType)
 Return a span of data containing the the type of data requested. More...
 

Detailed Description

Build advertising data.

The builder accepts an array of bytes in input and returns the result of the construction with getAdvertisingData().

Definition at line 48 of file AdvertisingDataBuilder.h.

Constructor & Destructor Documentation

◆ AdvertisingDataBuilder() [1/2]

AdvertisingDataBuilder ( mbed::Span< uint8_t >  buffer)

Advertising data needs a user-provided buffer to store the data.

Parameters
bufferBuffer used to store the data.
Note
Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.

◆ AdvertisingDataBuilder() [2/2]

AdvertisingDataBuilder ( uint8_t *  buffer,
size_t  buffer_size 
)

Advertising data needs a user provided buffer to store the data.

Parameters
bufferPointer to buffer to be used for storing advertising data.
buffer_sizeSize of the buffer.
Note
Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.

Member Function Documentation

◆ getAdvertisingData()

mbed::Span< const uint8_t > getAdvertisingData ( ) const

Get the subspan of the buffer containing valid data.

Returns
A Span containing the payload.

◆ addData()

ble_error_t addData ( adv_data_type_t  advDataType,
mbed::Span< const uint8_t >  fieldData 
)

Add a new field into the payload.

Returns an error if type is already present.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]advDataTypeThe type of the field to add.
[in]fieldDataSpan of data to add.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_OPERATION_NOT_PERMITTEDif data type already present.
BLE_ERROR_INVALID_PARAMif size of data is too big too fit in an individual data field.

◆ replaceData()

ble_error_t replaceData ( adv_data_type_t  advDataType,
mbed::Span< const uint8_t >  fieldData 
)

Replace a new field into the payload.

Will fail if type is not already present.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]advDataTypeThe type of the field to add.
[in]fieldDataSpan of data to add.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_NOT_FOUNDif data type not present.
BLE_ERROR_INVALID_PARAMif size of data is too big too fit in an individual data field.

◆ appendData()

ble_error_t appendData ( adv_data_type_t  advDataType,
mbed::Span< const uint8_t >  fieldData 
)

Append data to an existing field in the payload.

Will fail if type is not already present.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]advDataTypeThe type of the field to add.
[in]fieldDataSpan of data to add.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_NOT_FOUNDif data type not present.
BLE_ERROR_INVALID_PARAMif size of data is too big too fit in an individual data field.

◆ removeData()

ble_error_t removeData ( adv_data_type_t  advDataType)

Remove existing date of given type.

Will return an error if type is not present.

Parameters
[in]advDataTypeThe type of the field to remove.
Returns
BLE_ERROR_NONE returned on success, BLE_ERROR_INVALID_PARAM if field doesn't exist

◆ addOrReplaceData()

ble_error_t addOrReplaceData ( adv_data_type_t  advDataType,
mbed::Span< const uint8_t >  fieldData 
)

Adds a new field into the payload.

If the supplied advertising data type is already present in the advertising payload, then the value is replaced.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]advDataTypeThe type of the field to add.
[in]fieldDataSpan of data to add.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAMif size of data is too big too fit in an individual data field.

◆ addOrAppendData()

ble_error_t addOrAppendData ( adv_data_type_t  advDataType,
mbed::Span< const uint8_t >  fieldData 
)

Adds a new field into the payload.

If the supplied advertising data type is already present in the advertising payload, then the value is replaced.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]advDataTypeThe type of the field to add.
[in]fieldDataSpan of data to add.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAMif size of data is too big too fit in an individual data field.

◆ clear()

void clear ( )

Clears the advertising data payload.

Postcondition
getPayloadLen() returns 0.

◆ setAppearance()

ble_error_t setAppearance ( adv_data_appearance_t  appearance)

Add device appearance in the advertising payload.

Parameters
[in]appearanceThe appearance to advertise.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
Note
This call is equivalent to calling addOrReplaceData() with adv_data_type_t::APPEARANCE as the field type.

◆ setFlags()

ble_error_t setFlags ( adv_data_flags_t  flags = adv_data_flags_t::default_flags)

Add BLE flags in the advertising payload.

Parameters
[in]flagsBitfield describing the capability of the device. See allowed flags in Flags_t.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
Note
This call is equivalent to calling addOrReplaceData() with adv_data_type_t::FLAGS as the field type.

◆ setTxPowerAdvertised()

ble_error_t setTxPowerAdvertised ( advertising_power_t  txPower)

Add the advertising TX in the advertising payload.

Parameters
[in]txPowerTransmission power level in dB.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
Note
This call is equivalent to calling addOrReplaceData() with adv_data_type_t::TX_POWER_LEVEL as the field type.

◆ setName()

ble_error_t setName ( const char *  name,
bool  complete = true 
)

Add device name to the advertising payload.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]nameNull terminated string containing the name.
[in]completeComplete local name if true, otherwise
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAMif size of data is too big too fit in an individual data field.

◆ setManufacturerSpecificData()

ble_error_t setManufacturerSpecificData ( mbed::Span< const uint8_t >  data)

Add manufacturer-specific data to the advertising payload.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]dataNew data to be added.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAMif size of data is too big too fit in an individual data field or the data is too small (must contain 2 bytes of manufacturer ID)

◆ setAdvertisingInterval()

ble_error_t setAdvertisingInterval ( adv_interval_t  interval)

Add advertising interval to the payload.

This field can only carry 2 bytes.

Parameters
intervalInterval to advertise. Cannot be larger than 0xFFFF.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAMif interval value outside of valid range.

◆ setConnectionIntervalPreference()

ble_error_t setConnectionIntervalPreference ( conn_interval_t  min,
conn_interval_t  max 
)

Add connection interval preferences to the payload.

Parameters
minMinimum connection interval to advertise.
maxMaximum connection interval to advertise.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.

◆ setServiceData()

ble_error_t setServiceData ( UUID  service,
mbed::Span< const uint8_t >  data 
)

Add service data data to the advertising payload.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]serviceUUID of the service.
[in]dataNew data to be added.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAMif size of data is too big too fit in an individual data field.

◆ setLocalServiceList()

ble_error_t setLocalServiceList ( mbed::Span< const UUID data,
bool  complete = true 
)

Add local service IDs to the advertising payload.

If the data can't fit, no modification will take place.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]dataNew data to be added.
[in]completeTrue if this is a complete list.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAMif number of UUIDs of any one type is too high.

◆ setRequestedServiceList()

ble_error_t setRequestedServiceList ( mbed::Span< const UUID data)

Add a list of UUIDs of solicited services.

Note
Data size for individual types cannot exceed 255 bytes.
Parameters
[in]dataList of 128 or 16 bit service UUIDs.
Return values
BLE_ERROR_NONEon success.
BLE_ERROR_BUFFER_OVERFLOWif buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAMif number of UUIDs of any one type is too high.

◆ getData()

ble_error_t getData ( mbed::Span< const uint8_t > &  data,
adv_data_type_t  advDataType 
)

Return a span of data containing the the type of data requested.

Parameters
[out]dataSpan used to return the requested data.
[in]advDataTypeData type to return.
Returns
BLE_ERROR_NONE if data was found and BLE_ERROR_NOT_FOUND if not.