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_TYPE_STATIC, 102 GAP_RANDOM_ADDRESS_NON_RESOLVABLE, 103 GAP_RANDOM_ADDRESS_RESOLVABLE, 104 } gap_random_address_type_t; 105 106 // Authorization state 107 typedef enum { 108 AUTHORIZATION_UNKNOWN, 109 AUTHORIZATION_PENDING, 110 AUTHORIZATION_DECLINED, 111 AUTHORIZATION_GRANTED 112 } authorization_state_t; 113 114 115 /* API_START */ 116 117 // Classic + LE 118 119 /** 120 * @brief Disconnect connection with handle 121 * @param handle 122 */ 123 uint8_t gap_disconnect(hci_con_handle_t handle); 124 125 /** 126 * @brief Get connection type 127 * @param con_handle 128 * @result connection_type 129 */ 130 gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle); 131 132 // Classic 133 134 /** 135 * @brief Sets local name. 136 * @note has to be done before stack starts up 137 * @note Default name is 'BTstack 00:00:00:00:00:00' 138 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 139 * @param name is not copied, make sure memory is accessible during stack startup 140 */ 141 void gap_set_local_name(const char * local_name); 142 143 /** 144 * @brief Set Extended Inquiry Response data 145 * @note has to be done before stack starts up 146 * @note If not set, local name will be used for EIR data (see gap_set_local_name) 147 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 148 * @param eir_data size 240 bytes, is not copied make sure memory is accessible during stack startup 149 */ 150 void gap_set_extended_inquiry_response(const uint8_t * data); 151 152 /** 153 * @brief Set class of device that will be set during Bluetooth init. 154 * @note has to be done before stack starts up 155 */ 156 void gap_set_class_of_device(uint32_t class_of_device); 157 158 /** 159 * @brief Enable/disable bonding. Default is enabled. 160 * @param enabled 161 */ 162 void gap_set_bondable_mode(int enabled); 163 164 /** 165 * @brief Get bondable mode. 166 * @return 1 if bondable 167 */ 168 int gap_get_bondable_mode(void); 169 170 /* Configure Secure Simple Pairing */ 171 172 /** 173 * @brief Enable will enable SSP during init. 174 */ 175 void gap_ssp_set_enable(int enable); 176 177 /** 178 * @brief Set IO Capability. BTstack will return capability to SSP requests 179 */ 180 void gap_ssp_set_io_capability(int ssp_io_capability); 181 182 /** 183 * @brief Set Authentication Requirements using during SSP 184 */ 185 void gap_ssp_set_authentication_requirement(int authentication_requirement); 186 187 /** 188 * @brief If set, BTstack will confirm a numeric comparison and enter '000000' if requested. 189 */ 190 void gap_ssp_set_auto_accept(int auto_accept); 191 192 /** 193 * @brief Start dedicated bonding with device. Disconnect after bonding. 194 * @param device 195 * @param request MITM protection 196 * @return error, if max num acl connections active 197 * @result GAP_DEDICATED_BONDING_COMPLETE 198 */ 199 int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required); 200 201 gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type); 202 gap_security_level_t gap_security_level(hci_con_handle_t con_handle); 203 204 void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level); 205 206 int gap_mitm_protection_required_for_security_level(gap_security_level_t level); 207 208 // LE 209 210 /** 211 * @brief Set parameters for LE Scan 212 */ 213 void gap_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window); 214 215 /** 216 * @brief Start LE Scan 217 */ 218 void gap_start_scan(void); 219 220 /** 221 * @brief Stop LE Scan 222 */ 223 void gap_stop_scan(void); 224 225 /** 226 * @brief Enable privacy by using random addresses 227 * @param random_address_type to use (incl. OFF) 228 */ 229 void gap_random_address_set_mode(gap_random_address_type_t random_address_type); 230 231 /** 232 * @brief Get privacy mode 233 */ 234 gap_random_address_type_t gap_random_address_get_mode(void); 235 236 /** 237 * @brief Sets update period for random address 238 * @param period_ms in ms 239 */ 240 void gap_random_address_set_update_period(int period_ms); 241 242 /** 243 * @brief Sets a fixed random address for advertising 244 * @param addr 245 * @note Sets random address mode to type off 246 */ 247 void gap_random_address_set(bd_addr_t addr); 248 249 /** 250 * @brief Set Advertisement Data 251 * @param advertising_data_length 252 * @param advertising_data (max 31 octets) 253 * @note data is not copied, pointer has to stay valid 254 * @note '00:00:00:00:00:00' in advertising_data will be replaced with actual bd addr 255 */ 256 void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data); 257 258 /** 259 * @brief Set Advertisement Paramters 260 * @param adv_int_min 261 * @param adv_int_max 262 * @param adv_type 263 * @param direct_address_type 264 * @param direct_address 265 * @param channel_map 266 * @param filter_policy 267 * @note own_address_type is used from gap_random_address_set_mode 268 */ 269 void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, 270 uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy); 271 272 /** 273 * @brief Enable/Disable Advertisements. OFF by default. 274 * @param enabled 275 */ 276 void gap_advertisements_enable(int enabled); 277 278 /** 279 * @brief Set Scan Response Data 280 * 281 * @note For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used 282 * 283 * @param advertising_data_length 284 * @param advertising_data (max 31 octets) 285 * @note data is not copied, pointer has to stay valid 286 * @note '00:00:00:00:00:00' in scan_response_data will be replaced with actual bd addr 287 */ 288 void gap_scan_response_set_data(uint8_t scan_response_data_length, uint8_t * scan_response_data); 289 290 /** 291 * @brief Set connection parameters for outgoing connections 292 * @param conn_scan_interval (unit: 0.625 msec), default: 60 ms 293 * @param conn_scan_window (unit: 0.625 msec), default: 30 ms 294 * @param conn_interval_min (unit: 1.25ms), default: 10 ms 295 * @param conn_interval_max (unit: 1.25ms), default: 30 ms 296 * @param conn_latency, default: 4 297 * @param supervision_timeout (unit: 10ms), default: 720 ms 298 * @param min_ce_length (unit: 0.625ms), default: 10 ms 299 * @param max_ce_length (unit: 0.625ms), default: 30 ms 300 */ 301 void gap_set_connection_parameters(uint16_t conn_scan_interval, uint16_t conn_scan_window, 302 uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, 303 uint16_t supervision_timeout, uint16_t min_ce_length, uint16_t max_ce_length); 304 305 /** 306 * @brief Request an update of the connection parameter for a given LE connection 307 * @param handle 308 * @param conn_interval_min (unit: 1.25ms) 309 * @param conn_interval_max (unit: 1.25ms) 310 * @param conn_latency 311 * @param supervision_timeout (unit: 10ms) 312 * @returns 0 if ok 313 */ 314 int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min, 315 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 316 317 /** 318 * @brief Updates the connection parameters for a given LE connection 319 * @param handle 320 * @param conn_interval_min (unit: 1.25ms) 321 * @param conn_interval_max (unit: 1.25ms) 322 * @param conn_latency 323 * @param supervision_timeout (unit: 10ms) 324 * @returns 0 if ok 325 */ 326 int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min, 327 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 328 329 /** 330 * @brief Set accepted connection parameter range 331 * @param range 332 */ 333 void gap_get_connection_parameter_range(le_connection_parameter_range_t * range); 334 335 /** 336 * @brief Get accepted connection parameter range 337 * @param range 338 */ 339 void gap_set_connection_parameter_range(le_connection_parameter_range_t * range); 340 341 /** 342 * @brief Connect to remote LE device 343 */ 344 uint8_t gap_connect(bd_addr_t addr, bd_addr_type_t addr_type); 345 346 /** 347 * @brief Cancel connection process initiated by gap_connect 348 */ 349 uint8_t gap_connect_cancel(void); 350 351 /** 352 * @brief Auto Connection Establishment - Start Connecting to device 353 * @param address_typ 354 * @param address 355 * @returns 0 if ok 356 */ 357 int gap_auto_connection_start(bd_addr_type_t address_typ, bd_addr_t address); 358 359 /** 360 * @brief Auto Connection Establishment - Stop Connecting to device 361 * @param address_typ 362 * @param address 363 * @returns 0 if ok 364 */ 365 int gap_auto_connection_stop(bd_addr_type_t address_typ, bd_addr_t address); 366 367 /** 368 * @brief Auto Connection Establishment - Stop everything 369 * @note Convenience function to stop all active auto connection attempts 370 */ 371 void gap_auto_connection_stop_all(void); 372 373 /** 374 * 375 * @brief Get encryption key size. 376 * @param con_handle 377 * @return 0 if not encrypted, 7-16 otherwise 378 */ 379 int gap_encryption_key_size(hci_con_handle_t con_handle); 380 381 /** 382 * @brief Get authentication property. 383 * @param con_handle 384 * @return 1 if bonded with OOB/Passkey (AND MITM protection) 385 */ 386 int gap_authenticated(hci_con_handle_t con_handle); 387 388 /** 389 * @brief Queries authorization state. 390 * @param con_handle 391 * @return authorization_state for the current session 392 */ 393 authorization_state_t gap_authorization_state(hci_con_handle_t con_handle); 394 395 // Classic 396 397 /** 398 * @brief Override page scan mode. Page scan mode enabled by l2cap when services are registered 399 * @note Might be used to reduce power consumption while Bluetooth module stays powered but no (new) 400 * connections are expected 401 */ 402 void gap_connectable_control(uint8_t enable); 403 404 /** 405 * @brief Allows to control if device is discoverable. OFF by default. 406 */ 407 void gap_discoverable_control(uint8_t enable); 408 409 /** 410 * @brief Gets local address. 411 */ 412 void gap_local_bd_addr(bd_addr_t address_buffer); 413 414 /** 415 * @brief Deletes link key for remote device with baseband address. 416 * @param addr 417 */ 418 void gap_drop_link_key_for_bd_addr(bd_addr_t addr); 419 420 /** 421 * @brief Store link key for remote device with baseband address 422 * @param addr 423 * @param link_key 424 * @param link_key_type 425 */ 426 void gap_store_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t type); 427 428 /** 429 * @brief Start GAP Classic Inquiry 430 * @param duration in 1.28s units 431 * @return 0 if ok 432 * @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE 433 */ 434 int gap_inquiry_start(uint8_t duration_in_1280ms_units); 435 436 /** 437 * @brief Stop GAP Classic Inquiry 438 * @brief Stop GAP Classic Inquiry 439 * @returns 0 if ok 440 * @events: GAP_EVENT_INQUIRY_COMPLETE 441 */ 442 int gap_inquiry_stop(void); 443 444 /** 445 * @brief Remote Name Request 446 * @param addr 447 * @param page_scan_repetition_mode 448 * @param clock_offset only used when bit 15 is set - pass 0 if not known 449 * @events: HCI_EVENT_REMOTE_NAME_REQUEST_COMPLETE 450 */ 451 int gap_remote_name_request(bd_addr_t addr, uint8_t page_scan_repetition_mode, uint16_t clock_offset); 452 453 /** 454 * @brief Legacy Pairing Pin Code Response 455 * @param addr 456 * @param pin 457 * @return 0 if ok 458 */ 459 int gap_pin_code_response(bd_addr_t addr, const char * pin); 460 461 /** 462 * @brief Abort Legacy Pairing 463 * @param addr 464 * @param pin 465 * @return 0 if ok 466 */ 467 int gap_pin_code_negative(bd_addr_t addr); 468 469 /** 470 * @brief SSP Passkey Response 471 * @param addr 472 * @param passkey [0..999999] 473 * @return 0 if ok 474 */ 475 int gap_ssp_passkey_response(bd_addr_t addr, uint32_t passkey); 476 477 /** 478 * @brief Abort SSP Passkey Entry/Pairing 479 * @param addr 480 * @param pin 481 * @return 0 if ok 482 */ 483 int gap_ssp_passkey_negative(bd_addr_t addr); 484 485 /** 486 * @brief Accept SSP Numeric Comparison 487 * @param addr 488 * @param passkey 489 * @return 0 if ok 490 */ 491 int gap_ssp_confirmation_response(bd_addr_t addr); 492 493 /** 494 * @brief Abort SSP Numeric Comparison/Pairing 495 * @param addr 496 * @param pin 497 * @return 0 if ok 498 */ 499 int gap_ssp_confirmation_negative(bd_addr_t addr); 500 501 502 503 // LE 504 505 /** 506 * @brief Get own addr type and address used for LE 507 */ 508 void gap_le_get_own_address(uint8_t * addr_type, bd_addr_t addr); 509 510 511 /* API_END*/ 512 513 #if defined __cplusplus 514 } 515 #endif 516 517 #endif // __GAP_H 518