Infrastructure to fill in Advertising and Scan Response Data. More...

#include </mnt/devel/pabigot-cxx/include/pabigot/ble/gap.hpp>

Inheritance diagram for pabigot::ble::gap::adv_data:

Data Structures
class	store_helper
	RAII helper to avoid overruns and to back-fill lengths. More...

Public Member Functions
	adv_data (uint8_t begin, uint8_t end)
	Reference an octet sequence into which advertising data will be written. More...

template<size_t count>
	adv_data (std::array< uint8_t, count > &src)
	Construct from a `std::array` reference.

const uint8_t *	data () const noexcept
	Get a typed pointer to the start of the buffer. More...

store_helper	start_store (uint8_t tag, size_type count)
	Reserve space for a data type record. More...

void	set_Flags (unsigned int flags)
	Helper to set the Flags data value. More...

void	set_ShortenedLocalName (const char *name, ptrdiff_t count=-1)
	Helper to set the shortened local name. More...

void	set_CompleteLocalName (const char *name, ptrdiff_t count=-1)
	Helper to set the complete local name. More...

void	set_TXPowerLevel (int8_t txPower)
	Helper to set the TX Power Level data value. More...

template<typename uuid_type >
void	set_CompleteListServiceUUID (const uuid_type &uuid)
	Helper for complete listing of a single UUID service. More...

template<typename uuid_type >
void	set_CompleteListServiceUUID (const uuid_type begin, const uuid_type end)
	Helper for complete listing of multiple UUID services. More...

template<typename uuid_type >
void	set_IncompleteListServiceUUID (const uuid_type &uuid)
	Helper for incomplete listing a single UUID service. More...

template<typename uuid_type >
void	set_IncompleteListServiceUUID (const uuid_type begin, const uuid_type end)
	Helper for incomplete listing of multiple UUID services. More...

template<typename uuid_type >
void	set_ListServiceSolicitationUUID (const uuid_type &uuid)
	Helper for listing a single service solicitation UUID. More...

template<typename uuid_type >
void	set_ListServiceSolicitationUUID (const uuid_type begin, const uuid_type end)
	Helper for listing multiple service solicitation UUIDs. More...

template<typename uuid_type >
uint8_t *	set_ServiceData (const uuid_type &uuid, const uint8_t begin, const uint8_t end)
	Helper to set service data. More...

template<typename uuid_type , std::size_t len>
uint8_t *	set_ServiceData (const uuid_type &uuid, const std::array< uint8_t, len > &data)
	Helper to set service data. More...

template<typename uuid_type >
uint8_t *	set_ServiceData (const uuid_type &uuid, const void *buf, size_t count)
	Helper to set service data. More...

void	set_AdvertisingInterval (uint16_t advInterval)
	Helper to set the Advertising Interval data value. More...

void	set_SlaveConnectionIntervalRange (uint16_t connIntervalMin, uint16_t connIntervalMax)
	Helper to set the preferred connectional interval range. More...

void *	set_ManufacturerSpecificData (uint16_t companyID, size_t span)
	Helper to set Manufacturer Specific Data. More...

Public Member Functions inherited from pabigot::byteorder::octets_helper
	octets_helper (uint8_t begin, uint8_t end)
	Reference an octet range into which data will be written. More...

	octets_helper (uint8_t *begin, size_type count)
	Reference an octet sequence into which data will be written. More...

void	reset () noexcept
	Remove all content from the buffer. More...

const bool	valid () const noexcept
	Indicates whether advance() caused an error. More...

void	invalidate () noexcept
	Explicitly mark the buffer invalid. More...

const void *	begin () const noexcept
	Get a pointer to the start of buffer. More...

const void *	end () const noexcept
	Get a pointer to the end of the filled part of the buffer. More...

const size_type	size () const noexcept
	Number of octets stored in the buffer. More...

const size_type	available () const noexcept
	Number of unused octets available in the buffer. More...

const size_type	max_size () const noexcept
	Maximum number of octets supported by the buffer.

void *	advance (size_type s) noexcept
	Allocate a region and return a pointer to it or a nullptr if the advance went too far. More...

bool	can_advance (size_type s) const noexcept
	Indicate whether advance() would succeed for a given span. More...

bool	append (const void *sp, size_type span) noexcept
	Append a value to the buffer. More...

template<typename T >
bool	append (const T &value) noexcept
	Append a value to the buffer. More...

template<typename T >
bool	append_be (const T &value) noexcept
	As with append() but stores the value converted to big-endian byte order.

template<typename T >
bool	append_le (const T &value) noexcept
	As with append() but stores the value converted to little-endian byte order.

Protected Types
using	super = byteorder::octets_helper

Protected Member Functions
template<typename uuid_type >
void	store_uuids (uint8_t dt, const uuid_type begin, const uuid_type end)

