From cb41532dc8c4919c9e24deae7ef3974fe6396985 Mon Sep 17 00:00:00 2001 From: Wojciech Pietraszewski Date: Fri, 11 Aug 2023 16:21:17 +0200 Subject: [PATCH] host/hs_adv: add and update doxygen comments for the header file Adds missing macros, functions and structures documentation. --- nimble/host/include/host/ble_hs_adv.h | 225 ++++++++++++++++++++++++-- 1 file changed, 210 insertions(+), 15 deletions(-) diff --git a/nimble/host/include/host/ble_hs_adv.h b/nimble/host/include/host/ble_hs_adv.h index e3b6ea7098..fabeca64dc 100644 --- a/nimble/host/include/host/ble_hs_adv.h +++ b/nimble/host/include/host/ble_hs_adv.h @@ -20,6 +20,13 @@ #ifndef H_BLE_HS_ADV_ #define H_BLE_HS_ADV_ +/** + * @brief Bluetooth Host Advertising API + * @defgroup bt_adv Bluetooth Host Advertising API + * @ingroup bt_host + * @{ + */ + #include #include "host/ble_uuid.h" @@ -27,115 +34,245 @@ extern "C" { #endif +/** Max Advertising Data Size. */ #define BLE_HS_ADV_MAX_SZ BLE_HCI_MAX_ADV_DATA_LEN /** Max field payload size (account for 2-byte header). */ #define BLE_HS_ADV_MAX_FIELD_SZ (BLE_HS_ADV_MAX_SZ - 2) +/** Represents advertising data packet in BLE advertisement or scan response. */ struct ble_hs_adv_field { + /** Length of the advertising data (type and value). */ uint8_t length; + + /** Type of the advertising data field. */ uint8_t type; + + /** Value of the advertising data field. */ uint8_t value[0]; }; +/** Function pointer typedef for parsing an advertising data field. */ typedef int (* ble_hs_adv_parse_func_t) (const struct ble_hs_adv_field *, void *); +/** Advertising Data Fields. */ struct ble_hs_adv_fields { - /*** 0x01 - Flags. */ + /** 0x01 - Flags. */ uint8_t flags; - /*** 0x02,0x03 - 16-bit service class UUIDs. */ + /** 0x02,0x03 - 16-bit service class UUIDs. */ const ble_uuid16_t *uuids16; + + /** Number of 16-bit UUIDs. */ uint8_t num_uuids16; + + /** Indicates if the list of 16-bit UUIDs is complete. */ unsigned uuids16_is_complete:1; - /*** 0x04,0x05 - 32-bit service class UUIDs. */ + + /** 0x04,0x05 - 32-bit service class UUIDs. */ const ble_uuid32_t *uuids32; + + /** Number of 32-bit UUIDs. */ uint8_t num_uuids32; + + /** Indicates if the list of 32-bit UUIDs is complete. */ unsigned uuids32_is_complete:1; - /*** 0x06,0x07 - 128-bit service class UUIDs. */ + + /** 0x06,0x07 - 128-bit service class UUIDs. */ const ble_uuid128_t *uuids128; + + /** Number of 128-bit UUIDs. */ uint8_t num_uuids128; + + /** Indicates if the list of 128-bit UUIDs is complete. */ unsigned uuids128_is_complete:1; - /*** 0x08,0x09 - Local name. */ + + /** 0x08,0x09 - Local name. */ const uint8_t *name; + + /** Length of the local name. */ uint8_t name_len; + + /** Indicates if the list of local names if complete. */ unsigned name_is_complete:1; - /*** 0x0a - Tx power level. */ + + /** 0x0a - Tx power level. */ int8_t tx_pwr_lvl; + + /** Indicates if Tx power level is present. */ unsigned tx_pwr_lvl_is_present:1; - /*** 0x0d - Slave connection interval range. */ + + /** 0x12 - Slave connection interval range. */ const uint8_t *slave_itvl_range; - /*** 0x16 - Service data - 16-bit UUID. */ + /** 0x16 - Service data - 16-bit UUID. */ const uint8_t *svc_data_uuid16; + + /** Length of the service data with 16-bit UUID. */ uint8_t svc_data_uuid16_len; - /*** 0x17 - Public target address. */ + + /** 0x17 - Public target address. */ const uint8_t *public_tgt_addr; + + /** Number of public target addresses. */ uint8_t num_public_tgt_addrs; - /*** 0x19 - Appearance. */ + /** 0x19 - Appearance. */ uint16_t appearance; + + /** Indicates if Appearance is present. */ unsigned appearance_is_present:1; - /*** 0x1a - Advertising interval. */ + + /** 0x1a - Advertising interval. */ uint16_t adv_itvl; + + /** Indicates if advertising interval is present. */ unsigned adv_itvl_is_present:1; - /*** 0x20 - Service data - 32-bit UUID. */ + + /** 0x20 - Service data - 32-bit UUID. */ const uint8_t *svc_data_uuid32; + + /** Length of the service data with 32-bit UUID. */ uint8_t svc_data_uuid32_len; - /*** 0x21 - Service data - 128-bit UUID. */ + + /** 0x21 - Service data - 128-bit UUID. */ const uint8_t *svc_data_uuid128; + + /** Length of service data with 128-bit UUID. */ uint8_t svc_data_uuid128_len; - /*** 0x24 - URI. */ + + /** 0x24 - URI. */ const uint8_t *uri; + + /** Length of the URI. */ uint8_t uri_len; - /*** 0xff - Manufacturer specific data. */ + + /** 0xff - Manufacturer specific data. */ const uint8_t *mfg_data; + + /** Length of manufacturer specific data. */ uint8_t mfg_data_len; }; +/** + * @defgroup ble_hs_adv_types BLE Advertising Common Data Types + * @{ + */ + +/** Common Data Type: Flags. */ #define BLE_HS_ADV_TYPE_FLAGS 0x01 + +/** Common Data Type: Incomplete List of 16-bit Service Class UUIDs. */ #define BLE_HS_ADV_TYPE_INCOMP_UUIDS16 0x02 + +/** Common Data Type: Complete List of 16-bit Service Class UUIDs. */ #define BLE_HS_ADV_TYPE_COMP_UUIDS16 0x03 + +/** Common Data Type: Incomplete List of 32-bit Service Class UUIDs. */ #define BLE_HS_ADV_TYPE_INCOMP_UUIDS32 0x04 + +/** Common Data Type: Complete List of 32-bit Service Class UUIDs. */ #define BLE_HS_ADV_TYPE_COMP_UUIDS32 0x05 + +/** Common Data Type: Incomplete List of 128-bit Service Class UUIDs. */ #define BLE_HS_ADV_TYPE_INCOMP_UUIDS128 0x06 + +/** Common Data Type: Complete List of 128-bit Service Class UUIDs. */ #define BLE_HS_ADV_TYPE_COMP_UUIDS128 0x07 + +/** Common Data Type: Shortened Local Name. */ #define BLE_HS_ADV_TYPE_INCOMP_NAME 0x08 + +/** Common Data Type: Complete Local Name. */ #define BLE_HS_ADV_TYPE_COMP_NAME 0x09 + +/** Common Data Type: Tx Power Level. */ #define BLE_HS_ADV_TYPE_TX_PWR_LVL 0x0a + +/** Common Data Type: Peripheral Connection Interval Range. */ #define BLE_HS_ADV_TYPE_SLAVE_ITVL_RANGE 0x12 + +/** Common Data Type: List of 16-bit Service Solicitation UUIDs. */ #define BLE_HS_ADV_TYPE_SOL_UUIDS16 0x14 + +/** Common Data Type: List of 128-bit Service Solicitation UUIDs. */ #define BLE_HS_ADV_TYPE_SOL_UUIDS128 0x15 + +/** Common Data Type: Service Data - 16-bit UUID. */ #define BLE_HS_ADV_TYPE_SVC_DATA_UUID16 0x16 + +/** Common Data Type: Public Target Address. */ #define BLE_HS_ADV_TYPE_PUBLIC_TGT_ADDR 0x17 + +/** Common Data Type: Random Target Address. */ #define BLE_HS_ADV_TYPE_RANDOM_TGT_ADDR 0x18 + +/** Common Data Type: Appearance. */ #define BLE_HS_ADV_TYPE_APPEARANCE 0x19 + +/** Common Data Type: Advertising Interval. */ #define BLE_HS_ADV_TYPE_ADV_ITVL 0x1a + +/** Common Data Type: Service Data - 32-bit UUID. */ #define BLE_HS_ADV_TYPE_SVC_DATA_UUID32 0x20 + +/** Common Data Type: Service Data - 128-bit UUID. */ #define BLE_HS_ADV_TYPE_SVC_DATA_UUID128 0x21 + +/** Common Data Type: URI. */ #define BLE_HS_ADV_TYPE_URI 0x24 + +/** Common Data Type: PB-ADV. */ #define BLE_HS_ADV_TYPE_MESH_PROV 0x29 + +/** Common Data Type: Mesh Message. */ #define BLE_HS_ADV_TYPE_MESH_MESSAGE 0x2a + +/** Common Data Type: Mesh Beacon. */ #define BLE_HS_ADV_TYPE_MESH_BEACON 0x2b + +/** Common Data Type: Manufacturer Specific Data. */ #define BLE_HS_ADV_TYPE_MFG_DATA 0xff +/** + * @} + */ + +/** + * @defgroup ble_hs_adv_flags BLE Advertising Flags + * @{ + */ +/** Length of BLE Advertising Flags field. */ #define BLE_HS_ADV_FLAGS_LEN 1 + +/** Limited Discoverable Mode Flag. */ #define BLE_HS_ADV_F_DISC_LTD 0x01 + +/** General Discoverable Mode Flag. */ #define BLE_HS_ADV_F_DISC_GEN 0x02 + +/** BR/EDR Not Supported Flag. */ #define BLE_HS_ADV_F_BREDR_UNSUP 0x04 +/** @} */ + +/** + * @defgroup ble_hs_adv_misc BLE Advertising Miscellaneous + * @{ + */ +/** Length of BLE advertising transmit power level field. */ #define BLE_HS_ADV_TX_PWR_LVL_LEN 1 /** @@ -144,29 +281,83 @@ struct ble_hs_adv_fields { */ #define BLE_HS_ADV_TX_PWR_LVL_AUTO (-128) +/** Length of the Peripheral Connection Interval Range field. */ #define BLE_HS_ADV_SLAVE_ITVL_RANGE_LEN 4 +/** Minimum length of the Service Data - 16-bit UUID field. */ #define BLE_HS_ADV_SVC_DATA_UUID16_MIN_LEN 2 +/** Length of a Public Target Address entry. */ #define BLE_HS_ADV_PUBLIC_TGT_ADDR_ENTRY_LEN 6 +/** Length of the Appearance field. */ #define BLE_HS_ADV_APPEARANCE_LEN 2 +/** Length of the Advertising Interval field. */ #define BLE_HS_ADV_ADV_ITVL_LEN 2 +/** Minimum length of the Service Data - 32-bit UUID field. */ #define BLE_HS_ADV_SVC_DATA_UUID32_MIN_LEN 4 +/** Minimum length of the Service Data - 128-bit UUID field. */ #define BLE_HS_ADV_SVC_DATA_UUID128_MIN_LEN 16 +/** + * @} + */ + +/** + * Set the advertising data fields in an os_mbuf. + * + * @param adv_fields Pointer to the advertising data structure. + * @param om Pointer to the memory buffer that will be written with + * advertising data. + * + * @return 0 on success; non-zero on failure. + */ int ble_hs_adv_set_fields_mbuf(const struct ble_hs_adv_fields *adv_fields, struct os_mbuf *om); +/** + * Set the advertising data fields in a destination buffer. + * + * @param adv_fields Pointer to the advertising data structure. + * @param dst Pointer to the destination buffer that will be written + * with advertising data. + * @param dst_len Pointer to the variable that will hold the length of + * the data written. + * @param max_len Maximum length of the destination buffer. + * + * @return 0 on success; nonzero on failure. + */ int ble_hs_adv_set_fields(const struct ble_hs_adv_fields *adv_fields, uint8_t *dst, uint8_t *dst_len, uint8_t max_len); +/** + * Parse the advertising data fields from a source buffer. + * + * @param adv_fields Pointer to the advertising data fields structure + * to populate. + * @param src Pointer to the source buffer containing the data + * to parse. + * @param src_len Length of the source buffer. + * + * @return 0 on success; nonzero on failure. + */ int ble_hs_adv_parse_fields(struct ble_hs_adv_fields *adv_fields, const uint8_t *src, uint8_t src_len); +/** + * Parse the advertising data using the provided parsing function. + * + * @param data Pointer to the advertising data buffer to parse. + * @param length Length of the advertising data buffer. + * @param func Pointer to the parsing function to apply to each + * field. + * @param user_data User-defined data to pass to the parsing function. + * + * @return 0 on success; nonzero on failure. + */ int ble_hs_adv_parse(const uint8_t *data, uint8_t length, ble_hs_adv_parse_func_t func, void *user_data); @@ -174,4 +365,8 @@ int ble_hs_adv_parse(const uint8_t *data, uint8_t length, } #endif +/** + * @} + */ + #endif