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