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 // BIG has up to 2 BIS (stereo) 58 #ifndef MAX_NR_BIS 59 #define MAX_NR_BIS 2 60 #endif 61 62 // CIG usually has up to 2 CIS (stereo) 63 #ifndef MAX_NR_CIS 64 #define MAX_NR_CIS 2 65 #endif 66 67 typedef enum { 68 69 // MITM protection not required 70 // No encryption required 71 // No user interaction required 72 LEVEL_0 = 0, 73 74 // MITM protection not required 75 // No encryption required 76 // Minimal user interaction desired 77 LEVEL_1, 78 79 // MITM protection not required 80 // Encryption required 81 LEVEL_2, 82 83 // MITM protection required 84 // Encryption required 85 // User interaction acceptable 86 LEVEL_3, 87 88 // MITM protection required 89 // Encryption required 90 // 128-bit equivalent strength for link and encryption keys required (P-192 is not enough) 91 // User interaction acceptable 92 LEVEL_4, 93 } gap_security_level_t; 94 95 96 typedef enum { 97 // non-secure 98 GAP_SECURITY_MODE_1 = 1, 99 100 // service level enforced security 101 GAP_SECURITY_MODE_2, 102 103 // link level enforced security 104 GAP_SECURITY_MODE_3, 105 106 // service level enforced security 107 GAP_SECURITY_MODE_4 108 } gap_security_mode_t; 109 110 typedef enum { 111 GAP_SECURITY_NONE, 112 GAP_SECURITY_ENCRYPTED, // SSP: JUST WORKS 113 GAP_SECURITY_AUTHENTICATED, // SSP: numeric comparison, passkey, OOB 114 // GAP_SECURITY_AUTHORIZED 115 } gap_security_state; 116 117 typedef enum { 118 GAP_CONNECTION_INVALID, 119 GAP_CONNECTION_ACL, 120 GAP_CONNECTION_SCO, 121 GAP_CONNECTION_LE 122 } gap_connection_type_t; 123 124 typedef struct le_connection_parameter_range{ 125 uint16_t le_conn_interval_min; 126 uint16_t le_conn_interval_max; 127 uint16_t le_conn_latency_min; 128 uint16_t le_conn_latency_max; 129 uint16_t le_supervision_timeout_min; 130 uint16_t le_supervision_timeout_max; 131 } le_connection_parameter_range_t; 132 133 typedef enum { 134 GAP_RANDOM_ADDRESS_TYPE_OFF = 0, 135 GAP_RANDOM_ADDRESS_TYPE_STATIC, 136 GAP_RANDOM_ADDRESS_NON_RESOLVABLE, 137 GAP_RANDOM_ADDRESS_RESOLVABLE, 138 } gap_random_address_type_t; 139 140 // Authorization state 141 typedef enum { 142 AUTHORIZATION_UNKNOWN, 143 AUTHORIZATION_PENDING, 144 AUTHORIZATION_DECLINED, 145 AUTHORIZATION_GRANTED 146 } authorization_state_t; 147 148 // Extended Advertising Parameters 149 typedef struct { 150 uint16_t advertising_event_properties; 151 uint16_t primary_advertising_interval_min; 152 uint16_t primary_advertising_interval_max; 153 uint8_t primary_advertising_channel_map; 154 bd_addr_type_t own_address_type; 155 bd_addr_type_t peer_address_type; 156 bd_addr_t peer_address; 157 uint8_t advertising_filter_policy; 158 int8_t advertising_tx_power; 159 uint8_t primary_advertising_phy; 160 uint8_t secondary_advertising_max_skip; 161 uint8_t secondary_advertising_phy; 162 uint8_t advertising_sid; 163 uint8_t scan_request_notification_enable; 164 } le_extended_advertising_parameters_t; 165 166 typedef struct { 167 uint16_t periodic_advertising_interval_min; 168 uint16_t periodic_advertising_interval_max; 169 uint16_t periodic_advertising_properties; 170 } le_periodic_advertising_parameters_t; 171 172 // Extended Advertising Set State 173 typedef struct { 174 btstack_linked_item_t item; 175 le_extended_advertising_parameters_t extended_params; 176 le_periodic_advertising_parameters_t periodic_params; 177 bd_addr_t random_address; 178 const uint8_t * adv_data; 179 const uint8_t * scan_data; 180 const uint8_t * periodic_data; 181 uint16_t adv_data_len; 182 uint16_t scan_data_len; 183 uint16_t periodic_data_len; 184 uint16_t adv_data_pos; 185 uint16_t scan_data_pos; 186 uint16_t periodic_data_pos; 187 uint16_t enable_timeout; 188 uint8_t advertising_handle; 189 uint8_t enable_max_scan_events; 190 bool periodic_include_adi; 191 uint8_t state; 192 uint8_t tasks; 193 } le_advertising_set_t; 194 195 // Isochronous Streams 196 197 // -- Broadcast Isochronous Group BIG 198 199 typedef struct { 200 uint8_t big_handle; 201 uint8_t advertising_handle; 202 uint8_t num_bis; 203 uint32_t sdu_interval_us; 204 uint16_t max_sdu; 205 uint16_t max_transport_latency_ms; 206 uint8_t rtn; 207 uint8_t phy; 208 uint8_t packing; 209 uint8_t framing; 210 uint8_t encryption; 211 uint8_t broadcast_code[16]; 212 } le_audio_big_params_t; 213 214 typedef struct { 215 uint8_t big_handle; 216 uint8_t sync_handle; 217 uint8_t encryption; 218 uint8_t broadcast_code[16]; 219 uint8_t mse; 220 uint16_t big_sync_timeout_10ms; 221 uint8_t num_bis; 222 uint8_t bis_indices[MAX_NR_BIS]; 223 } le_audio_big_sync_params_t; 224 225 typedef enum { 226 LE_AUDIO_BIG_STATE_CREATE, 227 LE_AUDIO_BIG_STATE_W4_ESTABLISHED, 228 LE_AUDIO_BIG_STATE_SETUP_ISO_PATH, 229 LE_AUDIO_BIG_STATE_W4_SETUP_ISO_PATH, 230 LE_AUDIO_BIG_STATE_W4_SETUP_ISO_PATH_THEN_TERMINATE, 231 LE_AUDIO_BIG_STATE_SETUP_ISO_PATHS_FAILED, 232 LE_AUDIO_BIG_STATE_ACTIVE, 233 LE_AUDIO_BIG_STATE_TERMINATE, 234 LE_AUDIO_BIG_STATE_W4_TERMINATED_AFTER_SETUP_FAILED, 235 LE_AUDIO_BIG_STATE_W4_TERMINATED, 236 } le_audio_big_state_t; 237 238 typedef struct { 239 btstack_linked_item_t item; 240 uint8_t big_handle; 241 le_audio_big_state_t state; 242 union { 243 uint8_t next_bis; 244 uint8_t status; 245 } state_vars; 246 uint8_t num_bis; 247 hci_con_handle_t bis_con_handles[MAX_NR_BIS]; 248 const le_audio_big_params_t * params; 249 // request to send 250 bool can_send_now_requested; 251 // previous and current timestamp of number completed event to track ISO intervals 252 bool num_completed_timestamp_previous_valid; 253 bool num_completed_timestamp_current_valid; 254 uint32_t num_completed_timestamp_previous_ms; 255 uint32_t num_completed_timestamp_current_ms; 256 257 } le_audio_big_t; 258 259 typedef struct { 260 btstack_linked_item_t item; 261 uint8_t big_handle; 262 le_audio_big_state_t state; 263 union { 264 uint8_t next_bis; 265 uint8_t status; 266 } state_vars; 267 uint8_t num_bis; 268 hci_con_handle_t bis_con_handles[MAX_NR_BIS]; 269 const le_audio_big_sync_params_t * params; 270 } le_audio_big_sync_t; 271 272 // -- Connected Isochronuous Group CIG 273 274 typedef enum { 275 LE_AUDIO_CIG_STATE_CREATE, 276 LE_AUDIO_CIG_STATE_W4_ESTABLISHED, 277 LE_AUDIO_CIG_STATE_W4_CIS_REQUEST, 278 LE_AUDIO_CIG_STATE_CREATE_CIS, 279 LE_AUDIO_CIG_STATE_W4_CREATE_CIS, 280 LE_AUDIO_CIG_STATE_SETUP_ISO_PATH, 281 LE_AUDIO_CIG_STATE_W4_SETUP_ISO_PATH, 282 LE_AUDIO_CIG_STATE_ACTIVE, 283 LE_AUDIO_CIG_STATE_REMOVE, 284 } le_audio_cig_state_t; 285 286 typedef struct { 287 uint8_t cis_id; 288 uint16_t max_sdu_c_to_p; 289 uint16_t max_sdu_p_to_c; 290 uint8_t phy_c_to_p; 291 uint8_t phy_p_to_c; 292 uint8_t rtn_c_to_p; 293 uint8_t rtn_p_to_c; 294 } le_audio_cis_params_t; 295 296 typedef struct { 297 uint8_t cig_id; 298 uint32_t sdu_interval_c_to_p; 299 uint32_t sdu_interval_p_to_c; 300 uint8_t worst_case_sca; 301 uint8_t packing; 302 uint8_t framing; 303 uint16_t max_transport_latency_c_to_p; 304 uint16_t max_transport_latency_p_to_c; 305 uint8_t num_cis; 306 le_audio_cis_params_t cis_params[MAX_NR_CIS]; 307 } le_audio_cig_params_t; 308 309 typedef struct { 310 btstack_linked_item_t item; 311 uint8_t cig_id; 312 le_audio_cig_params_t * params; 313 le_audio_cig_state_t state; 314 union { 315 uint8_t next_cis; 316 uint8_t status; 317 } state_vars; 318 uint8_t num_cis; 319 hci_con_handle_t cis_con_handles[MAX_NR_CIS]; 320 hci_con_handle_t acl_con_handles[MAX_NR_CIS]; 321 bool cis_setup_active[MAX_NR_CIS]; 322 bool cis_established[MAX_NR_CIS]; 323 // request to send 324 bool can_send_now_requested; 325 } le_audio_cig_t; 326 327 /* API_START */ 328 329 // Classic + LE 330 331 /** 332 * @brief Read RSSI 333 * @param con_handle 334 * @events: GAP_EVENT_RSSI_MEASUREMENT 335 */ 336 int gap_read_rssi(hci_con_handle_t con_handle); 337 338 339 /** 340 * @brief Gets local address. 341 */ 342 void gap_local_bd_addr(bd_addr_t address_buffer); 343 344 /** 345 * @brief Disconnect connection with handle 346 * @param handle 347 * @return status 348 */ 349 uint8_t gap_disconnect(hci_con_handle_t handle); 350 351 /** 352 * @brief Get connection type 353 * @param con_handle 354 * @result connection_type 355 */ 356 gap_connection_type_t gap_get_connection_type(hci_con_handle_t connection_handle); 357 358 /** 359 * @brief Get HCI connection role 360 * @param con_handle 361 * @result hci_role_t HCI_ROLE_MASTER / HCI_ROLE_SLAVE / HCI_ROLE_INVALID (if connection does not exist) 362 */ 363 hci_role_t gap_get_role(hci_con_handle_t connection_handle); 364 365 // Classic 366 367 /** 368 * @brief Request role switch 369 * @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 370 * @param addr 371 * @param hci_role_t HCI_ROLE_MASTER / HCI_ROLE_SLAVE 372 * @result status 373 */ 374 uint8_t gap_request_role(const bd_addr_t addr, hci_role_t role); 375 376 /** 377 * @brief Sets local name. 378 * @note Default name is 'BTstack 00:00:00:00:00:00' 379 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 380 * @param name is not copied, make sure memory stays valid 381 */ 382 void gap_set_local_name(const char * local_name); 383 384 /** 385 * @brief Set Extended Inquiry Response data 386 * @note If not set, local name will be used for EIR data (see gap_set_local_name) 387 * @note '00:00:00:00:00:00' in local_name will be replaced with actual bd addr 388 * @param eir_data size HCI_EXTENDED_INQUIRY_RESPONSE_DATA_LEN (240) bytes, is not copied make sure memory stays valid 389 */ 390 void gap_set_extended_inquiry_response(const uint8_t * data); 391 392 /** 393 * @brief Set class of device 394 */ 395 void gap_set_class_of_device(uint32_t class_of_device); 396 397 /** 398 * @brief Set default link policy settings for all classic ACL links 399 * @param default_link_policy_settings - see LM_LINK_POLICY_* in bluetooth.h 400 * @note common value: LM_LINK_POLICY_ENABLE_ROLE_SWITCH | LM_LINK_POLICY_ENABLE_SNIFF_MODE to enable role switch and sniff mode 401 */ 402 void gap_set_default_link_policy_settings(uint16_t default_link_policy_settings); 403 404 /** 405 * @brief Set Allow Role Switch param for outgoing classic ACL links 406 * @param allow_role_switch - true: allow remote device to request role switch, false: stay master 407 */ 408 void gap_set_allow_role_switch(bool allow_role_switch); 409 410 /** 411 * @brief Set link supervision timeout for outgoing classic ACL links 412 * @param default_link_supervision_timeout * 0.625 ms, default 0x7d00 = 20 seconds, 0 = no link supervision timeout 413 */ 414 void gap_set_link_supervision_timeout(uint16_t link_supervision_timeout); 415 416 /** 417 * @brief Enable link watchdog. If no ACL packet is sent within timeout_ms, the link will get disconnected 418 * note: current implementation uses the automatic flush timeout controller feature with a max timeout of 1.28s 419 * @param timeout_ms 420 */ 421 void gap_enable_link_watchdog(uint16_t timeout_ms); 422 423 /** 424 * @brief Enable/disable bonding. Default is enabled. 425 * @param enabled 426 */ 427 void gap_set_bondable_mode(int enabled); 428 429 /** 430 * @brief Get bondable mode. 431 * @return 1 if bondable 432 */ 433 int gap_get_bondable_mode(void); 434 435 /** 436 * @brief Set security mode for all outgoing and incoming connections. Default: GAP_SECURITY_MODE_4 437 * @param security_mode is GAP_SECURITY_MODE_2 or GAP_SECURITY_MODE_4 438 * @return status ERROR_CODE_SUCCESS or ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE 439 */ 440 uint8_t gap_set_security_mode(gap_security_mode_t security_mode); 441 442 /** 443 * @brief Get security mode 444 * @return security_mode 445 */ 446 gap_security_mode_t gap_get_security_mode(void); 447 448 /** 449 * @brief Set security level for all outgoing and incoming connections. Default: LEVEL_2 450 * @param security_level 451 * @note has to be called before services or profiles are initialized 452 */ 453 void gap_set_security_level(gap_security_level_t security_level); 454 455 /** 456 * @brief Get security level 457 * @return security_level 458 */ 459 gap_security_level_t gap_get_security_level(void); 460 461 /** 462 * @brief Set Secure Connections Only Mode for BR/EDR (Classic) Default: false 463 * @param enable 464 */ 465 void gap_set_secure_connections_only_mode(bool enable); 466 467 /** 468 * @breif Get Secure Connections Only Mode 469 * @param enabled 470 */ 471 bool gap_get_secure_connections_only_mode(void); 472 473 /** 474 * @brief Set minimal security level for registered services 475 * @param security_level 476 * @note Called by L2CAP based on registered services 477 */ 478 void gap_set_minimal_service_security_level(gap_security_level_t security_level); 479 480 /** 481 * @brief Register filter for rejecting classic connections. Callback will return 1 accept connection, 0 on reject. 482 */ 483 void gap_register_classic_connection_filter(int (*accept_callback)(bd_addr_t addr, hci_link_type_t link_type)); 484 485 /* Configure Secure Simple Pairing */ 486 487 /** 488 * @brief Enable will enable SSP during init. Default: true 489 */ 490 void gap_ssp_set_enable(int enable); 491 492 /** 493 * @brief Set IO Capability. BTstack will return capability to SSP requests 494 */ 495 void gap_ssp_set_io_capability(int ssp_io_capability); 496 497 /** 498 * @brief Set Authentication Requirements using during SSP 499 */ 500 void gap_ssp_set_authentication_requirement(int authentication_requirement); 501 502 /** 503 * @brief Enable/disable Secure Connections. Default: true if supported by Controller 504 */ 505 void gap_secure_connections_enable(bool enable); 506 507 /** 508 * @brief Query if Secure Connections can be used for Classic connections. 509 * @note Requires gap_secure_connections_enable == true and Controller to support it 510 */ 511 bool gap_secure_connections_active(void); 512 513 /** 514 * @brief If set, BTstack will confirm a numeric comparison and enter '000000' if requested. 515 */ 516 void gap_ssp_set_auto_accept(int auto_accept); 517 518 /** 519 * @brief Set required encryption key size for GAP Levels 1-3 on classic connections. 520 * @note If you need to reduce the required encryption key size, please consider enabling 521 * ENABLE_MUTUAL_AUTHENTICATION_FOR_LEGACY_SECURE_CONNECTIONS to prevent BIAS attacks. 522 * However, the re-authentication for Legacy Secure Connections can cause a link loss 523 * in some Controller combinations. 524 * @param encryption_key_size in bytes. Valid 7..16, default: 16 525 */ 526 void gap_set_required_encryption_key_size(uint8_t encryption_key_size); 527 528 /** 529 * @brief Start dedicated bonding with device. Disconnect after bonding. 530 * @param device 531 * @param request MITM protection 532 * @return error, if max num acl connections active 533 * @result GAP_DEDICATED_BONDING_COMPLETE 534 */ 535 int gap_dedicated_bonding(bd_addr_t device, int mitm_protection_required); 536 537 gap_security_level_t gap_security_level_for_link_key_type(link_key_type_t link_key_type); 538 539 /** 540 * @brief map link keys to secure connection yes/no 541 */ 542 bool gap_secure_connection_for_link_key_type(link_key_type_t link_key_type); 543 544 /** 545 * @brief map link keys to authenticated 546 */ 547 bool gap_authenticated_for_link_key_type(link_key_type_t link_key_type); 548 549 gap_security_level_t gap_security_level(hci_con_handle_t con_handle); 550 551 void gap_request_security_level(hci_con_handle_t con_handle, gap_security_level_t level); 552 553 bool gap_mitm_protection_required_for_security_level(gap_security_level_t level); 554 555 /** 556 * @brief Set Page Scan Type 557 * @param page_scan_interval * 0.625 ms, range: 0x0012..0x1000, default: 0x0800 558 * @param page_scan_windows * 0.625 ms, range: 0x0011..page_scan_interval, default: 0x0012 559 */ 560 void gap_set_page_scan_activity(uint16_t page_scan_interval, uint16_t page_scan_window); 561 562 /** 563 * @brief Set Page Scan Type 564 * @param page_scan_mode 565 */ 566 void gap_set_page_scan_type(page_scan_type_t page_scan_type); 567 568 /** 569 * @brief Set Page Timeout 570 * @param page_timeout * 0.625 ms, range: 0x0001..0xffff, default: 0x6000 (ca 15 seconds) 571 */ 572 void gap_set_page_timeout(uint16_t page_timeout); 573 574 // LE 575 576 /** 577 * @brief Set parameters for LE Scan 578 * @param scan_type 0 = passive, 1 = active 579 * @param scan_interval range 0x0004..0x4000, unit 0.625 ms 580 * @param scan_window range 0x0004..0x4000, unit 0.625 ms 581 * @param scanning_filter_policy 0 = all devices, 1 = all from whitelist 582 */ 583 void gap_set_scan_params(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window, uint8_t scanning_filter_policy); 584 585 /** 586 * @brief Set parameters for LE Scan 587 * @deprecated Use gap_set_scan_params instead 588 */ 589 void gap_set_scan_parameters(uint8_t scan_type, uint16_t scan_interval, uint16_t scan_window); 590 591 /** 592 * @brief Set duplicate filter for LE Scan 593 * @param enabled if enabled, only one advertisements per BD_ADDR is reported, default: false 594 */ 595 void gap_set_scan_duplicate_filter(bool enabled); 596 597 /** 598 * @brief Set PHYs for LE Scan 599 * @param phy bitmask: 1 = LE 1M PHY, 4 = LE Coded PHY 600 */ 601 void gap_set_scan_phys(uint8_t phys); 602 603 /** 604 * @brief Start LE Scan 605 */ 606 void gap_start_scan(void); 607 608 /** 609 * @brief Stop LE Scan 610 */ 611 void gap_stop_scan(void); 612 613 /** 614 * @brief Enable privacy by using random addresses 615 * @param random_address_type to use (incl. OFF) 616 */ 617 void gap_random_address_set_mode(gap_random_address_type_t random_address_type); 618 619 /** 620 * @brief Get privacy mode 621 */ 622 gap_random_address_type_t gap_random_address_get_mode(void); 623 624 /** 625 * @brief Sets update period for random address 626 * @param period_ms in ms 627 */ 628 void gap_random_address_set_update_period(int period_ms); 629 630 /** 631 * @brief Sets a fixed random address for advertising 632 * @param addr 633 * @note Sets random address mode to type static 634 */ 635 void gap_random_address_set(const bd_addr_t addr); 636 637 /** 638 * @brief Set Advertisement Data 639 * @param advertising_data_length 640 * @param advertising_data (max 31 octets) 641 * @note data is not copied, pointer has to stay valid 642 * @note '00:00:00:00:00:00' in advertising_data will be replaced with actual bd addr 643 */ 644 void gap_advertisements_set_data(uint8_t advertising_data_length, uint8_t * advertising_data); 645 646 /** 647 * @brief Set Advertisement Parameters 648 * @param adv_int_min 649 * @param adv_int_max 650 * @param adv_type 651 * @param direct_address_type 652 * @param direct_address 653 * @param channel_map 654 * @param filter_policy 655 * @note own_address_type is used from gap_random_address_set_mode 656 */ 657 void gap_advertisements_set_params(uint16_t adv_int_min, uint16_t adv_int_max, uint8_t adv_type, 658 uint8_t direct_address_typ, bd_addr_t direct_address, uint8_t channel_map, uint8_t filter_policy); 659 660 /** 661 * @brief Enable/Disable Advertisements. OFF by default. 662 * @param enabled 663 */ 664 void gap_advertisements_enable(int enabled); 665 666 /** 667 * @brief Set Scan Response Data 668 * 669 * @note For scan response data, scannable undirected advertising (ADV_SCAN_IND) need to be used 670 * 671 * @param advertising_data_length 672 * @param advertising_data (max 31 octets) 673 * @note data is not copied, pointer has to stay valid 674 * @note '00:00:00:00:00:00' in scan_response_data will be replaced with actual bd addr 675 */ 676 void gap_scan_response_set_data(uint8_t scan_response_data_length, uint8_t * scan_response_data); 677 678 679 /** 680 * @brief Set update interval for resolvable private addresses generated by the Controller 681 * @param update_s timeout for updates in seconds 682 * @return status 683 */ 684 uint8_t gap_extended_advertising_set_resolvable_private_address_update(uint16_t update_s); 685 686 /** 687 * @brief Provide storage for new advertising set and setup on Controller 688 * @note Using RPA as own_address_type requires ENABLE_LE_ENHANCED_CONNECTION_COMPLETE_EVENT is required for pairing 689 * @param storage to use by stack, needs to stay valid until adv set is removed with gap_extended_advertising_remove 690 * @param advertising_parameters 691 * @param out_advertising_handle to use with other adv config commands 692 * @return status 693 * @events: GAP_SUBEVENT_ADVERTISING_SET_INSTALLED 694 */ 695 uint8_t gap_extended_advertising_setup(le_advertising_set_t * storage, const le_extended_advertising_parameters_t * advertising_parameters, uint8_t * out_advertising_handle); 696 697 /** 698 * @param Set advertising params for advertising set 699 * @note Using RPA as own_address_type requires ENABLE_LE_ENHANCED_CONNECTION_COMPLETE_EVENT is required for pairing 700 * @param advertising_handle 701 * @param advertising_parameters 702 * @return status 703 */ 704 uint8_t gap_extended_advertising_set_params(uint8_t advertising_handle, const le_extended_advertising_parameters_t * advertising_parameters); 705 706 /** 707 * @param Get advertising params for advertising set, e.g. to update params 708 * @param advertising_handle 709 * @param advertising_parameters 710 * @return status 711 */ 712 uint8_t gap_extended_advertising_get_params(uint8_t advertising_handle, le_extended_advertising_parameters_t * advertising_parameters); 713 714 /** 715 * @param Set periodic advertising params for advertising set 716 * @param advertising_handle 717 * @param advertising_parameters 718 * @return status 719 */ 720 uint8_t gap_periodic_advertising_set_params(uint8_t advertising_handle, const le_periodic_advertising_parameters_t * advertising_parameters); 721 722 /** 723 * @param Get params for periodic advertising set, e.g. to update params 724 * @param advertising_handle 725 * @param advertising_parameters 726 * @return status 727 */ 728 uint8_t gap_periodic_advertising_get_params(uint8_t advertising_handle, le_periodic_advertising_parameters_t * advertising_parameters); 729 730 /** 731 * @param Set random addrress for advertising set 732 * @param advertising_handle 733 * @param random_address 734 * @return status 735 */ 736 uint8_t gap_extended_advertising_set_random_address(uint8_t advertising_handle, bd_addr_t random_address); 737 738 /** 739 * @brief Set Advertising Data for a advertisement set 740 * @param advertising_handle 741 * @param advertising_data_length 742 * @param advertising_data 743 * @return status 744 */ 745 uint8_t gap_extended_advertising_set_adv_data(uint8_t advertising_handle, uint16_t advertising_data_length, const uint8_t * advertising_data); 746 747 /** 748 * @brief Set Scan Response Data for a advertisement set 749 * @param advertising_handle 750 * @param scan_response_data_length 751 * @param scan_response_data 752 * @return status 753 */ 754 uint8_t gap_extended_advertising_set_scan_response_data(uint8_t advertising_handle, uint16_t scan_response_data_length, const uint8_t * scan_response_data); 755 756 /** 757 * @brief Set data for periodic advertisement set 758 * @param advertising_handle 759 * @param periodic_data_length 760 * @param periodic_data 761 * @return status 762 */ 763 uint8_t gap_periodic_advertising_set_data(uint8_t advertising_handle, uint16_t periodic_data_length, const uint8_t * periodic_data); 764 765 /** 766 * @brief Start advertising advertising set 767 * @param advertising_handle 768 * @param timeout in 10ms, or 0 == no timeout 769 * @param num_extended_advertising_events Controller shall send, or 0 == no max number 770 * @return status 771 */ 772 uint8_t gap_extended_advertising_start(uint8_t advertising_handle, uint16_t timeout, uint8_t num_extended_advertising_events); 773 774 /** 775 * @brief Stop advertising 776 * @param advertising_handle 777 * @return status 778 */ 779 uint8_t gap_extended_advertising_stop(uint8_t advertising_handle); 780 781 /** 782 * @brief Start periodic advertising for given advertising set 783 * @param advertising_handle 784 * @param include_adi 785 * @return status 786 */ 787 uint8_t gap_periodic_advertising_start(uint8_t advertising_handle, bool include_adi); 788 789 /** 790 * @brief Stop periodic advertising for given advertising set 791 * @param advertising_handle 792 * @return status 793 */ 794 uint8_t gap_periodic_advertising_stop(uint8_t advertising_handle); 795 796 /** 797 * @brief Set Default Periodic Advertising Sync Transfer Parameters 798 * @note The parameters are used for all subsequent connections over the LE transport. 799 * If mode != 0, an HCI_LE_Periodic_Advertising_Sync_Transfer_Received event will be emitted by the Controller 800 * @param mode 0 = ignore (default), 1 = periodic advertising events disabled 801 * 2 = periodic advertising events enabled with duplicate filtering 802 * 3 = periodic advertising events enabled with duplicate filtering 803 * @param skip The number of periodic advertising packets that can be skipped after a successful receive 804 * @param sync_timeout Range: 0x000A to 0x4000, Time = N*10 ms, Time Range: 100 ms to 163.84 s 805 * @param cte_type bit 0 = Do not sync to packets with an AoA Constant Tone Extension 806 * bit 1 = Do not sync to packets with an AoD Constant Tone Extension with 1 μs slots 807 * bit 2 = Do not sync to packets with an AoD Constant Tone Extension with 2 μs slots 808 * bit 3 = Do not sync to packets without a Constant Tone Extension 809 * @return status 810 */ 811 uint8_t gap_periodic_advertising_sync_transfer_set_default_parameters(uint8_t mode, uint16_t skip, uint16_t sync_timeout, uint8_t cte_type); 812 813 /** 814 * @brief Send Periodic Advertising Sync Transfer to connected device 815 * @param con_handle of connected device 816 * @param service_data 16-bit data to transfer to remote host 817 * @param sync_handle of synchronized periodic advertising train to transfer 818 * @return status 819 */ 820 uint8_t gap_periodic_advertising_sync_transfer_send(hci_con_handle_t con_handle, uint16_t service_data, hci_con_handle_t sync_handle); 821 822 /** 823 * @brief Send Periodic Advertising Set Info Transfer to connected device 824 * @param con_handle of connected device 825 * @param service_data 16-bit data to transfer to remote host 826 * @param advertising_handle of local periodic advertising train to transfer 827 * @return status 828 */ 829 uint8_t gap_periodic_advertising_set_info_transfer_send(hci_con_handle_t con_handle, uint16_t service_data, uint8_t advertising_handle); 830 831 /** 832 * @brief Remove advertising set from Controller 833 * @param advertising_handle 834 * @return status 835 * @events GAP_SUBEVENT_ADVERTISING_SET_REMOVED 836 */ 837 uint8_t gap_extended_advertising_remove(uint8_t advertising_handle); 838 839 /** 840 * @brief Create Broadcast Isochronous Group (BIG) 841 * @param storage to use by stack, needs to stay valid until adv set is removed with gap_big_terminate 842 * @param big_params 843 * @return status 844 * @events GAP_SUBEVENT_BIG_CREATED unless interrupted by call to gap_big_terminate 845 */ 846 uint8_t gap_big_create(le_audio_big_t * storage, le_audio_big_params_t * big_params); 847 848 /** 849 * @brief Terminate Broadcast Isochronous Group (BIG) 850 * @param big_handle 851 * @return status 852 * @events GAP_SUBEVENT_BIG_TERMINATED 853 */ 854 uint8_t gap_big_terminate(uint8_t big_handle); 855 856 /** 857 * @brief Synchronize to Broadcast Isochronous Group (BIG) 858 * @param storage to use by stack, needs to stay valid until adv set is removed with gap_big_terminate 859 * @param big_sync_params 860 * @return status 861 * @events GAP_SUBEVENT_BIG_SYNC_CREATED unless interrupted by call to gap_big_sync_terminate 862 */ 863 uint8_t gap_big_sync_create(le_audio_big_sync_t * storage, le_audio_big_sync_params_t * big_sync_params); 864 865 /** 866 * @brief Stop synchronizing to Broadcast Isochronous Group (BIG). Triggers GAP_SUBEVENT_BIG_SYNC_STOPPED 867 * @note Also used to stop synchronizing before BIG Sync was established 868 * @param big_handle 869 * @return status 870 * @events GAP_SUBEVENT_BIG_SYNC_STOPPED 871 */ 872 uint8_t gap_big_sync_terminate(uint8_t big_handle); 873 874 /** 875 * @brief Create Connected Isochronous Group (CIG) 876 * @param storage to use by stack, needs to stay valid until CIG removed with gap_cig_remove 877 * @param cig_params 878 * @return status 879 * @events GAP_SUBEVENT_CIG_CREATED unless interrupted by call to gap_cig_remove 880 */ 881 uint8_t gap_cig_create(le_audio_cig_t * storage, le_audio_cig_params_t * cig_params); 882 883 /** 884 * @brief Remove Connected Isochronous Group (CIG) 885 * @param cig_id 886 * @return status 887 * @events GAP_SUBEVENT_CIG_TERMINATED 888 */ 889 uint8_t gap_cig_remove(uint8_t cig_id); 890 891 /** 892 * @brief Create Connected Isochronous Streams (CIS) 893 * @note number of CIS from cig_params in gap_cig_create is used 894 * @param cig_id 895 * @param cis_con_handles array of CIS Connection Handles 896 * @param acl_con_handles array of ACL Connection Handles 897 * @return status 898 * @events GAP_SUBEVENT_CIS_CREATED unless interrupted by call to gap_cig_remove 899 */ 900 uint8_t gap_cis_create(uint8_t cig_id, hci_con_handle_t cis_con_handles [], hci_con_handle_t acl_con_handles []); 901 902 /** 903 * @brief Accept Connected Isochronous Stream (CIS) 904 * @param cis_con_handle 905 * @return status 906 * @events GAP_SUBEVENT_CIS_CREATED 907 */ 908 uint8_t gap_cis_accept(hci_con_handle_t cis_con_handle); 909 910 /** 911 * @brief Reject Connected Isochronous Stream (CIS) 912 * @param cis_con_handle 913 * @return status 914 * @events GAP_SUBEVENT_CIS_CREATED 915 */ 916 uint8_t gap_cis_reject(hci_con_handle_t cis_con_handle); 917 918 /** 919 * @brief Set connection parameters for outgoing connections and connection parameter updates 920 * @param conn_scan_interval (unit: 0.625 msec), default: 60 ms 921 * @param conn_scan_window (unit: 0.625 msec), default: 30 ms 922 * @param conn_interval_min (unit: 1.25ms), default: 10 ms 923 * @param conn_interval_max (unit: 1.25ms), default: 30 ms 924 * @param conn_latency, default: 4 925 * @param supervision_timeout (unit: 10ms), default: 720 ms 926 * @param min_ce_length (unit: 0.625ms), default: 10 ms 927 * @param max_ce_length (unit: 0.625ms), default: 30 ms 928 */ 929 void gap_set_connection_parameters(uint16_t conn_scan_interval, uint16_t conn_scan_window, 930 uint16_t conn_interval_min, uint16_t conn_interval_max, uint16_t conn_latency, 931 uint16_t supervision_timeout, uint16_t min_ce_length, uint16_t max_ce_length); 932 933 /** 934 * @brief Set initiating PHYs for outgoing connections 935 * @param phy bitmask: 1 = LE 1M PHY, 2 = LE 2M PHY, 4 = LE Coded PHY 936 */ 937 void gap_set_connection_phys(uint8_t phys); 938 939 /** 940 * @brief Request an update of the connection parameter for a given LE connection 941 * @param handle 942 * @param conn_interval_min (unit: 1.25ms) 943 * @param conn_interval_max (unit: 1.25ms) 944 * @param conn_latency 945 * @param supervision_timeout (unit: 10ms) 946 * @return 0 if ok 947 */ 948 int gap_request_connection_parameter_update(hci_con_handle_t con_handle, uint16_t conn_interval_min, 949 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 950 951 /** 952 * @brief Updates the connection parameters for a given LE connection 953 * @param handle 954 * @param conn_interval_min (unit: 1.25ms) 955 * @param conn_interval_max (unit: 1.25ms) 956 * @param conn_latency 957 * @param supervision_timeout (unit: 10ms) 958 * @return 0 if ok 959 */ 960 int gap_update_connection_parameters(hci_con_handle_t con_handle, uint16_t conn_interval_min, 961 uint16_t conn_interval_max, uint16_t conn_latency, uint16_t supervision_timeout); 962 963 /** 964 * @brief Set accepted connection parameter range 965 * @param range 966 */ 967 void gap_get_connection_parameter_range(le_connection_parameter_range_t * range); 968 969 /** 970 * @brief Get accepted connection parameter range 971 * @param range 972 */ 973 void gap_set_connection_parameter_range(le_connection_parameter_range_t * range); 974 975 /** 976 * @brief Test if connection parameters are inside in existing rage 977 * @param conn_interval_min (unit: 1.25ms) 978 * @param conn_interval_max (unit: 1.25ms) 979 * @param conn_latency 980 * @param supervision_timeout (unit: 10ms) 981 * @return 1 if included 982 */ 983 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); 984 985 /** 986 * @brief Request an update of the connection subrating for a given LE connection 987 * @param handle 988 * @param subrate_min 989 * @param subrate_max 990 * @param max_latency (in units of subrated connection intervals) 991 * @param continuation_number (Minimum number of underlying connection events to remain active after a packet containing a Link Layer PDU with a non-zero Length field is sent or received) 992 * @param supervision_timeout (unit: 10ms) range: 10..3200 (100 ms to 32 s) 993 * @return status 994 */ 995 uint8_t gap_request_connection_subrating(hci_con_handle_t con_handle, uint16_t subrate_min, uint16_t subrate_max, 996 uint16_t max_latency, uint16_t continuation_number, uint16_t supervision_timeout); 997 998 /** 999 * @brief Set max number of connections in LE Peripheral role (if Bluetooth Controller supports it) 1000 * @note: default: 1 1001 * @param max_peripheral_connections 1002 */ 1003 void gap_set_max_number_peripheral_connections(int max_peripheral_connections); 1004 1005 /** 1006 * @brief Add Device to Whitelist 1007 * @param address_typ 1008 * @param address 1009 * @return status 1010 */ 1011 uint8_t gap_whitelist_add(bd_addr_type_t address_type, const bd_addr_t address); 1012 1013 /** 1014 * @brief Remove Device from Whitelist 1015 * @param address_typ 1016 * @param address 1017 * @return status 1018 */ 1019 uint8_t gap_whitelist_remove(bd_addr_type_t address_type, const bd_addr_t address); 1020 1021 /** 1022 * @brief Clear Whitelist 1023 * @return status 1024 */ 1025 uint8_t gap_whitelist_clear(void); 1026 1027 /** 1028 * @brief Connect to remote LE device 1029 * @return status 1030 */ 1031 uint8_t gap_connect(const bd_addr_t addr, bd_addr_type_t addr_type); 1032 1033 /** 1034 * @brief Connect with Whitelist 1035 * @note Explicit whitelist management and this connect with whitelist replace deprecated gap_auto_connection_* functions 1036 * @return status 1037 */ 1038 uint8_t gap_connect_with_whitelist(void); 1039 1040 /** 1041 * @brief Cancel connection process initiated by gap_connect 1042 * @return status 1043 */ 1044 uint8_t gap_connect_cancel(void); 1045 1046 /** 1047 * @brief Auto Connection Establishment - Start Connecting to device 1048 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 1049 * @param address_type 1050 * @param address 1051 * @return status 1052 */ 1053 uint8_t gap_auto_connection_start(bd_addr_type_t address_type, const bd_addr_t address); 1054 1055 /** 1056 * @brief Auto Connection Establishment - Stop Connecting to device 1057 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 1058 * @param address_type 1059 * @param address 1060 * @return status 1061 */ 1062 uint8_t gap_auto_connection_stop(bd_addr_type_t address_type, const bd_addr_t address); 1063 1064 /** 1065 * @brief Auto Connection Establishment - Stop everything 1066 * @deprecated Please setup Whitelist with gap_whitelist_* and start connecting with gap_connect_with_whitelist 1067 * @note Convenience function to stop all active auto connection attempts 1068 * @return status 1069 */ 1070 uint8_t gap_auto_connection_stop_all(void); 1071 1072 /** 1073 * @brief Set LE PHY 1074 * @param con_handle 1075 * @param all_phys 0 = set rx/tx, 1 = set only rx, 2 = set only tx 1076 * @param tx_phys 1 = 1M, 2 = 2M, 4 = Coded 1077 * @param rx_phys 1 = 1M, 2 = 2M, 4 = Coded 1078 * @param phy_options 0 = no preferred coding for Coded, 1 = S=2 coding (500 kbit), 2 = S=8 coding (125 kbit) 1079 * @return status 1080 */ 1081 uint8_t gap_le_set_phy(hci_con_handle_t con_handle, uint8_t all_phys, uint8_t tx_phys, uint8_t rx_phys, uint16_t phy_options); 1082 1083 /** 1084 * @brief Get connection interval 1085 * @param con_handle 1086 * @return connection interval, otherwise 0 if error 1087 */ 1088 uint16_t gap_le_connection_interval(hci_con_handle_t con_handle); 1089 1090 /** 1091 * 1092 * @brief Get encryption key size. 1093 * @param con_handle 1094 * @return 0 if not encrypted, 7-16 otherwise 1095 */ 1096 uint8_t gap_encryption_key_size(hci_con_handle_t con_handle); 1097 1098 /** 1099 * @brief Get authentication property. 1100 * @param con_handle 1101 * @return true if bonded with OOB/Passkey (AND MITM protection) 1102 */ 1103 bool gap_authenticated(hci_con_handle_t con_handle); 1104 1105 /** 1106 * @brief Get secure connection property 1107 * @param con_handle 1108 * @return true if bonded usiung LE Secure Connections 1109 */ 1110 bool gap_secure_connection(hci_con_handle_t con_handle); 1111 1112 /** 1113 * @brief Queries authorization state. 1114 * @param con_handle 1115 * @return authorization_state for the current session 1116 */ 1117 authorization_state_t gap_authorization_state(hci_con_handle_t con_handle); 1118 1119 /** 1120 * @brief Get bonded property (BR/EDR/LE) 1121 * @note LE: has to be called after identity resolving is complete 1122 * @param con_handle 1123 * @return true if bonded 1124 */ 1125 bool gap_bonded(hci_con_handle_t con_handle); 1126 1127 // Classic 1128 #ifdef ENABLE_CLASSIC 1129 1130 /** 1131 * @brief Override page scan mode. Page scan mode enabled by l2cap when services are registered 1132 * @note Might be used to reduce power consumption while Bluetooth module stays powered but no (new) 1133 * connections are expected 1134 */ 1135 void gap_connectable_control(uint8_t enable); 1136 1137 /** 1138 * @brief Allows to control if device is discoverable. OFF by default. 1139 */ 1140 void gap_discoverable_control(uint8_t enable); 1141 1142 /** 1143 * @brief Deletes link key for remote device with baseband address. 1144 * @param addr 1145 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 1146 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 1147 * power up, this function only works, when the stack is in working state for these ports. 1148 */ 1149 void gap_drop_link_key_for_bd_addr(bd_addr_t addr); 1150 1151 /** 1152 * @brief Delete all stored link keys 1153 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 1154 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 1155 * power up, this function only works, when the stack is in working state for these ports. 1156 */ 1157 void gap_delete_all_link_keys(void); 1158 1159 /** 1160 * @brief Store link key for remote device with baseband address 1161 * @param addr 1162 * @param link_key 1163 * @param link_key_type 1164 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 1165 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 1166 * power up, this function only works, when the stack is in working state for these ports. 1167 */ 1168 void gap_store_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t type); 1169 1170 /** 1171 * @brief Get link for remote device with basband address 1172 * @param addr 1173 * @param link_key (out) is stored here 1174 * @param link_key_type (out) is stored here 1175 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 1176 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 1177 * power up, this function only works, when the stack is in working state for these ports. 1178 */ 1179 bool gap_get_link_key_for_bd_addr(bd_addr_t addr, link_key_t link_key, link_key_type_t * type); 1180 1181 /** 1182 * @brief Setup Link Key iterator 1183 * @param it 1184 * @return 1 on success 1185 * @note On most desktop ports, the Link Key DB uses a TLV and there is one TLV storage per 1186 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 1187 * power up, this function only works, when the stack is in working state for these ports. 1188 */ 1189 int gap_link_key_iterator_init(btstack_link_key_iterator_t * it); 1190 1191 /** 1192 * @brief Get next Link Key 1193 * @param it 1194 * @brief addr 1195 * @brief link_key 1196 * @brief type of link key 1197 * @return 1, if valid link key found 1198 * @see note on gap_link_key_iterator_init 1199 */ 1200 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); 1201 1202 /** 1203 * @brief Frees resources allocated by iterator_init 1204 * @note Must be called after iteration to free resources 1205 * @param it 1206 * @see note on gap_link_key_iterator_init 1207 */ 1208 void gap_link_key_iterator_done(btstack_link_key_iterator_t * it); 1209 1210 /** 1211 * @brief Start GAP Classic Inquiry 1212 * @param duration in 1.28s units 1213 * @return status 1214 * @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE 1215 */ 1216 int gap_inquiry_start(uint8_t duration_in_1280ms_units); 1217 1218 /** 1219 * @brief Start GAP Classic Periodic Inquiry 1220 * @param duration in 1.28s units 1221 * @param max_period_length between consecutive inquiries in 1.28s units 1222 * @param min_period_length between consecutive inquiries in 1.28s units 1223 * @return status 1224 * @events: GAP_EVENT_INQUIRY_RESULT, GAP_EVENT_INQUIRY_COMPLETE 1225 */ 1226 uint8_t gap_inquiry_periodic_start(uint8_t duration, uint16_t max_period_length, uint16_t min_period_length); 1227 1228 /** 1229 * @brief Stop GAP Classic Inquiry (regular or periodic) 1230 * @return 0 if ok 1231 * @events GAP_EVENT_INQUIRY_COMPLETE 1232 */ 1233 int gap_inquiry_stop(void); 1234 1235 /** 1236 * @brief Set LAP for GAP Classic Inquiry 1237 * @param lap GAP_IAC_GENERAL_INQUIRY (default), GAP_IAC_LIMITED_INQUIRY 1238 */ 1239 void gap_inquiry_set_lap(uint32_t lap); 1240 1241 /** 1242 * @brief Set Inquiry Scan Activity 1243 * @param inquiry_scan_interval range: 0x0012 to 0x1000; only even values are valid, Time = N * 0.625 ms 1244 * @param inquiry_scan_window range: 0x0011 to 0x1000; Time = N * 0.625 ms 1245 */ 1246 void gap_inquiry_set_scan_activity(uint16_t inquiry_scan_interval, uint16_t inquiry_scan_window); 1247 1248 /** 1249 * @brief Set Inquiry Transmit Power Level 1250 * @param tx_power range: -70 to 20 dBm 1251 */ 1252 void gap_inquiry_set_transmit_power_level(int8_t tx_power); 1253 1254 /** 1255 * @brief Remote Name Request 1256 * @param addr 1257 * @param page_scan_repetition_mode 1258 * @param clock_offset only used when bit 15 is set - pass 0 if not known 1259 * @events HCI_EVENT_REMOTE_NAME_REQUEST_COMPLETE 1260 */ 1261 int gap_remote_name_request(const bd_addr_t addr, uint8_t page_scan_repetition_mode, uint16_t clock_offset); 1262 1263 /** 1264 * @brief Legacy Pairing Pin Code Response 1265 * @note data is not copied, pointer has to stay valid 1266 * @param addr 1267 * @param pin 1268 * @return 0 if ok 1269 */ 1270 int gap_pin_code_response(const bd_addr_t addr, const char * pin); 1271 1272 /** 1273 * @brief Legacy Pairing Pin Code Response for binary data / non-strings 1274 * @note data is not copied, pointer has to stay valid 1275 * @param addr 1276 * @param pin_data 1277 * @param pin_len 1278 * @return 0 if ok 1279 */ 1280 int gap_pin_code_response_binary(const bd_addr_t addr, const uint8_t * pin_data, uint8_t pin_len); 1281 1282 /** 1283 * @brief Abort Legacy Pairing 1284 * @param addr 1285 * @param pin 1286 * @return 0 if ok 1287 */ 1288 int gap_pin_code_negative(bd_addr_t addr); 1289 1290 /** 1291 * @brief SSP Passkey Response 1292 * @param addr 1293 * @param passkey [0..999999] 1294 * @return 0 if ok 1295 */ 1296 int gap_ssp_passkey_response(const bd_addr_t addr, uint32_t passkey); 1297 1298 /** 1299 * @brief Abort SSP Passkey Entry/Pairing 1300 * @param addr 1301 * @param pin 1302 * @return 0 if ok 1303 */ 1304 int gap_ssp_passkey_negative(const bd_addr_t addr); 1305 1306 /** 1307 * @brief Accept SSP Numeric Comparison 1308 * @param addr 1309 * @param passkey 1310 * @return 0 if ok 1311 */ 1312 int gap_ssp_confirmation_response(const bd_addr_t addr); 1313 1314 /** 1315 * @brief Abort SSP Numeric Comparison/Pairing 1316 * @param addr 1317 * @param pin 1318 * @return 0 if ok 1319 */ 1320 int gap_ssp_confirmation_negative(const bd_addr_t addr); 1321 1322 /** 1323 * @brief Generate new OOB data 1324 * @note OOB data will be provided in GAP_EVENT_LOCAL_OOB_DATA and be used in future pairing procedures 1325 */ 1326 void gap_ssp_generate_oob_data(void); 1327 1328 /** 1329 * @brief Report Remote OOB Data 1330 * @note Pairing Hash and Randomizer are expected in big-endian byte format 1331 * @param bd_addr 1332 * @param c_192 Simple Pairing Hash C derived from P-192 public key 1333 * @param r_192 Simple Pairing Randomizer derived from P-192 public key 1334 * @param c_256 Simple Pairing Hash C derived from P-256 public key 1335 * @param r_256 Simple Pairing Randomizer derived from P-256 public key 1336 * @return status 1337 */ 1338 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); 1339 1340 /** 1341 * Send SSP IO Capabilities Reply 1342 * @note IO Capabilities (Negative) Reply is sent automatically unless ENABLE_EXPLICIT_IO_CAPABILITIES_REPLY 1343 * @param addr 1344 * @return status 1345 */ 1346 uint8_t gap_ssp_io_capabilities_response(const bd_addr_t addr); 1347 1348 /** 1349 * Send SSP IO Capabilities Negative Reply 1350 * @note IO Capabilities (Negative) Reply is sent automatically unless ENABLE_EXPLICIT_IO_CAPABILITIES_REPLY 1351 * @param addr 1352 * @return status 1353 */ 1354 uint8_t gap_ssp_io_capabilities_negative(const bd_addr_t addr); 1355 1356 /** 1357 * Send Link Key Reponse 1358 * @note Link Key (Negative) Reply is sent automatically unless ENABLE_EXPLICIT_LINK_KEY_RESPONSE 1359 * @param addr 1360 * @param link_key 1361 * @param type or INVALID_LINK_KEY if link key not available 1362 * @return status 1363 */ 1364 uint8_t gap_send_link_key_response(const bd_addr_t addr, link_key_t link_key, link_key_type_t type); 1365 1366 /** 1367 * @brief Enter Sniff mode 1368 * @param con_handle 1369 * @param sniff_min_interval range: 0x0002 to 0xFFFE; only even values are valid, Time = N * 0.625 ms 1370 * @param sniff_max_interval range: 0x0002 to 0xFFFE; only even values are valid, Time = N * 0.625 ms 1371 * @param sniff_attempt Number of Baseband receive slots for sniff attempt. 1372 * @param sniff_timeout Number of Baseband receive slots for sniff timeout. 1373 * @return status 1374 */ 1375 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); 1376 1377 /** 1378 * @brief Exit Sniff mode 1379 * @param con_handle 1380 * @return status 1381 */ 1382 uint8_t gap_sniff_mode_exit(hci_con_handle_t con_handle); 1383 1384 /** 1385 * @brief Configure Sniff Subrating 1386 * @param con_handle 1387 * @param max_latency range: 0x0002 to 0xFFFE; Time = N * 0.625 ms 1388 * @param min_remote_timeout range: 0x0002 to 0xFFFE; Time = N * 0.625 ms 1389 * @param min_local_timeout range: 0x0002 to 0xFFFE; Time = N * 0.625 ms 1390 * @return status 1391 */ 1392 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); 1393 1394 /** 1395 * @Brief Set QoS 1396 * @param con_handle 1397 * @param service_type 1398 * @param token_rate 1399 * @param peak_bandwidth 1400 * @param latency 1401 * @param delay_variation 1402 * @return status 1403 */ 1404 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); 1405 1406 #endif 1407 1408 // LE 1409 1410 /** 1411 * @brief Get own addr type and address used for LE for next scan/advertisement/connect operation 1412 */ 1413 void gap_le_get_own_address(uint8_t * addr_type, bd_addr_t addr); 1414 1415 /** 1416 * @brief Get own addr type and address used for LE advertisements (Peripheral) 1417 */ 1418 void gap_le_get_own_advertisements_address(uint8_t * addr_type, bd_addr_t addr); 1419 1420 /** 1421 * @brief Get own addr type and address used for LE Extended Advertisiing (Peripheral) 1422 */ 1423 void gap_le_get_own_advertising_set_address(uint8_t * addr_type, bd_addr_t addr, uint8_t advertising_handle); 1424 1425 /** 1426 * @brief Get own addr type and address used for LE connections (Central) 1427 */ 1428 void gap_le_get_own_connection_address(uint8_t * addr_type, bd_addr_t addr); 1429 1430 /** 1431 * @brief Get state of connection re-encryption for bonded devices when in central role 1432 * @note used by gatt_client and att_server to wait for re-encryption 1433 * @param con_handle 1434 * @return 1 if security setup is active 1435 */ 1436 bool gap_reconnect_security_setup_active(hci_con_handle_t con_handle); 1437 1438 /** 1439 * @brief Delete bonding information for remote device 1440 * @note On most desktop ports, the LE Device DB uses a TLV and there is one TLV storage per 1441 * Controller resp. its Bluetooth Address. As the Bluetooth Address is retrieved during 1442 * power up, this function only works, when the stack is in working state for these ports. 1443 * @param address_type 1444 * @param address 1445 */ 1446 void gap_delete_bonding(bd_addr_type_t address_type, bd_addr_t address); 1447 1448 /** 1449 * LE Privacy 1.2 - requires support by Controller and ENABLE_LE_RESOLVING_LIST to be defined 1450 */ 1451 1452 /** 1453 * Set Privacy Mode for use in Resolving List. Default: LE_PRIVACY_MODE_DEVICE 1454 * @note Only applies for new devices added to resolving list, please call before startup 1455 * @param privacy_mode 1456 */ 1457 void gap_set_peer_privacy_mode(le_privacy_mode_t privacy_mode ); 1458 1459 /** 1460 * @brief Load LE Device DB entries into Controller Resolving List to allow filtering on 1461 * bonded devies with resolvable private addresses 1462 * @return EROOR_CODE_SUCCESS if supported by Controller 1463 */ 1464 uint8_t gap_load_resolving_list_from_le_device_db(void); 1465 1466 typedef enum { 1467 GAP_PRIVACY_CLIENT_STATE_IDLE, 1468 GAP_PRIVACY_CLIENT_STATE_PENDING, 1469 GAP_PRIVACY_CLIENT_STATE_READY 1470 } gap_privacy_client_state_t; 1471 1472 struct gap_privacy_client { 1473 btstack_linked_item_t * next; 1474 void (*callback)(struct gap_privacy_client * client, bd_addr_t random_addr); 1475 gap_privacy_client_state_t state; 1476 }; 1477 typedef struct gap_privacy_client gap_privacy_client_t; 1478 1479 /** 1480 * @brief Register callback that gets executed during random address update 1481 * @note gap_privacy_client_ready needs to be called after callback is received 1482 * @param client 1483 * @return status 1484 */ 1485 void gap_privacy_client_register(gap_privacy_client_t * client); 1486 1487 /** 1488 * @brief Acknowledge upcoming random address change 1489 * @param client 1490 * @return status 1491 */ 1492 void gap_privacy_client_ready(gap_privacy_client_t * client); 1493 1494 /** 1495 * @brief Unregister callback from random address updates 1496 * @param client 1497 * @return status 1498 */ 1499 void gap_privacy_client_unregister(gap_privacy_client_t * client); 1500 1501 /** 1502 * @brief Get local persistent IRK 1503 */ 1504 const uint8_t * gap_get_persistent_irk(void); 1505 1506 /* API_END*/ 1507 1508 #if defined __cplusplus 1509 } 1510 #endif 1511 1512 #endif // GAP_H 1513