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 #include "classic/btstack_link_key_db.h" 48 49 typedef enum { 50 51 // MITM protection not required 52 // No encryption required 53 // No user interaction required 54 LEVEL_0 = 0, 55 56 // MITM protection not required 57 // No encryption required 58 // Minimal user interaction desired 59 LEVEL_1, 60 61 // MITM protection not required 62 // Encryption required 63 LEVEL_2, 64 65 // MITM protection required 66 // Encryption required 67 // User interaction acceptable 68 LEVEL_3, 69 70 // MITM protection required 71 // Encryption required 72 // 128-bit equivalent strength for link and encryption keys required (P-192 is not enough) 73 // User interaction acceptable 74 LEVEL_4, 75 } gap_security_level_t; 76 77 typedef enum { 78 GAP_SECURITY_NONE, 79 GAP_SECUIRTY_ENCRYPTED, // SSP: JUST WORKS 80 GAP_SECURITY_AUTHENTICATED, // SSP: numeric comparison, passkey, OOB 81 // GAP_SECURITY_AUTHORIZED 82 } gap_security_state; 83 84 typedef enum { 85 GAP_CONNECTION_INVALID, 86 GAP_CONNECTION_ACL, 87 GAP_CONNECTION_SCO, 88 GAP_CONNECTION_LE 89 } gap_connection_type_t; 90 91 typedef struct le_connection_parameter_range{ 92 uint16_t le_conn_interval_min; 93 uint16_t le_conn_interval_max; 94 uint16_t le_conn_latency_min; 95 uint16_t le_conn_latency_max; 96 uint16_t le_supervision_timeout_min; 97 uint16_t le_supervision_timeout_max; 98 } le_connection_parameter_range_t; 99 100 typedef enum { 101 GAP_RANDOM_ADDRESS_TYPE_OFF = 0, 102 GAP_RANDOM_ADDRESS_TYPE_STATIC, 103 GAP_RANDOM_ADDRESS_NON_RESOLVABLE, 104 GAP_RANDOM_ADDRESS_RESOLVABLE, 105 } gap_random_address_type_t; 106 107 // Authorization state 108 typedef enum { 109 AUTHORIZATION_UNKNOWN, 110 AUTHORIZATION_PENDING, 111 AUTHORIZATION_DECLINED, 112 AUTHORIZATION_GRANTED 113 } authorization_state_t; 114 115 116 /* API_START */ 117 118 // Classic + LE 119 120 /** 121 * @brief Disconnect connection with handle 122 * @param handle 123 */ 124 uint8_t gap_disconnect(hci_con_handle_t handle); 125 126 /** 127 * @brief Get connection type 128 * @param con_handle 129 * @result connection_type 130 */ 131 gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle); 132 133 /** 134 * @brief Get HCI connection role 135 * @param con_handle 136 * @result hci_role_t HCI_ROLE_MASTER / HCI_ROLE_SLAVE / HCI_ROLE_INVALID (if connection does not exist) 137 */ 138 hci_role_t gap_get_role(hci_con_handle_t connection_handle); 139 140 // Classic 141 142 /** 143 * @brief Request role switch 144 * @note this only requests the role switch. A HCI_EVENT_ROLE_CHANGE is emitted and its status field will indicate if the switch was succesful 145 * @param addr 146 * @param hci_role_t HCI_ROLE_MASTER / HCI_ROLE_SLAVE 147 * @result status 148 */ 149 uint8_t gap_request_role(const bd_addr_t addr, hci_role_t role); 150 151 /** 152 * @brief Sets local name. 153 * @note has to be done before stack starts up 154 * @note Default name is 'BTstack 00:00:00:00:00:00' 155 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 156 * @param name is not copied, make sure memory is accessible during stack startup 157 */ 158 void gap_set_local_name(const char * local_name); 159 160 /** 161 * @brief Set Extended Inquiry Response data 162 * @note has to be done before stack starts up 163 * @note If not set, local name will be used for EIR data (see gap_set_local_name) 164 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 165 * @param eir_data size HCI_EXTENDED_INQUIRY_RESPONSE_DATA_LEN (240) bytes, is not copied make sure memory is accessible during stack startup 166 */ 167 void gap_set_extended_inquiry_response(const uint8_t * data); 168 169 /** 170 * @brief Set class of device that will be set during Bluetooth init. 171 * @note has to be done before stack starts up 172 */ 173 void gap_set_class_of_device(uint32_t class_of_device); 174 175 /** 176 * @brief Set default link policy settings for all classic ACL links 177 * @param default_link_policy_settings - see LM_LINK_POLICY_* in bluetooth.h 178 * @note common value: LM_LINK_POLICY_ENABLE_ROLE_SWITCH | LM_LINK_POLICY_ENABLE_SNIFF_MODE to enable role switch and sniff mode 179 * @note has to be done before stack starts up 180 */ 181 void gap_set_default_link_policy_settings(uint16_t default_link_policy_settings); 182 183 /** 184 * @brief Set Allow Role Switch param for outgoing classic ACL links 185 * @param allow_role_switch - true: allow remote device to request role switch, false: stay master 186 */ 187 void gap_set_allow_role_switch(bool allow_role_switch); 188 189 /** 190 * @brief Set link supervision timeout for outgoing classic ACL links 191 * @param default_link_supervision_timeout * 0.625 ms, default 0x7d00 = 20 seconds 192 */ 193 void gap_set_link_supervision_timeout(uint16_t link_supervision_timeout); 194 195 /** 196 * @brief Enable/disable bonding. Default is enabled. 197 * @param enabled 198 */ 199 void gap_set_bondable_mode(int enabled); 200 201 /** 202 * @brief Get bondable mode. 203 * @return 1 if bondable 204 */ 205 int gap_get_bondable_mode(void); 206 207 /** 208 * @brief Set security level for all outgoing and incoming connections. Default: LEVEL_2 209 * @param security_level 210 * @note has to be called before services or profiles are initialized 211 */ 212 void gap_set_security_level(gap_security_level_t security_level); 213 214 /** 215 * @brief Get security level 216 * @return security_level 217 */ 218 gap_security_level_t gap_get_security_level(void); 219 220 /** 221 * @brief Register filter for rejecting classic connections. Callback will return 1 accept connection, 0 on reject. 222 */ 223 void gap_register_classic_connection_filter(int (*accept_callback)(bd_addr_t addr, hci_link_type_t link_type)); 224 225 /* Configure Secure Simple Pairing */ 226 227 /** 228 * @brief Enable will enable SSP during init. Default: true 229 */ 230 void gap_ssp_set_enable(int enable); 231 232 /** 233 * @brief Set IO Capability. BTstack will return capability to SSP requests 234 */ 235 void gap_ssp_set_io_capability(int ssp_io_capability); 236 237 /** 238 * @brief Set Authentication Requirements using during SSP 239 */ 240 void gap_ssp_set_authentication_requirement(int authentication_requirement); 241 242 /** 243 * @brief Enable/disable Secure Connections. Default: true if supported by Controller 244 */ 245 void gap_secure_connections_enable(bool enable); 246 247 /** 248 * @brief If set, BTstack will confirm a numeric comparison and enter '000000' if requested. 249 */ 250 void gap_ssp_set_auto_accept(int auto_accept); 251 252 /** 253 * @brief Set required encryption key size for GAP Levels 1-3 on ccassic connections. Default: 16 bytes 254 * @param encryption_key_size in bytes. Valid 7..16 255 */ 256 void gap_set_required_encryption_key_size(uint8_t encryption_key_size); 257 258 /** 259 * @brief Start dedicated bonding with device. Disconnect after bonding. 260 * @param device 261 * @param request MITM protection 262 * @return error, if max num acl connections active 263 * @result GAP_DEDICATED_BONDING_COMPLETE 264 */ 265 int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required); 266 267 gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type); 268 269 /** 270 * @brief map link keys to secure connection yes/no 271 */ 272 int gap_secure_connection_for_link_key_type(link_key_type_t link_key_type); 273 274 /** 275 * @brief map link keys to authenticated 276 */ 277 int gap_authenticated_for_link_key_type(link_key_type_t link_key_type); 278 279 gap_security_level_t gap_security_level(hci_con_handle_t con_handle); 280 281 void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level); 282 283 int gap_mitm_protection_required_for_security_level(gap_security_level_t level); 284 285 /** 286 * @brief Set Page Scan Type 287 * @param page_scan_interval * 0.625 ms, range: 0x0012..0x1000, default: 0x0800 288 * @param page_scan_windows * 0.625 ms, range: 0x0011..page_scan_interval, default: 0x0012 289 */ 290 void gap_set_page_scan_activity(uint16_t page_scan_interval, uint16_t page_scan_window); 291 292 /** 293 * @brief Set Page Scan Type 294 * @param page_scan_mode 295 */ 296 void gap_set_page_scan_type(page_scan_type_t page_scan_type); 297 298 // LE 299 300 /** 301 * @brief Set parameters for LE Scan 302 * @param scan_type 0 = passive, 1 = active 303 * @param scan_interval range 0x0004..0x4000, unit 0.625 ms 304 * @param scan_window range 0x0004..0x4000, unit 0.625 ms 305 * @param scanning_filter_policy 0 = all devices, 1 = all from whitelist 306 */ 307 void gap_set_scan_params(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window, uint8_t scanning_filter_policy); 308 309 /** 310 * @brief Set parameters for LE Scan 311 * @deprecated Use gap_set_scan_params instead 312 */ 313 void gap_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window); 314 315 /** 316 * @brief Start LE Scan 317 */ 318 void gap_start_scan(void); 319 320 /** 321 * @brief Stop LE Scan 322 */ 323 void gap_stop_scan(void); 324 325 /** 326 * @brief Enable privacy by using random addresses 327 * @param random_address_type to use (incl. OFF) 328 */ 329 void gap_random_address_set_mode(gap_random_address_type_t random_address_type); 330 331 /** 332 * @brief Get privacy mode 333 */ 334 gap_random_address_type_t gap_random_address_get_mode(void); 335 336 /** 337 * @brief Sets update period for random address 338 * @param period_ms in ms 339 */ 340 void gap_random_address_set_update_period(int period_ms); 341 342 /** 343 * @brief Sets a fixed random address for advertising 344 * @param addr 345 * @note Sets random address mode to type off 346 */ 347 void gap_random_address_set(const bd_addr_t addr); 348 349 /** 350 * @brief Set Advertisement Data 351 * @param advertising_data_length 352 * @param advertising_data (max 31 octets) 353 * @note data is not copied, pointer has to stay valid 354 * @note '00:00:00:00:00:00' in advertising_data will be replaced with actual bd addr 355 */ 356 void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data); 357 358 /** 359 * @brief Set Advertisement Paramters 360 * @param adv_int_min 361 * @param adv_int_max 362 * @param adv_type 363 * @param direct_address_type 364 * @param direct_address 365 * @param channel_map 366 * @param filter_policy 367 * @note own_address_type is used from gap_random_address_set_mode 368 */ 369 void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, 370 uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy); 371 372 /** 373 * @brief Enable/Disable Advertisements. OFF by default. 374 * @param enabled 375 */ 376 void gap_advertisements_enable(int enabled); 377 378 /** 379 * @brief Set Scan Response Data 380 * 381 * @note For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used 382 * 383 * @param advertising_data_length 384 * @param advertising_data (max 31 octets) 385 * @note data is not copied, pointer has to stay valid 386 * @note '00:00:00:00:00:00' in scan_response_data will be replaced with actual bd addr 387 */ 388 void gap_scan_response_set_data(uint8_t scan_response_data_length, uint8_t * scan_response_data); 389 390 /** 391 * @brief Set connection parameters for outgoing connections 392 * @param conn_scan_interval (unit: 0.625 msec), default: 60 ms 393 * @param conn_scan_window (unit: 0.625 msec), default: 30 ms 394 * @param conn_interval_min (unit: 1.25ms), default: 10 ms 395 * @param conn_interval_max (unit: 1.25ms), default: 30 ms 396 * @param conn_latency, default: 4 397 * @param supervision_timeout (unit: 10ms), default: 720 ms 398 * @param min_ce_length (unit: 0.625ms), default: 10 ms 399 * @param max_ce_length (unit: 0.625ms), default: 30 ms 400 */ 401 void gap_set_connection_parameters(uint16_t conn_scan_interval, uint16_t conn_scan_window, 402 uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, 403 uint16_t supervision_timeout, uint16_t min_ce_length, uint16_t max_ce_length); 404 405 /** 406 * @brief Request an update of the connection parameter for a given LE connection 407 * @param handle 408 * @param conn_interval_min (unit: 1.25ms) 409 * @param conn_interval_max (unit: 1.25ms) 410 * @param conn_latency 411 * @param supervision_timeout (unit: 10ms) 412 * @returns 0 if ok 413 */ 414 int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min, 415 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 416 417 /** 418 * @brief Updates the connection parameters for a given LE connection 419 * @param handle 420 * @param conn_interval_min (unit: 1.25ms) 421 * @param conn_interval_max (unit: 1.25ms) 422 * @param conn_latency 423 * @param supervision_timeout (unit: 10ms) 424 * @returns 0 if ok 425 */ 426 int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min, 427 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 428 429 /** 430 * @brief Set accepted connection parameter range 431 * @param range 432 */ 433 void gap_get_connection_parameter_range(le_connection_parameter_range_t * range); 434 435 /** 436 * @brief Get accepted connection parameter range 437 * @param range 438 */ 439 void gap_set_connection_parameter_range(le_connection_parameter_range_t * range); 440 441 /** 442 * @brief Test if connection parameters are inside in existing rage 443 * @param conn_interval_min (unit: 1.25ms) 444 * @param conn_interval_max (unit: 1.25ms) 445 * @param conn_latency 446 * @param supervision_timeout (unit: 10ms) 447 * @returns 1 if included 448 */ 449 int gap_connection_parameter_range_included(le_connection_parameter_range_t * existing_range, uint16_t le_conn_interval_min, uint16_t le_conn_interval_max, uint16_t le_conn_latency, uint16_t le_supervision_timeout); 450 451 /** 452 * @brief Set max number of connections in LE Peripheral role (if Bluetooth Controller supports it) 453 * @note: default: 1 454 * @param max_peripheral_connections 455 */ 456 void gap_set_max_number_peripheral_connections(int max_peripheral_connections); 457 458 /** 459 * @brief Add Device to Whitelist 460 * @param address_typ 461 * @param address 462 * @returns 0 if ok 463 */ 464 uint8_t gap_whitelist_add(bd_addr_type_t address_type, const bd_addr_t address); 465 466 /** 467 * @brief Remove Device from Whitelist 468 * @param address_typ 469 * @param address 470 * @returns 0 if ok 471 */ 472 uint8_t gap_whitelist_remove(bd_addr_type_t address_type, const bd_addr_t address); 473 474 /** 475 * @brief Clear Whitelist 476 * @returns 0 if ok 477 */ 478 uint8_t gap_whitelist_clear(void); 479 480 /** 481 * @brief Connect to remote LE device 482 */ 483 uint8_t gap_connect(const bd_addr_t addr, bd_addr_type_t addr_type); 484 485 /** 486 * @brief Connect with Whitelist 487 * @note Explicit whitelist management and this connect with whitelist replace deprecated gap_auto_connection_* functions 488 * @returns - if ok 489 */ 490 uint8_t gap_connect_with_whitelist(void); 491 492 /** 493 * @brief Cancel connection process initiated by gap_connect 494 */ 495 uint8_t gap_connect_cancel(void); 496 497 /** 498 * @brief Auto Connection Establishment - Start Connecting to device 499 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 500 * @param address_typ 501 * @param address 502 * @returns 0 if ok 503 */ 504 uint8_t gap_auto_connection_start(bd_addr_type_t address_typ, const bd_addr_t address); 505 506 /** 507 * @brief Auto Connection Establishment - Stop Connecting to device 508 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 509 * @param address_typ 510 * @param address 511 * @returns 0 if ok 512 */ 513 uint8_t gap_auto_connection_stop(bd_addr_type_t address_typ, const bd_addr_t address); 514 515 /** 516 * @brief Auto Connection Establishment - Stop everything 517 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 518 * @note Convenience function to stop all active auto connection attempts 519 */ 520 uint8_t gap_auto_connection_stop_all(void); 521 522 /** 523 * @brief Set LE PHY 524 * @param con_handle 525 * @param all_phys 0 = set rx/tx, 1 = set only rx, 2 = set only tx 526 * @param tx_phys 1 = 1M, 2 = 2M, 4 = Coded 527 * @param rx_phys 1 = 1M, 2 = 2M, 4 = Coded 528 * @param phy_options 0 = no preferred coding for Coded, 1 = S=2 coding (500 kbit), 2 = S=8 coding (125 kbit) 529 * @returns 0 if ok 530 */ 531 uint8_t gap_le_set_phy(hci_con_handle_t con_handle, uint8_t all_phys, uint8_t tx_phys, uint8_t rx_phys, uint8_t phy_options); 532 533 /** 534 * @brief Get connection interval 535 * @return connection interval, otherwise 0 if error 536 */ 537 uint16_t gap_le_connection_interval(hci_con_handle_t connection_handle); 538 539 /** 540 * 541 * @brief Get encryption key size. 542 * @param con_handle 543 * @return 0 if not encrypted, 7-16 otherwise 544 */ 545 int gap_encryption_key_size(hci_con_handle_t con_handle); 546 547 /** 548 * @brief Get authentication property. 549 * @param con_handle 550 * @return 1 if bonded with OOB/Passkey (AND MITM protection) 551 */ 552 int gap_authenticated(hci_con_handle_t con_handle); 553 554 /** 555 * @brief Get secure connection property 556 * @param con_handle 557 * @return 1 if bonded usiung LE Secure Connections 558 */ 559 int gap_secure_connection(hci_con_handle_t con_handle); 560 561 /** 562 * @brief Queries authorization state. 563 * @param con_handle 564 * @return authorization_state for the current session 565 */ 566 authorization_state_t gap_authorization_state(hci_con_handle_t con_handle); 567 568 /** 569 * @brief Get bonded property (BR/EDR/LE) 570 * @note LE: has to be called after identity resolving is complete 571 * @param con_handle 572 * @return true if bonded 573 */ 574 bool gap_bonded(hci_con_handle_t con_handle); 575 576 // Classic 577 578 /** 579 * @brief Override page scan mode. Page scan mode enabled by l2cap when services are registered 580 * @note Might be used to reduce power consumption while Bluetooth module stays powered but no (new) 581 * connections are expected 582 */ 583 void gap_connectable_control(uint8_t enable); 584 585 /** 586 * @brief Allows to control if device is discoverable. OFF by default. 587 */ 588 void gap_discoverable_control(uint8_t enable); 589 590 /** 591 * @brief Gets local address. 592 */ 593 void gap_local_bd_addr(bd_addr_t address_buffer); 594 595 /** 596 * @brief Deletes link key for remote device with baseband address. 597 * @param addr 598 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 599 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 600 * power up, this function only works, when the stack is in working state for these ports. 601 */ 602 void gap_drop_link_key_for_bd_addr(bd_addr_t addr); 603 604 /** 605 * @brief Delete all stored link keys 606 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 607 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 608 * power up, this function only works, when the stack is in working state for these ports. 609 */ 610 void gap_delete_all_link_keys(void); 611 612 /** 613 * @brief Store link key for remote device with baseband address 614 * @param addr 615 * @param link_key 616 * @param link_key_type 617 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 618 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 619 * power up, this function only works, when the stack is in working state for these ports. 620 */ 621 void gap_store_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t type); 622 623 /** 624 * @brief Get link for remote device with basband address 625 * @param addr 626 * @param link_key (out) is stored here 627 * @param link_key_type (out) is stored here 628 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 629 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 630 * power up, this function only works, when the stack is in working state for these ports. 631 */ 632 bool gap_get_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t * type); 633 634 /** 635 * @brief Setup Link Key iterator 636 * @param it 637 * @returns 1 on success 638 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 639 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 640 * power up, this function only works, when the stack is in working state for these ports. 641 */ 642 int gap_link_key_iterator_init(btstack_link_key_iterator_t * it); 643 644 /** 645 * @brief Get next Link Key 646 * @param it 647 * @brief addr 648 * @brief link_key 649 * @brief type of link key 650 * @returns 1, if valid link key found 651 * @see note on gap_link_key_iterator_init 652 */ 653 int gap_link_key_iterator_get_next(btstack_link_key_iterator_t * it, bd_addr_t bd_addr, link_key_t link_key, link_key_type_t * type); 654 655 /** 656 * @brief Frees resources allocated by iterator_init 657 * @note Must be called after iteration to free resources 658 * @param it 659 * @see note on gap_link_key_iterator_init 660 */ 661 void gap_link_key_iterator_done(btstack_link_key_iterator_t * it); 662 663 /** 664 * @brief Start GAP Classic Inquiry 665 * @param duration in 1.28s units 666 * @return 0 if ok 667 * @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE 668 */ 669 int gap_inquiry_start(uint8_t duration_in_1280ms_units); 670 671 /** 672 * @brief Stop GAP Classic Inquiry 673 * @brief Stop GAP Classic Inquiry 674 * @returns 0 if ok 675 * @events: GAP_EVENT_INQUIRY_COMPLETE 676 */ 677 int gap_inquiry_stop(void); 678 679 /** 680 * @brief Remote Name Request 681 * @param addr 682 * @param page_scan_repetition_mode 683 * @param clock_offset only used when bit 15 is set - pass 0 if not known 684 * @events: HCI_EVENT_REMOTE_NAME_REQUEST_COMPLETE 685 */ 686 int gap_remote_name_request(const bd_addr_t addr, uint8_t page_scan_repetition_mode, uint16_t clock_offset); 687 688 /** 689 * @brief Read RSSI 690 * @param con_handle 691 * @events: GAP_EVENT_RSSI_MEASUREMENT 692 */ 693 int gap_read_rssi(hci_con_handle_t con_handle); 694 695 /** 696 * @brief Legacy Pairing Pin Code Response 697 * @note data is not copied, pointer has to stay valid 698 * @param addr 699 * @param pin 700 * @return 0 if ok 701 */ 702 int gap_pin_code_response(const bd_addr_t addr, const char * pin); 703 704 /** 705 * @brief Legacy Pairing Pin Code Response for binary data / non-strings 706 * @note data is not copied, pointer has to stay valid 707 * @param addr 708 * @param pin_data 709 * @param pin_len 710 * @return 0 if ok 711 */ 712 int gap_pin_code_response_binary(const bd_addr_t addr, const uint8_t * pin_data, uint8_t pin_len); 713 714 /** 715 * @brief Abort Legacy Pairing 716 * @param addr 717 * @param pin 718 * @return 0 if ok 719 */ 720 int gap_pin_code_negative(bd_addr_t addr); 721 722 /** 723 * @brief SSP Passkey Response 724 * @param addr 725 * @param passkey [0..999999] 726 * @return 0 if ok 727 */ 728 int gap_ssp_passkey_response(const bd_addr_t addr, uint32_t passkey); 729 730 /** 731 * @brief Abort SSP Passkey Entry/Pairing 732 * @param addr 733 * @param pin 734 * @return 0 if ok 735 */ 736 int gap_ssp_passkey_negative(const bd_addr_t addr); 737 738 /** 739 * @brief Accept SSP Numeric Comparison 740 * @param addr 741 * @param passkey 742 * @return 0 if ok 743 */ 744 int gap_ssp_confirmation_response(const bd_addr_t addr); 745 746 /** 747 * @brief Abort SSP Numeric Comparison/Pairing 748 * @param addr 749 * @param pin 750 * @return 0 if ok 751 */ 752 int gap_ssp_confirmation_negative(const bd_addr_t addr); 753 754 /** 755 * @brief Generate new OOB data 756 * @note OOB data will be provided in GAP_EVENT_LOCAL_OOB_DATA and be used in future pairing procedures 757 */ 758 void gap_ssp_generate_oob_data(void); 759 760 /** 761 * @brief Report Remote OOB Data 762 * @param bd_addr 763 * @param c_192 Simple Pairing Hash C derived from P-192 public key 764 * @param r_192 Simple Pairing Randomizer derived from P-192 public key 765 * @param c_256 Simple Pairing Hash C derived from P-256 public key 766 * @param r_256 Simple Pairing Randomizer derived from P-256 public key 767 */ 768 uint8_t gap_ssp_remote_oob_data(const bd_addr_t addr, const uint8_t * c_192, const uint8_t * r_192, const uint8_t * c_256, const uint8_t * r_256); 769 770 /** 771 * Send SSP IO Capabilities Reply 772 * @note IO Capabilities (Negative) Reply is sent automatically unless ENABLE_EXPLICIT_IO_CAPABILITIES_REPLY 773 * @param addr 774 * @return 0 if ok 775 */ 776 uint8_t gap_ssp_io_capabilities_response(const bd_addr_t addr); 777 778 /** 779 * Send SSP IO Capabilities Negative Reply 780 * @note IO Capabilities (Negative) Reply is sent automatically unless ENABLE_EXPLICIT_IO_CAPABILITIES_REPLY 781 * @param addr 782 * @return 0 if ok 783 */ 784 uint8_t gap_ssp_io_capabilities_negative(const bd_addr_t addr); 785 786 /** 787 * @brief Enter Sniff mode 788 * @param con_handle 789 * @param sniff_min_interval range: 0x0002 to 0xFFFE; only even values are valid, Time = N * 0.625 ms 790 * @param sniff_max_interval range: 0x0002 to 0xFFFE; only even values are valid, Time = N * 0.625 ms 791 * @param sniff_attempt Number of Baseband receive slots for sniff attempt. 792 * @param sniff_timeout Number of Baseband receive slots for sniff timeout. 793 @ @return 0 if ok 794 */ 795 uint8_t gap_sniff_mode_enter(hci_con_handle_t con_handle, uint16_t sniff_min_interval, uint16_t sniff_max_interval, uint16_t sniff_attempt, uint16_t sniff_timeout); 796 797 /** 798 * @brief Exit Sniff mode 799 * @param con_handle 800 @ @return 0 if ok 801 */ 802 uint8_t gap_sniff_mode_exit(hci_con_handle_t con_handle); 803 804 // LE 805 806 /** 807 * @brief Get own addr type and address used for LE 808 */ 809 void gap_le_get_own_address(uint8_t * addr_type, bd_addr_t addr); 810 811 812 /** 813 * @brief Get state of connection re-encryption for bonded devices when in central role 814 * @note used by gatt_client and att_server to wait for re-encryption 815 * @param con_handle 816 * @return 1 if security setup is active 817 */ 818 int gap_reconnect_security_setup_active(hci_con_handle_t con_handle); 819 820 /** 821 * @brief Delete bonding information for remote device 822 * @note On most desktop ports, the LE Device DB uses a TLV and there is one TLV storage per 823 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 824 * power up, this function only works, when the stack is in working state for these ports. 825 * @param address_type 826 * @param address 827 */ 828 void gap_delete_bonding(bd_addr_type_t address_type, bd_addr_t address); 829 830 /** 831 * LE Privacy 1.2 - requires support by Controller and ENABLE_LE_RESOLVING_LIST to be defined 832 */ 833 834 /** 835 * @brief Load LE Device DB entries into Controller Resolving List to allow filtering on 836 * bonded devies with resolvable private addresses 837 * @return EROOR_CODE_SUCCESS if supported by Controller 838 */ 839 uint8_t gap_load_resolving_list_from_le_device_db(void); 840 841 /** 842 * @brief Get local persistent IRK 843 */ 844 const uint8_t * gap_get_persistent_irk(void); 845 846 /* API_END*/ 847 848 #if defined __cplusplus 849 } 850 #endif 851 852 #endif // GAP_H 853