BLE Advertising Data (AD) Processing

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. More...
 

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. More...
 
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. More...
 
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. More...
 
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. More...
 
static int bluetil_ad_add_flags (bluetil_ad_t *ad, uint8_t flags)
 Convenience function to add the "flags" field. More...
 
static int bluetil_ad_add_name (bluetil_ad_t *ad, const char *name)
 Convenience function to add the "full name" field. More...
 
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. More...
 

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.

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]adadvertising data descriptor
[in]typefield type to add
[in]datapayload for the field
[in]data_lenlength 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]adadvertising data descriptor
[in]flagsflags 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 142 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]adadvertising data descriptor
[in]namename 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 159 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]adadvertising data descriptor
[in]typefield type to look for
[out]dataposition 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_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]adadvertising data descriptor
[in]typefield type to look for
[out]strresulting string is written to this buffer
[in]str_lenmaximum 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]adadvertising data descriptor
[in]bufbuffer to point to
[in]poscurrent fill position of buf
[in]sizesize 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]adadvertising data descriptor
[out]bufbuffer to write advertising data into
[in]buf_lensize of buf in bytes
[in]flagsflags 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 180 of file ad.h.