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 ( mbed::Span< uint8_t > buffer )

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

Parameters

buffer Buffer used to store the data.

Note: Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.

AdvertisingDataBuilder	(	uint8_t *	buffer,
		size_t	buffer_size
	)

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

Parameters

buffer	Pointer to buffer to be used for storing advertising data.
buffer_size	Size of the buffer.

Note: Use Gap::getMaxAdvertisingDataLength() to find out how much can be accepted.

Member Function Documentation

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]	advDataType	The type of the field to add.
[in]	fieldData	Span of data to add.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_OPERATION_NOT_PERMITTED	if data type already present.
BLE_ERROR_INVALID_PARAM	if size of data is too big too fit in an individual data field.

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]	advDataType	The type of the field to add.
[in]	fieldData	Span of data to add.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAM	if size of data is too big too fit in an individual data field.

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]	advDataType	The type of the field to add.
[in]	fieldData	Span of data to add.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAM	if size of data is too big too fit in an individual data field.

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]	advDataType	The type of the field to add.
[in]	fieldData	Span of data to add.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_NOT_FOUND	if data type not present.
BLE_ERROR_INVALID_PARAM	if size of data is too big too fit in an individual data field.

void clear ( )

Clears the advertising data payload.

Postcondition: getPayloadLen() returns 0.

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

Get the subspan of the buffer containing valid data.

Returns: A Span containing the payload.

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]	data	Span used to return the requested data.
[in]	advDataType	Data type to return.

Returns: BLE_ERROR_NONE if data was found and BLE_ERROR_NOT_FOUND if not.

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] advDataType The type of the field to remove.

Returns: BLE_ERROR_NONE returned on success, BLE_ERROR_INVALID_PARAM if field doesn't exist

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]	advDataType	The type of the field to add.
[in]	fieldData	Span of data to add.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_NOT_FOUND	if data type not present.
BLE_ERROR_INVALID_PARAM	if size of data is too big too fit in an individual data field.

ble_error_t setAdvertisingInterval ( adv_interval_t interval )

Add advertising interval to the payload.

This field can only carry 2 bytes.

Parameters

interval Interval to advertise. Cannot be larger than 0xFFFF.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAM	if interval value outside of valid range.

ble_error_t setAppearance ( adv_data_appearance_t appearance )

Add device appearance in the advertising payload.

Parameters

[in] appearance The appearance to advertise.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if 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.

ble_error_t setConnectionIntervalPreference	(	conn_interval_t	min,
		conn_interval_t	max
	)

Add connection interval preferences to the payload.

Parameters

min	Minimum connection interval to advertise.
max	Maximum connection interval to advertise.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.

ble_error_t setFlags ( adv_data_flags_t flags = adv_data_flags_t::default_flags )

Add BLE flags in the advertising payload.

Parameters

[in] flags Bitfield describing the capability of the device. See allowed flags in Flags_t.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if 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.

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]	data	New data to be added.
[in]	complete	True if this is a complete list.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAM	if number of UUIDs of any one type is too high.

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] data New data to be added.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAM	if 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)

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]	name	Null terminated string containing the name.
[in]	complete	Complete local name if true, otherwise

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAM	if size of data is too big too fit in an individual data field.

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] data List of 128 or 16 bit service UUIDs.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAM	if number of UUIDs of any one type is too high.

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]	service	UUID of the service.
[in]	data	New data to be added.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if buffer is too small to contain the new data.
BLE_ERROR_INVALID_PARAM	if size of data is too big too fit in an individual data field.

ble_error_t setTxPowerAdvertised ( advertising_power_t txPower )

Add the advertising TX in the advertising payload.

Parameters

[in] txPower Transmission power level in dB.

Return values

BLE_ERROR_NONE	on success.
BLE_ERROR_BUFFER_OVERFLOW	if 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.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Important Information for this Arm website