Generic BLE advertising and scan request data processing. More...

Detailed Description

Generic BLE advertising and scan request data processing.

This module provides functionality for user friendly reading and writing of BLE advertising and scan request buffers.

This module is independent from any BLE stack.

Files
file	ad.h
	Interface for the generic BLE advertising data processing module.

Data Structures
struct	bluetil_ad_data_t
	Struct used for returning the contents of a selected field. More...

struct	bluetil_ad_t
	Descriptor for a buffer containing advertising data. More...

Macros
#define	BLUETIL_AD_INIT(b, p, s) { .buf = b, .pos = p, .size = s }
	Static initializer for the advertising data structure.

#define	BLUETIL_AD_FLAGS_DEFAULT
	Default flags to set when advertising BLE devices.

Enumerations
enum	{ BLUETIL_AD_OK = 0 , BLUETIL_AD_NOTFOUND = -1 , BLUETIL_AD_NOMEM = -2 }
	Return values used by the bluetil_ad module. More...

Functions
void	bluetil_ad_init (bluetil_ad_t ad, void buf, size_t pos, size_t size)
	Initialize the given advertising data descriptor.

int	bluetil_ad_find (const bluetil_ad_t ad, uint8_t type, bluetil_ad_data_t data)
	Find a specific field in the given advertising data.

int	bluetil_ad_find_and_cmp (const bluetil_ad_t ad, uint8_t type, const void val, size_t val_len)
	Find a specific field and compare its value against the given data.

int	bluetil_ad_find_str (const bluetil_ad_t ad, uint8_t type, char str, size_t str_len)
	Find the given field and copy its payload into a string.

int	bluetil_ad_add (bluetil_ad_t ad, uint8_t type, const void data, size_t data_len)
	Add a new field to the given advertising data.

static int	bluetil_ad_add_flags (bluetil_ad_t *ad, uint8_t flags)
	Convenience function to add the "flags" field.

static int	bluetil_ad_add_name (bluetil_ad_t ad, const char name)
	Convenience function to add the "full name" field.

static int	bluetil_ad_init_with_flags (bluetil_ad_t ad, void buf, size_t buf_len, uint8_t flags)
	Convenience function for initializing the advertising data descriptor and directly adding the flags field.

Macro Definition Documentation

◆ BLUETIL_AD_FLAGS_DEFAULT

#define BLUETIL_AD_FLAGS_DEFAULT

Value:

(BLE_GAP_DISCOVERABLE | \

BLE_GAP_FLAG_BREDR_NOTSUP)

Default flags to set when advertising BLE devices.

Definition at line 48 of file ad.h.

◆ BLUETIL_AD_INIT

#define BLUETIL_AD_INIT	(	b,
		p,
		s
	)	{ .buf = b, .pos = p, .size = s }

Static initializer for the advertising data structure.

Definition at line 43 of file ad.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Return values used by the bluetil_ad module.

Enumerator
BLUETIL_AD_OK	everything went as expected
BLUETIL_AD_NOTFOUND	entry not found
BLUETIL_AD_NOMEM	insufficient memory to write field

Definition at line 54 of file ad.h.

Function Documentation

◆ bluetil_ad_add()

int bluetil_ad_add	(	bluetil_ad_t *	ad,
		uint8_t	type,
		const void *	data,
		size_t	data_len
	)

Add a new field to the given advertising data.

Parameters

[out]	ad	advertising data descriptor
[in]	type	field type to add
[in]	data	payload for the field
[in]	data_len	length of the payload in bytes

Returns: BLUETIL_AD_OK if the new field was added; BLUETIL_AD_NOMEM if there is not enough space to write add field

◆ bluetil_ad_add_flags()

static int bluetil_ad_add_flags	(	bluetil_ad_t *	ad,
		uint8_t	flags
	)

inlinestatic

Convenience function to add the "flags" field.

Parameters

[out]	ad	advertising data descriptor
[in]	flags	flags to set

