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