| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros | Enumerations | Functions
Advertising and Scan Response Data Encoder
BLE libraries

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 | ADV_LENGTH_FIELD_SIZE 1UL
#define | ADV_AD_TYPE_FIELD_SIZE 1UL
#define | ADV_AD_DATA_OFFSET
#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

## 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
uint32_t | adv_data_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...
uint32_t | ble_advdata_set (const ble_advdata_t *p_advdata, const ble_advdata_t *p_srdata)
| Function for encoding and setting the advertising data and/or scan response data. 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_TYPE_APPEARANCE_DATA_SIZE 2UL

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

#define AD_TYPE_APPEARANCE_SIZE

Value:
(ADV_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:
(ADV_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:
(ADV_AD_DATA_OFFSET + \
AD_TYPE_CONN_INT_DATA_SIZE)

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

#define AD_TYPE_FLAGS_DATA_SIZE 1UL

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

#define AD_TYPE_FLAGS_SIZE

Value:
(ADV_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:
(ADV_AD_DATA_OFFSET + \
AD_TYPE_TX_POWER_LEVEL_DATA_SIZE)

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

#define ADV_AD_DATA_OFFSET

Value:
(ADV_LENGTH_FIELD_SIZE + \
ADV_AD_TYPE_FIELD_SIZE)

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

#define ADV_AD_TYPE_FIELD_SIZE 1UL

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

#define ADV_LENGTH_FIELD_SIZE 1UL

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

## 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

uint32_t adv_data_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 selections 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.

uint32_t ble_advdata_set | ( | const ble_advdata_t * | p_advdata,
|  | const ble_advdata_t * | p_srdata
| ) |  |

Function for encoding and setting the advertising data and/or scan response data.

This function encodes advertising data and/or scan response data based on the selections in the supplied structures, and passes the encoded data to the stack.

Parameters

  [in] | p_advdata | Structure for specifying the content of the advertising data. Set to NULL if advertising data is not to be set.
  [in] | p_srdata | Structure for specifying the content of the scan response data. Set to NULL if scan response data is not to be set.

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 advertising packet. The maximum size of the advertisement packet is BLE_GAP_ADV_MAX_SIZE.

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.