Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of nrf51-sdk by
ble_advdata.h
00001 /* 00002 * Copyright (c) Nordic Semiconductor ASA 00003 * All rights reserved. 00004 * 00005 * Redistribution and use in source and binary forms, with or without modification, 00006 * are permitted provided that the following conditions are met: 00007 * 00008 * 1. Redistributions of source code must retain the above copyright notice, this 00009 * list of conditions and the following disclaimer. 00010 * 00011 * 2. Redistributions in binary form must reproduce the above copyright notice, this 00012 * list of conditions and the following disclaimer in the documentation and/or 00013 * other materials provided with the distribution. 00014 * 00015 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other 00016 * contributors to this software may be used to endorse or promote products 00017 * derived from this software without specific prior written permission. 00018 * 00019 * 00020 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 00021 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 00022 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 00023 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 00024 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 00025 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 00026 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 00027 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 00028 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 00029 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00030 * 00031 */ 00032 00033 /** @file 00034 * 00035 * @defgroup ble_sdk_lib_advdata Advertising and Scan Response Data Encoder 00036 * @{ 00037 * @ingroup ble_sdk_lib 00038 * @brief Functions for encoding data in the Advertising and Scan Response Data format, 00039 * and for passing the data to the stack. 00040 */ 00041 00042 #ifndef BLE_ADVDATA_H__ 00043 #define BLE_ADVDATA_H__ 00044 00045 #include <stdint.h> 00046 #include <stdbool.h> 00047 #include <string.h> 00048 #include "nrf_ble.h" 00049 #include "app_util.h " 00050 00051 00052 #define ADV_LENGTH_FIELD_SIZE 1UL /**< Advertising Data and Scan Response format contains 1 octet for the length. */ 00053 #define ADV_AD_TYPE_FIELD_SIZE 1UL /**< Advertising Data and Scan Response format contains 1 octet for the AD type. */ 00054 #define ADV_AD_DATA_OFFSET (ADV_LENGTH_FIELD_SIZE + \ 00055 ADV_AD_TYPE_FIELD_SIZE) /**< Offset for the AD data field of the Advertising Data and Scan Response format. */ 00056 #define AD_TYPE_TK_VALUE_DATA_SIZE (sizeof(ble_advdata_tk_value_t)) /**< Data size (in octets) of the Security Manager TK value AD type. */ 00057 #define AD_TYPE_TK_VALUE_SIZE (ADV_AD_DATA_OFFSET + \ 00058 AD_TYPE_TK_VALUE_DATA_SIZE) /**< Size (in octets) of the Security Manager TK value AD type. */ 00059 #define AD_TYPE_LE_ROLE_DATA_SIZE 1UL /**< Data size (in octets) of the LE Bluetooth Device Address AD type. */ 00060 #define AD_TYPE_LE_ROLE_SIZE (ADV_AD_DATA_OFFSET + \ 00061 AD_TYPE_LE_ROLE_DATA_SIZE) /**< Size (in octets) of the LE Bluetooth Device Address AD type. */ 00062 #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. */ 00063 #define AD_TYPE_BLE_DEVICE_ADDR_DATA_SIZE (BLE_GAP_ADDR_LEN + \ 00064 AD_TYPE_BLE_DEVICE_ADDR_TYPE_SIZE) /**< Data size (in octets) of the LE Bluetooth Device Address AD type. */ 00065 #define AD_TYPE_BLE_DEVICE_ADDR_SIZE (ADV_AD_DATA_OFFSET + \ 00066 AD_TYPE_BLE_DEVICE_ADDR_DATA_SIZE) /**< Size (in octets) of the LE Bluetooth Device Address AD type. */ 00067 #define AD_TYPE_APPEARANCE_DATA_SIZE 2UL /**< Data size (in octets) of the Appearance AD type. */ 00068 #define AD_TYPE_APPEARANCE_SIZE (ADV_AD_DATA_OFFSET + \ 00069 AD_TYPE_APPEARANCE_DATA_SIZE) /**< Size (in octets) of the Appearance AD type. */ 00070 #define AD_TYPE_FLAGS_DATA_SIZE 1UL /**< Data size (in octets) of the Flags AD type. */ 00071 #define AD_TYPE_FLAGS_SIZE (ADV_AD_DATA_OFFSET + \ 00072 AD_TYPE_FLAGS_DATA_SIZE) /**< Size (in octets) of the Flags AD type. */ 00073 #define AD_TYPE_TX_POWER_LEVEL_DATA_SIZE 1UL /**< Data size (in octets) of the TX Power Level AD type. */ 00074 #define AD_TYPE_TX_POWER_LEVEL_SIZE (ADV_AD_DATA_OFFSET + \ 00075 AD_TYPE_TX_POWER_LEVEL_DATA_SIZE) /**< Size (in octets) of the TX Power Level AD type. */ 00076 #define AD_TYPE_CONN_INT_DATA_SIZE 4UL /**< Data size (in octets) of the Slave Connection Interval Range AD type. */ 00077 #define AD_TYPE_CONN_INT_SIZE (ADV_AD_DATA_OFFSET + \ 00078 AD_TYPE_CONN_INT_DATA_SIZE) /**< Data size (in octets) of the Slave Connection Interval Range AD type. */ 00079 #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. */ 00080 #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. */ 00081 #define AD_TYPE_OOB_FLAGS_DATA_SIZE 1UL /**< Data size (in octets) of the Security Manager OOB Flags AD type. */ 00082 #define AD_TYPE_OOB_FLAGS_SIZE (ADV_AD_DATA_OFFSET + \ 00083 AD_TYPE_OOB_FLAGS_DATA_SIZE) /**< Size (in octets) of the Security Manager OOB Flags AD type. */ 00084 00085 #define AD_TYPE_SEC_MGR_OOB_FLAG_SET 1U /**< Security Manager OOB Flag set. Flag selection is done using _POS defines */ 00086 #define AD_TYPE_SEC_MGR_OOB_FLAG_CLEAR 0U /**< Security Manager OOB Flag clear. Flag selection is done using _POS defines */ 00087 #define AD_TYPE_SEC_MGR_OOB_FLAG_OOB_DATA_PRESENT_POS 0UL /**< Security Manager OOB Data Present Flag position. */ 00088 #define AD_TYPE_SEC_MGR_OOB_FLAG_OOB_LE_SUPPORTED_POS 1UL /**< Security Manager OOB Low Energy Supported Flag position. */ 00089 #define AD_TYPE_SEC_MGR_OOB_FLAG_SIM_LE_AND_EP_POS 2UL /**< Security Manager OOB Simultaneous LE and BR/EDR to Same Device Capable Flag position. */ 00090 #define AD_TYPE_SEC_MGR_OOB_ADDRESS_TYPE_PUBLIC 0UL /**< Security Manager OOB Public Address type. */ 00091 #define AD_TYPE_SEC_MGR_OOB_ADDRESS_TYPE_RANDOM 1UL /**< Security Manager OOB Random Address type. */ 00092 #define AD_TYPE_SEC_MGR_OOB_FLAG_ADDRESS_TYPE_POS 3UL /**< Security Manager OOB Address type Flag (0 = Public Address, 1 = Random Address) position. */ 00093 00094 00095 /**@brief Security Manager TK value. */ 00096 typedef struct 00097 { 00098 uint8_t tk[BLE_GAP_SEC_KEY_LEN]; /**< Array containing TK value. */ 00099 } ble_advdata_tk_value_t; 00100 00101 /**@brief Advertising data LE Role types. This enumeration contains the options available for the LE role inside 00102 * the advertising data. */ 00103 typedef enum 00104 { 00105 BLE_ADVDATA_ROLE_NOT_PRESENT = 0, /**< LE Role AD structure not present. */ 00106 BLE_ADVDATA_ROLE_ONLY_PERIPH, /**< Only Peripheral Role supported. */ 00107 BLE_ADVDATA_ROLE_ONLY_CENTRAL, /**< Only Central Role supported. */ 00108 BLE_ADVDATA_ROLE_BOTH_PERIPH_PREFERRED, /**< Peripheral and Central Role supported. Peripheral Role preferred for connection establishment. */ 00109 BLE_ADVDATA_ROLE_BOTH_CENTRAL_PREFERRED /**< Peripheral and Central Role supported. Central Role preferred for connection establishment */ 00110 } ble_advdata_le_role_t; 00111 00112 /**@brief Advertising data name type. This enumeration contains the options available for the device name inside 00113 * the advertising data. */ 00114 typedef enum 00115 { 00116 BLE_ADVDATA_NO_NAME, /**< Include no device name in advertising data. */ 00117 BLE_ADVDATA_SHORT_NAME, /**< Include short device name in advertising data. */ 00118 BLE_ADVDATA_FULL_NAME /**< Include full device name in advertising data. */ 00119 } ble_advdata_name_type_t; 00120 00121 /**@brief UUID list type. */ 00122 typedef struct 00123 { 00124 uint16_t uuid_cnt; /**< Number of UUID entries. */ 00125 ble_uuid_t * p_uuids; /**< Pointer to UUID array entries. */ 00126 } ble_advdata_uuid_list_t; 00127 00128 /**@brief Connection interval range structure. */ 00129 typedef struct 00130 { 00131 uint16_t min_conn_interval; /**< Minimum connection interval, in units of 1.25 ms, range 6 to 3200 (7.5 ms to 4 s). */ 00132 uint16_t max_conn_interval; /**< Maximum connection interval, in units of 1.25 ms, range 6 to 3200 (7.5 ms to 4 s). The value 0xFFFF indicates no specific maximum. */ 00133 } ble_advdata_conn_int_t; 00134 00135 /**@brief Manufacturer specific data structure. */ 00136 typedef struct 00137 { 00138 uint16_t company_identifier; /**< Company identifier code. */ 00139 uint8_array_t data; /**< Additional manufacturer specific data. */ 00140 } ble_advdata_manuf_data_t; 00141 00142 /**@brief Service data structure. */ 00143 typedef struct 00144 { 00145 uint16_t service_uuid; /**< Service UUID. */ 00146 uint8_array_t data; /**< Additional service data. */ 00147 } ble_advdata_service_data_t; 00148 00149 /**@brief Advertising data structure. This structure contains all options and data needed for encoding and 00150 * setting the advertising data. */ 00151 typedef struct 00152 { 00153 ble_advdata_name_type_t name_type; /**< Type of device name. */ 00154 uint8_t short_name_len; /**< Length of short device name (if short type is specified). */ 00155 bool include_appearance; /**< Determines if Appearance shall be included. */ 00156 uint8_t flags; /**< Advertising data Flags field. */ 00157 int8_t * p_tx_power_level; /**< TX Power Level field. */ 00158 ble_advdata_uuid_list_t uuids_more_available; /**< List of UUIDs in the 'More Available' list. */ 00159 ble_advdata_uuid_list_t uuids_complete; /**< List of UUIDs in the 'Complete' list. */ 00160 ble_advdata_uuid_list_t uuids_solicited; /**< List of solicited UUIDs. */ 00161 ble_advdata_conn_int_t * p_slave_conn_int; /**< Slave Connection Interval Range. */ 00162 ble_advdata_manuf_data_t * p_manuf_specific_data; /**< Manufacturer specific data. */ 00163 ble_advdata_service_data_t * p_service_data_array; /**< Array of Service data structures. */ 00164 uint8_t service_data_count; /**< Number of Service data structures. */ 00165 bool include_ble_device_addr; /**< Determines if LE Bluetooth Device Address shall be included. */ 00166 ble_advdata_le_role_t le_role; /**< LE Role field. Included when different from @ref BLE_ADVDATA_ROLE_NOT_PRESENT.*/ 00167 ble_advdata_tk_value_t * p_tk_value; /**< Security Manager TK value field. Included when different from NULL.*/ 00168 uint8_t * p_sec_mgr_oob_flags; /**< Security Manager Out Of Band Flags field. Included when different from NULL.*/ 00169 } ble_advdata_t; 00170 00171 /**@brief Function for encoding data in the Advertising and Scan Response data format 00172 * (AD structures). 00173 * 00174 * @details This function encodes data into the Advertising and Scan Response data format 00175 * (AD structures) based on the selections in the supplied structures. This function can be used to 00176 * create a payload of Advertising packet or Scan Response packet, or a payload of NFC 00177 * message intended for initiating the Out-of-Band pairing. 00178 * 00179 * @param[in] p_advdata Pointer to the structure for specifying the content of encoded data. 00180 * @param[out] p_encoded_data Pointer to the buffer where encoded data will be returned. 00181 * @param[in,out] p_len \c in: Size of \p p_encoded_data buffer. 00182 * \c out: Length of encoded data. 00183 * 00184 * @retval NRF_SUCCESS If the operation was successful. 00185 * @retval NRF_ERROR_INVALID_PARAM If the operation failed because a wrong parameter was provided in \p p_advdata. 00186 * @retval NRF_ERROR_DATA_SIZE If the operation failed because not all the requested data could fit into the 00187 * provided buffer or some encoded AD structure is too long and its 00188 * length cannot be encoded with one octet. 00189 * 00190 * @warning This API may override the application's request to use the long name and use a short name 00191 * instead. This truncation will occur in case the long name does not fit the provided buffer size. 00192 * The application can specify a preferred short name length if truncation is required. 00193 * For example, if the complete device name is ABCD_HRMonitor, the application can specify the short name 00194 * length to be 8, so that the short device name appears as ABCD_HRM instead of ABCD_HRMo or ABCD_HRMoni 00195 * if the available size for the short name is 9 or 12 respectively, to have a more appropriate short name. 00196 * However, it should be noted that this is just a preference that the application can specify, and 00197 * if the preference is too large to fit in the provided buffer, the name can be truncated further. 00198 */ 00199 uint32_t adv_data_encode(ble_advdata_t const * const p_advdata, 00200 uint8_t * const p_encoded_data, 00201 uint16_t * const p_len); 00202 00203 /**@brief Function for encoding and setting the advertising data and/or scan response data. 00204 * 00205 * @details This function encodes advertising data and/or scan response data based on the selections 00206 * in the supplied structures, and passes the encoded data to the stack. 00207 * 00208 * @param[in] p_advdata Structure for specifying the content of the advertising data. 00209 * Set to NULL if advertising data is not to be set. 00210 * @param[in] p_srdata Structure for specifying the content of the scan response data. 00211 * Set to NULL if scan response data is not to be set. 00212 * 00213 * @retval NRF_SUCCESS If the operation was successful. 00214 * @retval NRF_ERROR_INVALID_PARAM If the operation failed because a wrong parameter was provided in \p p_advdata. 00215 * @retval NRF_ERROR_DATA_SIZE If the operation failed because not all the requested data could fit into the 00216 * advertising packet. The maximum size of the advertisement packet 00217 * is @ref BLE_GAP_ADV_MAX_SIZE. 00218 * 00219 * @warning This API may override the application's request to use the long name and use a short name 00220 * instead. This truncation will occur in case the long name does not fit the provided buffer size. 00221 * The application can specify a preferred short name length if truncation is required. 00222 * For example, if the complete device name is ABCD_HRMonitor, the application can specify the short name 00223 * length to be 8, so that the short device name appears as ABCD_HRM instead of ABCD_HRMo or ABCD_HRMoni 00224 * if the available size for the short name is 9 or 12 respectively, to have a more appropriate short name. 00225 * However, it should be noted that this is just a preference that the application can specify, and 00226 * if the preference is too large to fit in the provided buffer, the name can be truncated further. 00227 */ 00228 uint32_t ble_advdata_set(const ble_advdata_t * p_advdata, const ble_advdata_t * p_srdata); 00229 00230 #endif // BLE_ADVDATA_H__ 00231 00232 /** @} */
Generated on Tue Jul 12 2022 17:52:43 by
