1 /* 2 * Copyright (C) 2014 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS 24 * RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 #ifndef __GAP_H 39 #define __GAP_H 40 41 #if defined __cplusplus 42 extern "C" { 43 #endif 44 45 #include "btstack_defines.h" 46 #include "btstack_util.h" 47 48 typedef enum { 49 50 // MITM protection not required 51 // No encryption required 52 // No user interaction required 53 LEVEL_0 = 0, 54 55 // MITM protection not required 56 // No encryption required 57 // Minimal user interaction desired 58 LEVEL_1, 59 60 // MITM protection not required 61 // Encryption required 62 LEVEL_2, 63 64 // MITM protection required 65 // Encryption required 66 // User interaction acceptable 67 LEVEL_3, 68 69 // MITM protection required 70 // Encryption required 71 // 128-bit equivalent strength for link and encryption keys required (P-192 is not enough) 72 // User interaction acceptable 73 LEVEL_4, 74 } gap_security_level_t; 75 76 typedef enum { 77 GAP_SECURITY_NONE, 78 GAP_SECUIRTY_ENCRYPTED, // SSP: JUST WORKS 79 GAP_SECURITY_AUTHENTICATED, // SSP: numeric comparison, passkey, OOB 80 // GAP_SECURITY_AUTHORIZED 81 } gap_security_state; 82 83 typedef enum { 84 GAP_CONNECTION_INVALID, 85 GAP_CONNECTION_ACL, 86 GAP_CONNECTION_SCO, 87 GAP_CONNECTION_LE 88 } gap_connection_type_t; 89 90 typedef struct le_connection_parameter_range{ 91 uint16_t le_conn_interval_min; 92 uint16_t le_conn_interval_max; 93 uint16_t le_conn_latency_min; 94 uint16_t le_conn_latency_max; 95 uint16_t le_supervision_timeout_min; 96 uint16_t le_supervision_timeout_max; 97 } le_connection_parameter_range_t; 98 99 typedef enum { 100 GAP_RANDOM_ADDRESS_TYPE_OFF = 0, 101 GAP_RANDOM_ADDRESS_NON_RESOLVABLE, 102 GAP_RANDOM_ADDRESS_RESOLVABLE, 103 } gap_random_address_type_t; 104 105 /* API_START */ 106 107 // Classic + LE 108 109 /** 110 * @brief Disconnect connection with handle 111 * @param handle 112 */ 113 uint8_t gap_disconnect(hci_con_handle_t handle); 114 115 /** 116 * @brief Get connection type 117 * @param con_handle 118 * @result connection_type 119 */ 120 gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle); 121 122 // Classic 123 124 /** 125 * @brief Sets local name. 126 * @note has to be done before stack starts up 127 * @param name is not copied, make sure memory is accessible during stack startup 128 */ 129 void gap_set_local_name(const char * local_name); 130 131 /** 132 * @brief Set Extended Inquiry Response data 133 * @param eir_data size 240 bytes, is not copied make sure memory is accessible during stack startup 134 * @note has to be done before stack starts up 135 */ 136 void gap_set_extended_inquiry_response(const uint8_t * data); 137 138 /** 139 * @brief Set class of device that will be set during Bluetooth init. 140 * @note has to be done before stack starts up 141 */ 142 void gap_set_class_of_device(uint32_t class_of_device); 143 144 /** 145 * @brief Enable/disable bonding. Default is enabled. 146 * @param enabled 147 */ 148 void gap_set_bondable_mode(int enabled); 149 150 /** 151 * @brief Get bondable mode. 152 * @return 1 if bondable 153 */ 154 int gap_get_bondable_mode(void); 155 156 /* Configure Secure Simple Pairing */ 157 158 /** 159 * @brief Enable will enable SSP during init. 160 */ 161 void gap_ssp_set_enable(int enable); 162 163 /** 164 * @brief Set IO Capability. BTstack will return capability to SSP requests 165 */ 166 void gap_ssp_set_io_capability(int ssp_io_capability); 167 168 /** 169 * @brief Set Authentication Requirements using during SSP 170 */ 171 void gap_ssp_set_authentication_requirement(int authentication_requirement); 172 173 /** 174 * @brief If set, BTstack will confirm a numeric comparison and enter '000000' if requested. 175 */ 176 void gap_ssp_set_auto_accept(int auto_accept); 177 178 /** 179 * @brief Start dedicated bonding with device. Disconnect after bonding. 180 * @param device 181 * @param request MITM protection 182 * @return error, if max num acl connections active 183 * @result GAP_DEDICATED_BONDING_COMPLETE 184 */ 185 int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required); 186 187 gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type); 188 gap_security_level_t gap_security_level(hci_con_handle_t con_handle); 189 190 void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level); 191 192 int gap_mitm_protection_required_for_security_level(gap_security_level_t level); 193 194 // LE 195 196 /** 197 * @brief Set parameters for LE Scan 198 */ 199 void gap_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window); 200 201 /** 202 * @brief Start LE Scan 203 */ 204 void gap_start_scan(void); 205 206 /** 207 * @brief Stop LE Scan 208 */ 209 void gap_stop_scan(void); 210 211 /** 212 * @brief Enable privacy by using random addresses 213 * @param random_address_type to use (incl. OFF) 214 */ 215 void gap_random_address_set_mode(gap_random_address_type_t random_address_type); 216 217 /** 218 * @brief Get privacy mode 219 */ 220 gap_random_address_type_t gap_random_address_get_mode(void); 221 222 /** 223 * @brief Sets update period for random address 224 * @param period_ms in ms 225 */ 226 void gap_random_address_set_update_period(int period_ms); 227 228 /** 229 * @brief Sets a fixed random address for advertising 230 * @param addr 231 * @note Sets random address mode to type off 232 */ 233 void gap_random_address_set(bd_addr_t addr); 234 235 /** 236 * @brief Set Advertisement Data 237 * @param advertising_data_length 238 * @param advertising_data (max 31 octets) 239 * @note data is not copied, pointer has to stay valid 240 */ 241 void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data); 242 243 /** 244 * @brief Set Advertisement Paramters 245 * @param adv_int_min 246 * @param adv_int_max 247 * @param adv_type 248 * @param direct_address_type 249 * @param direct_address 250 * @param channel_map 251 * @param filter_policy 252 * @note own_address_type is used from gap_random_address_set_mode 253 */ 254 void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, 255 uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy); 256 257 /** 258 * @brief Enable/Disable Advertisements. OFF by default. 259 * @param enabled 260 */ 261 void gap_advertisements_enable(int enabled); 262 263 /** 264 * @brief Set Scan Response Data 265 * 266 * @note For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used 267 * 268 * @param advertising_data_length 269 * @param advertising_data (max 31 octets) 270 * @note data is not copied, pointer has to stay valid 271 */ 272 void gap_scan_response_set_data(uint8_t scan_response_data_length, uint8_t * scan_response_data); 273 274 /** 275 * @brief Request an update of the connection parameter for a given LE connection 276 * @param handle 277 * @param conn_interval_min (unit: 1.25ms) 278 * @param conn_interval_max (unit: 1.25ms) 279 * @param conn_latency 280 * @param supervision_timeout (unit: 10ms) 281 * @returns 0 if ok 282 */ 283 int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min, 284 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 285 286 /** 287 * @brief Updates the connection parameters for a given LE connection 288 * @param handle 289 * @param conn_interval_min (unit: 1.25ms) 290 * @param conn_interval_max (unit: 1.25ms) 291 * @param conn_latency 292 * @param supervision_timeout (unit: 10ms) 293 * @returns 0 if ok 294 */ 295 int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min, 296 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 297 298 /** 299 * @brief Set accepted connection parameter range 300 * @param range 301 */ 302 void gap_get_connection_parameter_range(le_connection_parameter_range_t * range); 303 304 /** 305 * @brief Get accepted connection parameter range 306 * @param range 307 */ 308 void gap_set_connection_parameter_range(le_connection_parameter_range_t * range); 309 310 /** 311 * @brief Connect to remote LE device 312 */ 313 uint8_t gap_connect(bd_addr_t addr, bd_addr_type_t addr_type); 314 315 /** 316 * @brief Cancel connection process initiated by gap_connect 317 */ 318 uint8_t gap_connect_cancel(void); 319 320 /** 321 * @brief Auto Connection Establishment - Start Connecting to device 322 * @param address_typ 323 * @param address 324 * @returns 0 if ok 325 */ 326 int gap_auto_connection_start(bd_addr_type_t address_typ, bd_addr_t address); 327 328 /** 329 * @brief Auto Connection Establishment - Stop Connecting to device 330 * @param address_typ 331 * @param address 332 * @returns 0 if ok 333 */ 334 int gap_auto_connection_stop(bd_addr_type_t address_typ, bd_addr_t address); 335 336 /** 337 * @brief Auto Connection Establishment - Stop everything 338 * @note Convenience function to stop all active auto connection attempts 339 */ 340 void gap_auto_connection_stop_all(void); 341 342 // Classic 343 344 /** 345 * @brief Override page scan mode. Page scan mode enabled by l2cap when services are registered 346 * @note Might be used to reduce power consumption while Bluetooth module stays powered but no (new) 347 * connections are expected 348 */ 349 void gap_connectable_control(uint8_t enable); 350 351 /** 352 * @brief Allows to control if device is discoverable. OFF by default. 353 */ 354 void gap_discoverable_control(uint8_t enable); 355 356 /** 357 * @brief Gets local address. 358 */ 359 void gap_local_bd_addr(bd_addr_t address_buffer); 360 361 /** 362 * @brief Deletes link key for remote device with baseband address. 363 * @param addr 364 */ 365 void gap_drop_link_key_for_bd_addr(bd_addr_t addr); 366 367 /** 368 * @brief Store link key for remote device with baseband address 369 * @param addr 370 * @param link_key 371 * @param link_key_type 372 */ 373 void gap_store_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t type); 374 375 // LE 376 377 /** 378 * @brief Get addr type and address used in advertisement packets. 379 */ 380 void gap_advertisements_get_address(uint8_t * addr_type, bd_addr_t addr); 381 382 383 /* API_END*/ 384 385 #if defined __cplusplus 386 } 387 #endif 388 389 #endif // __GAP_H 390