Advertising and Scan Response Data Encoder

Functions for encoding data in the Advertising and Scan Response Data format, and for passing the data to the stack. More...

Data Structures
struct	ble_advdata_tk_value_t
	Security Manager TK value. More...
struct	ble_advdata_uuid_list_t
	UUID list type. More...
struct	ble_advdata_conn_int_t
	Connection interval range structure. More...
struct	ble_advdata_manuf_data_t
	Manufacturer specific data structure. More...
struct	ble_advdata_service_data_t
	Service data structure. More...
struct	ble_advdata_t
	Advertising data structure. This structure contains all options and data needed for encoding and setting the advertising data. More...

Macros
#define	AD_LENGTH_FIELD_SIZE   1UL
#define	AD_TYPE_FIELD_SIZE   1UL
#define	AD_DATA_OFFSET   (AD_LENGTH_FIELD_SIZE + AD_TYPE_FIELD_SIZE)
#define	AD_TYPE_BLE_DEVICE_ADDR_TYPE_SIZE   1UL
#define	AD_TYPE_BLE_DEVICE_ADDR_DATA_SIZE
#define	AD_TYPE_BLE_DEVICE_ADDR_SIZE
#define	AD_TYPE_APPEARANCE_DATA_SIZE   2UL
#define	AD_TYPE_APPEARANCE_SIZE
#define	AD_TYPE_FLAGS_DATA_SIZE   1UL
#define	AD_TYPE_FLAGS_SIZE
#define	AD_TYPE_TX_POWER_LEVEL_DATA_SIZE   1UL
#define	AD_TYPE_TX_POWER_LEVEL_SIZE
#define	AD_TYPE_CONN_INT_DATA_SIZE   4UL
#define	AD_TYPE_CONN_INT_SIZE
#define	AD_TYPE_MANUF_SPEC_DATA_ID_SIZE   2UL
#define	AD_TYPE_SERV_DATA_16BIT_UUID_SIZE   2UL
#define	BLE_ADV_DATA_MATCH_FULL_NAME   0xff

Enumerations
enum	ble_advdata_le_role_t {   BLE_ADVDATA_ROLE_NOT_PRESENT = 0,   BLE_ADVDATA_ROLE_ONLY_PERIPH,   BLE_ADVDATA_ROLE_ONLY_CENTRAL,   BLE_ADVDATA_ROLE_BOTH_PERIPH_PREFERRED,   BLE_ADVDATA_ROLE_BOTH_CENTRAL_PREFERRED }
	Advertising data LE Role types. This enumeration contains the options available for the LE role inside the advertising data. More...
enum	ble_advdata_name_type_t {   BLE_ADVDATA_NO_NAME,   BLE_ADVDATA_SHORT_NAME,   BLE_ADVDATA_FULL_NAME }
	Advertising data name type. This enumeration contains the options available for the device name inside the advertising data. More...

Functions
ret_code_t	ble_advdata_encode (ble_advdata_t const *const p_advdata, uint8_t *const p_encoded_data, uint16_t *const p_len)
	Function for encoding data in the Advertising and Scan Response data format (AD structures). More...
uint16_t	ble_advdata_search (uint8_t const *p_encoded_data, uint16_t data_len, uint16_t *p_offset, uint8_t ad_type)
	Function for searching encoded Advertising or Scan Response data for specific data types. More...
uint8_t *	ble_advdata_parse (uint8_t *p_encoded_data, uint16_t data_len, uint8_t ad_type)
	Function for getting specific data from encoded Advertising or Scan Response data. More...
bool	ble_advdata_name_find (uint8_t const *p_encoded_data, uint16_t data_len, char const *p_target_name)
	Function for searching through encoded Advertising data for a complete local name. More...
bool	ble_advdata_short_name_find (uint8_t const *p_encoded_data, uint16_t data_len, char const *p_target_name, uint8_t const short_name_min_len)
	Function for searching through encoded Advertising data for a device shortened name. More...
bool	ble_advdata_uuid_find (uint8_t const *p_encoded_data, uint16_t data_len, ble_uuid_t const *p_target_uuid)
	Function for searching through encoded Advertising data for a UUID (16-bit or 128-bit). More...
bool	ble_advdata_appearance_find (uint8_t const *p_encoded_data, uint16_t data_len, uint16_t const *p_target_appearance)
	Function for searching through encoded Advertising data for an appearance. More...

Detailed Description

Functions for encoding data in the Advertising and Scan Response Data format, and for passing the data to the stack.

Macro Definition Documentation

#define AD_DATA_OFFSET   (AD_LENGTH_FIELD_SIZE + AD_TYPE_FIELD_SIZE)

Offset for the AD data field of the Advertising Data and Scan Response format.

#define AD_LENGTH_FIELD_SIZE   1UL

Advertising Data and Scan Response format contains 1 octet for the length.

#define AD_TYPE_APPEARANCE_DATA_SIZE   2UL

Data size (in octets) of the Appearance AD type.

#define AD_TYPE_APPEARANCE_SIZE

Value:

(AD_DATA_OFFSET + \
 AD_TYPE_APPEARANCE_DATA_SIZE)