Additional Inherited Members
Public Types inherited from pabigot::byteorder::octets_helper
using	size_type = std::size_t
	Type used for span values.

Protected Attributes inherited from pabigot::byteorder::octets_helper
uint8_t *const	begin_

uint8_t *const	end_

uint8_t *	bp_ = nullptr

Detailed Description

Infrastructure to fill in Advertising and Scan Response Data.

Note: Not all AD and EIR structures are implemented.

For assigned numbers and references to data representation see: https://www.bluetooth.com/specifications/assigned-numbers/generic-access-profile

Constructor & Destructor Documentation

◆ adv_data()

pabigot::ble::gap::adv_data::adv_data	(	uint8_t *	begin,
		uint8_t *	end
	)

inline

Reference an octet sequence into which advertising data will be written.

Parameters

begin	pointer to the first octet in the sequence.
end	pointer just past the last octet available for the sequence.

Member Function Documentation

◆ data()

const uint8_t* pabigot::ble::gap::adv_data::data ( ) const

inlinenoexcept

Get a typed pointer to the start of the buffer.

APIs that consume the prepared ASR packet generally want to receive it as a pointer to an octet.

◆ set_AdvertisingInterval()

void pabigot::ble::gap::adv_data::set_AdvertisingInterval ( uint16_t advInterval )

Helper to set the Advertising Interval data value.

Parameters

advInterval interval between advertisements, measured in 625 us ticks. Valid range is 32 (20 ms) to 65535 (about 41 s).

◆ set_CompleteListServiceUUID() [1/2]

template<typename uuid_type >

void pabigot::ble::gap::adv_data::set_CompleteListServiceUUID ( const uuid_type & uuid )

inline

Helper for complete listing of a single UUID service.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

uuid	the UUID to be stored in the structure.

◆ set_CompleteListServiceUUID() [2/2]

template<typename uuid_type >

void pabigot::ble::gap::adv_data::set_CompleteListServiceUUID	(	const uuid_type *	begin,
		const uuid_type *	end
	)

Helper for complete listing of multiple UUID services.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

begin	start of the range providing the service UUIDs.
end	end of the range providing the service UUIDs.

◆ set_CompleteLocalName()

void pabigot::ble::gap::adv_data::set_CompleteLocalName	(	const char *	name,
		ptrdiff_t	count = `-1`
	)

Helper to set the complete local name.

Parameters

name	pointer to the name.
name	pointer to the name, as a UTF8 character sequence.
count	number of octets in the name. If a negative value is provided then `strlen(name)` will be used.

◆ set_Flags()

void pabigot::ble::gap::adv_data::set_Flags ( unsigned int flags )

Helper to set the Flags data value.

Parameters

flags providing LE and BR/EDR modes and features

◆ set_IncompleteListServiceUUID() [1/2]

template<typename uuid_type >

void pabigot::ble::gap::adv_data::set_IncompleteListServiceUUID ( const uuid_type & uuid )

inline

Helper for incomplete listing a single UUID service.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

uuid	the UUID to be stored in the structure.

◆ set_IncompleteListServiceUUID() [2/2]

template<typename uuid_type >

void pabigot::ble::gap::adv_data::set_IncompleteListServiceUUID	(	const uuid_type *	begin,
		const uuid_type *	end
	)

Helper for incomplete listing of multiple UUID services.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

begin	start of the range providing the service UUIDs.
end	end of the range providing the service UUIDs.

◆ set_ListServiceSolicitationUUID() [1/2]

template<typename uuid_type >

void pabigot::ble::gap::adv_data::set_ListServiceSolicitationUUID ( const uuid_type & uuid )

inline

Helper for listing a single service solicitation UUID.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

uuid	the UUID to be stored in the structure.

◆ set_ListServiceSolicitationUUID() [2/2]

template<typename uuid_type >

void pabigot::ble::gap::adv_data::set_ListServiceSolicitationUUID	(	const uuid_type *	begin,
		const uuid_type *	end
	)

Helper for listing multiple service solicitation UUIDs.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

begin	start of the range providing the service UUIDs.
end	end of the range providing the service UUIDs.

◆ set_ManufacturerSpecificData()

void* pabigot::ble::gap::adv_data::set_ManufacturerSpecificData	(	uint16_t	companyID,
		size_t	span
	)

Helper to set Manufacturer Specific Data.

Note: The returned pointer is aligned to the requirements of the advertising PDU. If octet-level access is not desired the object accessed though the pointer should be packed.

Parameters

companyID	the assigned company identifier. Pass `-1` for the reserved test identifier.
span	number of octets to be stored in the payload.

Returns: pointer into the ASR data region at which the data starts. This should be used to set the advertising payload initially and when the data changes, as long as the data length does not change.