Returns: BLUETIL_AD_OK if the flags field was added; BLUETIL_AD_NOMEM if there is not enough space to write add field

Definition at line 156 of file ad.h.

◆ bluetil_ad_add_name()

static int bluetil_ad_add_name	(	bluetil_ad_t *	ad,
		const char *	name
	)

inlinestatic

Convenience function to add the "full name" field.

While the given name must be \0 terminated, the termination character is not written to the advertising data.

Parameters

[out]	ad	advertising data descriptor
[in]	name	name to set

Returns: BLUETIL_AD_OK if the name field was added; BLUETIL_AD_NOMEM if there is not enough space to add the name field

Definition at line 173 of file ad.h.

◆ bluetil_ad_find()

int bluetil_ad_find	(	const bluetil_ad_t *	ad,
		uint8_t	type,
		bluetil_ad_data_t *	data
	)

Find a specific field in the given advertising data.

Parameters

[in]	ad	advertising data descriptor
[in]	type	field type to look for
[out]	data	position and length of the field's payload

Returns: BLUETIL_AD_OK if field was found; BLUETIL_AD_NOTFOUND if field was not found

◆ bluetil_ad_find_and_cmp()

int bluetil_ad_find_and_cmp	(	const bluetil_ad_t *	ad,
		uint8_t	type,
		const void *	val,
		size_t	val_len
	)

Find a specific field and compare its value against the given data.

Parameters

[in]	ad	advertising data descriptor
[in]	type	field to search for
[in]	val	data to compare against
[in]	val_len	size of `val` in byte

Returns: true if the field was found and its data is equal to the given data; false if the field was not found or the data is not equal

◆ bluetil_ad_find_str()

int bluetil_ad_find_str	(	const bluetil_ad_t *	ad,
		uint8_t	type,
		char *	str,
		size_t	str_len
	)

Find the given field and copy its payload into a string.

The resulting string is \0 terminated. If the resulting string is too large to fit into the given buffer, it will be truncated to the maximum possible size (but still including the \0 at the end).

Parameters

[in]	ad	advertising data descriptor
[in]	type	field type to look for
[out]	str	resulting string is written to this buffer
[in]	str_len	maximum number of bytes to write to `str`, including the `\0` character

Returns: BLUETIL_AD_OK if the field was found and copied; BLUETIL_AD_NOTFOUND if the given field was not found

◆ bluetil_ad_init()

void bluetil_ad_init	(	bluetil_ad_t *	ad,
		void *	buf,
		size_t	pos,
		size_t	size
	)

Initialize the given advertising data descriptor.

Parameters

[out]	ad	advertising data descriptor
[in]	buf	buffer to point to
[in]	pos	current fill position of `buf`
[in]	size	size of `buf`

◆ bluetil_ad_init_with_flags()

static int bluetil_ad_init_with_flags	(	bluetil_ad_t *	ad,
		void *	buf,
		size_t	buf_len,
		uint8_t	flags
	)

inlinestatic

Convenience function for initializing the advertising data descriptor and directly adding the flags field.

Most users will want to set the (mandatory) flags field right after initializing the advertising context, so this function provides a small shortcut.

Parameters

[out]	ad	advertising data descriptor
[out]	buf	buffer to write advertising data into
[in]	buf_len	size of `buf` in bytes
[in]	flags	flags to set, typically BLUETIL_AD_FLAGS_DEFAULT

Returns: BLUETIL_AD_OK on successful initialization with flags field; BLUETIL_AD_NOMEM if given buffer is too small

Definition at line 194 of file ad.h.

Detailed Description

Files

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

◆ BLUETIL_AD_FLAGS_DEFAULT

◆ BLUETIL_AD_INIT

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ bluetil_ad_add()

◆ bluetil_ad_add_flags()

◆ bluetil_ad_add_name()

◆ bluetil_ad_find()

◆ bluetil_ad_find_and_cmp()

◆ bluetil_ad_find_str()

◆ bluetil_ad_init()

◆ bluetil_ad_init_with_flags()