Size (in octets) of the Appearance AD type.

#define AD_TYPE_BLE_DEVICE_ADDR_DATA_SIZE

Value:

(BLE_GAP_ADDR_LEN + \
 AD_TYPE_BLE_DEVICE_ADDR_TYPE_SIZE)

Data size (in octets) of the LE Bluetooth Device Address AD type.

#define AD_TYPE_BLE_DEVICE_ADDR_SIZE

Value:

(AD_DATA_OFFSET + \
 AD_TYPE_BLE_DEVICE_ADDR_DATA_SIZE)

Size (in octets) of the LE Bluetooth Device Address AD type.

#define AD_TYPE_BLE_DEVICE_ADDR_TYPE_SIZE   1UL

Data size (in octets) of the Address type of the LE Bluetooth Device Address AD type.

#define AD_TYPE_CONN_INT_DATA_SIZE   4UL

Data size (in octets) of the Slave Connection Interval Range AD type.

#define AD_TYPE_CONN_INT_SIZE

Value:

(AD_DATA_OFFSET + \
 AD_TYPE_CONN_INT_DATA_SIZE)

Data size (in octets) of the Slave Connection Interval Range AD type.

#define AD_TYPE_FIELD_SIZE   1UL

Advertising Data and Scan Response format contains 1 octet for the AD type.

#define AD_TYPE_FLAGS_DATA_SIZE   1UL

Data size (in octets) of the Flags AD type.

#define AD_TYPE_FLAGS_SIZE

Value:

(AD_DATA_OFFSET + \
 AD_TYPE_FLAGS_DATA_SIZE)

Size (in octets) of the Flags AD type.

#define AD_TYPE_MANUF_SPEC_DATA_ID_SIZE   2UL

Size (in octets) of the Company Identifier Code, which is a part of the Manufacturer Specific Data AD type.

#define AD_TYPE_SERV_DATA_16BIT_UUID_SIZE   2UL

Size (in octets) of the 16-bit UUID, which is a part of the Service Data AD type.

#define AD_TYPE_TX_POWER_LEVEL_DATA_SIZE   1UL

Data size (in octets) of the TX Power Level AD type.

#define AD_TYPE_TX_POWER_LEVEL_SIZE

Value:

(AD_DATA_OFFSET + \
 AD_TYPE_TX_POWER_LEVEL_DATA_SIZE)

Size (in octets) of the TX Power Level AD type.

Enumeration Type Documentation

enum ble_advdata_le_role_t

Advertising data LE Role types. This enumeration contains the options available for the LE role inside the advertising data.

Enumerator
BLE_ADVDATA_ROLE_NOT_PRESENT	LE Role AD structure not present.
BLE_ADVDATA_ROLE_ONLY_PERIPH	Only Peripheral Role supported.
BLE_ADVDATA_ROLE_ONLY_CENTRAL	Only Central Role supported.
BLE_ADVDATA_ROLE_BOTH_PERIPH_PREFERRED	Peripheral and Central Role supported. Peripheral Role preferred for connection establishment.
BLE_ADVDATA_ROLE_BOTH_CENTRAL_PREFERRED	Peripheral and Central Role supported. Central Role preferred for connection establishment

enum ble_advdata_name_type_t

Advertising data name type. This enumeration contains the options available for the device name inside the advertising data.

Enumerator
BLE_ADVDATA_NO_NAME	Include no device name in advertising data.
BLE_ADVDATA_SHORT_NAME	Include short device name in advertising data.
BLE_ADVDATA_FULL_NAME	Include full device name in advertising data.

Function Documentation

bool ble_advdata_appearance_find	(	uint8_t const *	p_encoded_data,
		uint16_t	data_len,
		uint16_t const *	p_target_appearance
	)

Function for searching through encoded Advertising data for an appearance.

Parameters

[in]	p_encoded_data	Data buffer containing the encoded Advertising data.
[in]	data_len	Length of the data buffer p_encoded_data.
[in]	p_target_appearance	Appearance to search for.

Return values

true	If p_target_appearance was found among p_encoded_data.
false	If p_target_appearance was not found among p_encoded_data, or if p_encoded_data or p_target_appearance was NULL.

ret_code_t ble_advdata_encode	(	ble_advdata_t const *const	p_advdata,
		uint8_t *const	p_encoded_data,
		uint16_t *const	p_len
	)

Function for encoding data in the Advertising and Scan Response data format (AD structures).

This function encodes data into the Advertising and Scan Response data format (AD structures) based on the fields in the supplied structures. This function can be used to create a payload of Advertising packet or Scan Response packet, or a payload of NFC message intended for initiating the Out-of-Band pairing.

Parameters

[in]	p_advdata	Pointer to the structure for specifying the content of encoded data.
[out]	p_encoded_data	Pointer to the buffer where encoded data will be returned.
[in,out]	p_len	in: Size of p_encoded_data buffer. out: Length of encoded data.

Return values