◆ set_ServiceData() [1/3]

template<typename uuid_type , std::size_t len>

uint8_t* pabigot::ble::gap::adv_data::set_ServiceData	(	const uuid_type &	uuid,
		const std::array< uint8_t, len > &	data
	)

inline

Helper to set service data.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

data	the data to be sent

Returns: pointer into the ASR data region at which data was copied. This can be used to update the advertising payload when the data changes.

◆ set_ServiceData() [2/3]

template<typename uuid_type >

uint8_t* pabigot::ble::gap::adv_data::set_ServiceData	(	const uuid_type &	uuid,
		const uint8_t *	begin,
		const uint8_t *	end
	)

Helper to set service data.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

begin	start of the service data to be stored in the payload.
end	end of the service data to be stored in the payload

Returns: pointer into the ASR data region at which data was copied. This can be used to update the advertising payload when the data changes, as long as the data length does not change.

◆ set_ServiceData() [3/3]

template<typename uuid_type >

uint8_t* pabigot::ble::gap::adv_data::set_ServiceData	(	const uuid_type &	uuid,
		const void *	buf,
		size_t	count
	)

inline

Helper to set service data.

Template Parameters

uuid_type one of uuid16_type, uuid32_type, or uuid128_type.

Parameters

buf	pointer to the data to be sent
count	the number of bytes to be sent

Returns: pointer into the ASR data region at which data was copied. This can be used to update the advertising payload when the data changes.

◆ set_ShortenedLocalName()

void pabigot::ble::gap::adv_data::set_ShortenedLocalName	(	const char *	name,
		ptrdiff_t	count = `-1`
	)

Helper to set the shortened local name.

Parameters

name	pointer to the name, as a UTF8 character sequence.
count	number of octets in the name. If a negative value is provided then `strlen(name)` will be used.

◆ set_SlaveConnectionIntervalRange()

void pabigot::ble::gap::adv_data::set_SlaveConnectionIntervalRange	(	uint16_t	connIntervalMin,
		uint16_t	connIntervalMax
	)

Helper to set the preferred connectional interval range.

Parameters

connIntervalMin	minimum value for connection interval, measured in 1250 us ticks. Allowed (but unverified) range is 0x0006 through 0x0C80 inclusive. Pass -1 for no specific minimum.
connIntervalMax	maximum value for connection interval, measured in 1250 us ticks. Allowed (but unverified) range is 0x0006 through 0x0C80 inclusive, and a non-negative value must not be less than `connIntervalMin`. Pass -1 for no specific maximum. interval between advertisements, measured in 625 us ticks.

◆ set_TXPowerLevel()

void pabigot::ble::gap::adv_data::set_TXPowerLevel ( int8_t txPower )

Helper to set the TX Power Level data value.

Parameters

txPower transmission power level in dBm.

◆ start_store()

store_helper pabigot::ble::gap::adv_data::start_store	(	uint8_t	tag,
		size_type	count
	)

inline

Reserve space for a data type record.

This function checks whether there is enough space in the buffer for a data type with the given tag and length. If so, it stores the length and tag; if no, the buffer is invalidated.

Use it this way if count is a fixed span:

if (start_store(DT_WHATEVER, count)) {
   append(count_octets);
}

Use it this way if count is a maximum span and the actual space required may be less:

if (auto raii = start_store(DT_WHATEVER, count)) {
   append(whatever_up_to_count);
}

Parameters

tag	the data type tag identifying the content to be stored.
count	the number of octets of data required for the record, excluding the data type tag.

Returns: an object that is true when converted to bool iff the reservation succeeded. When the object is destructed the length of the data type record is updated to reflect the actual amount of space used if content was added after this function was called.

The documentation for this class was generated from the following file:

/mnt/devel/pabigot-cxx/include/pabigot/ble/gap.hpp

Data Structures

Public Member Functions

Protected Types

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ adv_data()

Member Function Documentation

◆ data()

◆ set_AdvertisingInterval()

◆ set_CompleteListServiceUUID() [1/2]

◆ set_CompleteListServiceUUID() [2/2]

◆ set_CompleteLocalName()

◆ set_Flags()

◆ set_IncompleteListServiceUUID() [1/2]

◆ set_IncompleteListServiceUUID() [2/2]

◆ set_ListServiceSolicitationUUID() [1/2]

◆ set_ListServiceSolicitationUUID() [2/2]

◆ set_ManufacturerSpecificData()

◆ set_ServiceData() [1/3]

◆ set_ServiceData() [2/3]

◆ set_ServiceData() [3/3]

◆ set_ShortenedLocalName()

◆ set_SlaveConnectionIntervalRange()

◆ set_TXPowerLevel()

◆ start_store()