NRF_SUCCESS	If the operation was successful.
NRF_ERROR_INVALID_PARAM	If the operation failed because a wrong parameter was provided in p_advdata.
NRF_ERROR_DATA_SIZE	If the operation failed because not all the requested data could fit into the provided buffer or some encoded AD structure is too long and its length cannot be encoded with one octet.

Warning

This API may override the application's request to use the long name and use a short name instead. This truncation will occur in case the long name does not fit the provided buffer size. The application can specify a preferred short name length if truncation is required. For example, if the complete device name is ABCD_HRMonitor, the application can specify the short name length to be 8, so that the short device name appears as ABCD_HRM instead of ABCD_HRMo or ABCD_HRMoni if the available size for the short name is 9 or 12 respectively, to have a more appropriate short name. However, it should be noted that this is just a preference that the application can specify, and if the preference is too large to fit in the provided buffer, the name can be truncated further.

bool ble_advdata_name_find	(	uint8_t const *	p_encoded_data,
		uint16_t	data_len,
		char const *	p_target_name
	)

Function for searching through encoded Advertising data for a complete local name.

Parameters

[in]	p_encoded_data	Data buffer containing the encoded Advertising data.
[in]	data_len	Length of the data buffer p_encoded_data.
[in]	p_target_name	Name to search for.

Return values

true	If p_target_name was found among p_encoded_data, as a complete local name.
false	If p_target_name was not found among p_encoded_data, or if p_encoded_data or p_target_name was NULL.

uint8_t* ble_advdata_parse	(	uint8_t *	p_encoded_data,
		uint16_t	data_len,
		uint8_t	ad_type
	)

Function for getting specific data from encoded Advertising or Scan Response data.

This function searches through encoded data e.g. the data produced by ble_advdata_encode, or the data found in Advertising reports (BLE_GAP_EVT_ADV_REPORT), and returns a pointer directly to the data within the data buffer.

Example code: ad_type_data = ble_advdata_parse(&data, len, AD_TYPE);

Parameters

[in]	p_encoded_data	Data buffer containing the encoded Advertising data.
[in]	data_len	Length of the data buffer p_encoded_data.
[in]	ad_type	Type of data to search for.

Returns

Pointer to the found data, or NULL if no data was found with the type ad_type, or if p_encoded_data or p_data_len were NULL.

uint16_t ble_advdata_search	(	uint8_t const *	p_encoded_data,
		uint16_t	data_len,
		uint16_t *	p_offset,
		uint8_t	ad_type
	)

Function for searching encoded Advertising or Scan Response data for specific data types.

This function searches through encoded data e.g. the data produced by ble_advdata_encode, or the data found in Advertising reports (BLE_GAP_EVT_ADV_REPORT), and gives the offset of the data within the data buffer. The data with type ad_type can be found at p_encoded_data[*p_offset] after calling the function. This function can iterate through multiple instances of data of one type by calling it again with the offset provided by the previous call.

Example code for finding multiple instances of one type of data: offset = 0; ble_advdata_search(&data, len, &offset, AD_TYPE); first_instance_of_data = data[offset]; ble_advdata_search(&data, len, &offset, AD_TYPE); second_instance_of_data = data[offset];

Parameters

[in]	p_encoded_data	The data buffer containing the encoded Advertising data.
[in]	data_len	The length of the data buffer p_encoded_data.
[in,out]	p_offset	in: The offset to start searching from. out: The offset the data type can be found at. This value is not changed if the call returns 0.
[in]	ad_type	The type of data to search for.

Returns

The length of the found data, or 0 if no data was found with the the type ad_type, or if p_encoded_data or p_offset were NULL.

bool ble_advdata_short_name_find	(	uint8_t const *	p_encoded_data,
		uint16_t	data_len,
		char const *	p_target_name,
		uint8_t const	short_name_min_len
	)

Function for searching through encoded Advertising data for a device shortened name.

Parameters

[in]	p_encoded_data	Data buffer containing the encoded Advertising data.
[in]	data_len	Length of the data buffer p_encoded_data.
[in]	p_target_name	Name to search for.
[in]	short_name_min_len	Minimum length of the shortened name. For example, if the advertising data has a shortened name 'No' and this parameter is set to 4 with a target_name set to Nordic_XXX it will return false, but if the shortened name in the advertising data is 'Nord', it will return true.

Note

: If the shortened name in the Advertising data has the same length as the target name, this function will return false, since this means that the complete name is actually longer, thus different than the target name.

Return values

true	If p_target_name was found among p_encoded_data, as short local name.
false	If p_target_name was not found among p_encoded_data, or if p_encoded_data or p_target_name was NULL.

bool ble_advdata_uuid_find	(	uint8_t const *	p_encoded_data,
		uint16_t	data_len,
		ble_uuid_t const *	p_target_uuid
	)

Function for searching through encoded Advertising data for a UUID (16-bit or 128-bit).

Parameters

[in]	p_encoded_data	Data buffer containing the encoded Advertising data.
[in]	data_len	Length of the data buffer p_encoded_data.
[in]	p_target_uuid	UUID to search for.

Return values

true	If p_target_uuid was found among p_encoded_data.
false	If p_target_uuid was not found among p_encoded_data, or if p_encoded_data or p_target_uuid was NULL.