1 /** @file 2 * @brief Bluetooth connection handling 3 */ 4 5 /* 6 * Copyright (c) 2015-2016 Intel Corporation 7 * 8 * SPDX-License-Identifier: Apache-2.0 9 */ 10 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_ 11 #define ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_ 12 13 /** 14 * @brief Connection management 15 * @defgroup bt_conn Connection management 16 * @ingroup bluetooth 17 * @{ 18 */ 19 20 #include <stdbool.h> 21 #include <stdint.h> 22 23 #include <zephyr/bluetooth/bluetooth.h> 24 #include <zephyr/bluetooth/hci_types.h> 25 #include <zephyr/bluetooth/addr.h> 26 #include <zephyr/bluetooth/gap.h> 27 #include <zephyr/bluetooth/direction.h> 28 #include <zephyr/sys/iterable_sections.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /** Opaque type representing a connection to a remote device */ 35 struct bt_conn; 36 37 /** Connection parameters for LE connections */ 38 struct bt_le_conn_param { 39 uint16_t interval_min; 40 uint16_t interval_max; 41 uint16_t latency; 42 uint16_t timeout; 43 }; 44 45 /** @brief Initialize connection parameters 46 * 47 * @param int_min Minimum Connection Interval (N * 1.25 ms) 48 * @param int_max Maximum Connection Interval (N * 1.25 ms) 49 * @param lat Connection Latency 50 * @param to Supervision Timeout (N * 10 ms) 51 */ 52 #define BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \ 53 { \ 54 .interval_min = (int_min), \ 55 .interval_max = (int_max), \ 56 .latency = (lat), \ 57 .timeout = (to), \ 58 } 59 60 /** Helper to declare connection parameters inline 61 * 62 * @param int_min Minimum Connection Interval (N * 1.25 ms) 63 * @param int_max Maximum Connection Interval (N * 1.25 ms) 64 * @param lat Connection Latency 65 * @param to Supervision Timeout (N * 10 ms) 66 */ 67 #define BT_LE_CONN_PARAM(int_min, int_max, lat, to) \ 68 ((struct bt_le_conn_param[]) { \ 69 BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \ 70 }) 71 72 /** Default LE connection parameters: 73 * Connection Interval: 30-50 ms 74 * Latency: 0 75 * Timeout: 4 s 76 */ 77 #define BT_LE_CONN_PARAM_DEFAULT BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, \ 78 BT_GAP_INIT_CONN_INT_MAX, \ 79 0, 400) 80 81 /** Connection PHY information for LE connections */ 82 struct bt_conn_le_phy_info { 83 uint8_t tx_phy; /** Connection transmit PHY */ 84 uint8_t rx_phy; /** Connection receive PHY */ 85 }; 86 87 /** Connection PHY options */ 88 enum { 89 /** Convenience value when no options are specified. */ 90 BT_CONN_LE_PHY_OPT_NONE = 0, 91 92 /** LE Coded using S=2 coding preferred when transmitting. */ 93 BT_CONN_LE_PHY_OPT_CODED_S2 = BIT(0), 94 95 /** LE Coded using S=8 coding preferred when transmitting. */ 96 BT_CONN_LE_PHY_OPT_CODED_S8 = BIT(1), 97 }; 98 99 /** Preferred PHY parameters for LE connections */ 100 struct bt_conn_le_phy_param { 101 uint16_t options; /** Connection PHY options. */ 102 uint8_t pref_tx_phy; /** Bitmask of preferred transmit PHYs */ 103 uint8_t pref_rx_phy; /** Bitmask of preferred receive PHYs */ 104 }; 105 106 /** Initialize PHY parameters 107 * 108 * @param _pref_tx_phy Bitmask of preferred transmit PHYs. 109 * @param _pref_rx_phy Bitmask of preferred receive PHYs. 110 */ 111 #define BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \ 112 { \ 113 .options = BT_CONN_LE_PHY_OPT_NONE, \ 114 .pref_tx_phy = (_pref_tx_phy), \ 115 .pref_rx_phy = (_pref_rx_phy), \ 116 } 117 118 /** Helper to declare PHY parameters inline 119 * 120 * @param _pref_tx_phy Bitmask of preferred transmit PHYs. 121 * @param _pref_rx_phy Bitmask of preferred receive PHYs. 122 */ 123 #define BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy) \ 124 ((struct bt_conn_le_phy_param []) { \ 125 BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \ 126 }) 127 128 /** Only LE 1M PHY */ 129 #define BT_CONN_LE_PHY_PARAM_1M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M, \ 130 BT_GAP_LE_PHY_1M) 131 132 /** Only LE 2M PHY */ 133 #define BT_CONN_LE_PHY_PARAM_2M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_2M, \ 134 BT_GAP_LE_PHY_2M) 135 136 /** Only LE Coded PHY. */ 137 #define BT_CONN_LE_PHY_PARAM_CODED BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_CODED, \ 138 BT_GAP_LE_PHY_CODED) 139 140 /** All LE PHYs. */ 141 #define BT_CONN_LE_PHY_PARAM_ALL BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M | \ 142 BT_GAP_LE_PHY_2M | \ 143 BT_GAP_LE_PHY_CODED, \ 144 BT_GAP_LE_PHY_1M | \ 145 BT_GAP_LE_PHY_2M | \ 146 BT_GAP_LE_PHY_CODED) 147 148 /** Connection data length information for LE connections */ 149 struct bt_conn_le_data_len_info { 150 /** Maximum Link Layer transmission payload size in bytes. */ 151 uint16_t tx_max_len; 152 /** Maximum Link Layer transmission payload time in us. */ 153 uint16_t tx_max_time; 154 /** Maximum Link Layer reception payload size in bytes. */ 155 uint16_t rx_max_len; 156 /** Maximum Link Layer reception payload time in us. */ 157 uint16_t rx_max_time; 158 }; 159 160 /** Connection data length parameters for LE connections */ 161 struct bt_conn_le_data_len_param { 162 /** Maximum Link Layer transmission payload size in bytes. */ 163 uint16_t tx_max_len; 164 /** Maximum Link Layer transmission payload time in us. */ 165 uint16_t tx_max_time; 166 }; 167 168 /** Initialize transmit data length parameters 169 * 170 * @param _tx_max_len Maximum Link Layer transmission payload size in bytes. 171 * @param _tx_max_time Maximum Link Layer transmission payload time in us. 172 */ 173 #define BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \ 174 { \ 175 .tx_max_len = (_tx_max_len), \ 176 .tx_max_time = (_tx_max_time), \ 177 } 178 179 /** Helper to declare transmit data length parameters inline 180 * 181 * @param _tx_max_len Maximum Link Layer transmission payload size in bytes. 182 * @param _tx_max_time Maximum Link Layer transmission payload time in us. 183 */ 184 #define BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time) \ 185 ((struct bt_conn_le_data_len_param[]) { \ 186 BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \ 187 }) 188 189 /** Default LE data length parameters. */ 190 #define BT_LE_DATA_LEN_PARAM_DEFAULT \ 191 BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_DEFAULT, \ 192 BT_GAP_DATA_TIME_DEFAULT) 193 194 /** Maximum LE data length parameters. */ 195 #define BT_LE_DATA_LEN_PARAM_MAX \ 196 BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_MAX, \ 197 BT_GAP_DATA_TIME_MAX) 198 199 /** @brief Increment a connection's reference count. 200 * 201 * Increment the reference count of a connection object. 202 * 203 * @note Will return NULL if the reference count is zero. 204 * 205 * @param conn Connection object. 206 * 207 * @return Connection object with incremented reference count, or NULL if the 208 * reference count is zero. 209 */ 210 struct bt_conn *bt_conn_ref(struct bt_conn *conn); 211 212 /** @brief Decrement a connection's reference count. 213 * 214 * Decrement the reference count of a connection object. 215 * 216 * @param conn Connection object. 217 */ 218 void bt_conn_unref(struct bt_conn *conn); 219 220 /** @brief Iterate through all bt_conn objects. 221 * 222 * Iterates trough all bt_conn objects that are alive in the Host allocator. 223 * 224 * To find established connections, combine this with @ref bt_conn_get_info. 225 * Check that @ref bt_conn_info.state is @ref BT_CONN_STATE_CONNECTED. 226 * 227 * Thread safety: This API is thread safe, but it does not guarantee a 228 * sequentially-consistent view for objects allocated during the current 229 * invocation of this API. E.g. If preempted while allocations A then B then C 230 * happen then results may include A and C but miss B. 231 * 232 * @param type Connection Type 233 * @param func Function to call for each connection. 234 * @param data Data to pass to the callback function. 235 */ 236 void bt_conn_foreach(int type, void (*func)(struct bt_conn *conn, void *data), 237 void *data); 238 239 /** @brief Look up an existing connection by address. 240 * 241 * Look up an existing connection based on the remote address. 242 * 243 * The caller gets a new reference to the connection object which must be 244 * released with bt_conn_unref() once done using the object. 245 * 246 * @param id Local identity (in most cases BT_ID_DEFAULT). 247 * @param peer Remote address. 248 * 249 * @return Connection object or NULL if not found. 250 */ 251 struct bt_conn *bt_conn_lookup_addr_le(uint8_t id, const bt_addr_le_t *peer); 252 253 /** @brief Get destination (peer) address of a connection. 254 * 255 * @param conn Connection object. 256 * 257 * @return Destination address. 258 */ 259 const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn); 260 261 /** @brief Get array index of a connection 262 * 263 * This function is used to map bt_conn to index of an array of 264 * connections. The array has CONFIG_BT_MAX_CONN elements. 265 * 266 * @param conn Connection object. 267 * 268 * @return Index of the connection object. 269 * The range of the returned value is 0..CONFIG_BT_MAX_CONN-1 270 */ 271 uint8_t bt_conn_index(const struct bt_conn *conn); 272 273 /** Connection Type */ 274 enum { 275 /** LE Connection Type */ 276 BT_CONN_TYPE_LE = BIT(0), 277 /** BR/EDR Connection Type */ 278 BT_CONN_TYPE_BR = BIT(1), 279 /** SCO Connection Type */ 280 BT_CONN_TYPE_SCO = BIT(2), 281 /** ISO Connection Type */ 282 BT_CONN_TYPE_ISO = BIT(3), 283 /** All Connection Type */ 284 BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR | 285 BT_CONN_TYPE_SCO | BT_CONN_TYPE_ISO, 286 }; 287 288 /** LE Connection Info Structure */ 289 struct bt_conn_le_info { 290 /** Source (Local) Identity Address */ 291 const bt_addr_le_t *src; 292 /** Destination (Remote) Identity Address or remote Resolvable Private 293 * Address (RPA) before identity has been resolved. 294 */ 295 const bt_addr_le_t *dst; 296 /** Local device address used during connection setup. */ 297 const bt_addr_le_t *local; 298 /** Remote device address used during connection setup. */ 299 const bt_addr_le_t *remote; 300 uint16_t interval; /** Connection interval */ 301 uint16_t latency; /** Connection peripheral latency */ 302 uint16_t timeout; /** Connection supervision timeout */ 303 304 #if defined(CONFIG_BT_USER_PHY_UPDATE) 305 const struct bt_conn_le_phy_info *phy; 306 #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */ 307 308 #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE) 309 /* Connection maximum single fragment parameters */ 310 const struct bt_conn_le_data_len_info *data_len; 311 #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */ 312 }; 313 314 /** @brief Convert connection interval to milliseconds 315 * 316 * Multiply by 1.25 to get milliseconds. 317 * 318 * Note that this may be inaccurate, as something like 7.5 ms cannot be 319 * accurately presented with integers. 320 */ 321 #define BT_CONN_INTERVAL_TO_MS(interval) ((interval) * 5U / 4U) 322 323 /** @brief Convert connection interval to microseconds 324 * 325 * Multiply by 1250 to get microseconds. 326 */ 327 #define BT_CONN_INTERVAL_TO_US(interval) ((interval) * 1250U) 328 329 /** BR/EDR Connection Info Structure */ 330 struct bt_conn_br_info { 331 const bt_addr_t *dst; /** Destination (Remote) BR/EDR address */ 332 }; 333 334 enum { 335 BT_CONN_ROLE_CENTRAL = 0, 336 BT_CONN_ROLE_PERIPHERAL = 1, 337 }; 338 339 enum bt_conn_state { 340 /** Channel disconnected */ 341 BT_CONN_STATE_DISCONNECTED, 342 /** Channel in connecting state */ 343 BT_CONN_STATE_CONNECTING, 344 /** Channel connected and ready for upper layer traffic on it */ 345 BT_CONN_STATE_CONNECTED, 346 /** Channel in disconnecting state */ 347 BT_CONN_STATE_DISCONNECTING, 348 }; 349 350 /** Security level. */ 351 typedef enum __packed { 352 /** Level 0: Only for BR/EDR special cases, like SDP */ 353 BT_SECURITY_L0, 354 /** Level 1: No encryption and no authentication. */ 355 BT_SECURITY_L1, 356 /** Level 2: Encryption and no authentication (no MITM). */ 357 BT_SECURITY_L2, 358 /** Level 3: Encryption and authentication (MITM). */ 359 BT_SECURITY_L3, 360 /** Level 4: Authenticated Secure Connections and 128-bit key. */ 361 BT_SECURITY_L4, 362 /** Bit to force new pairing procedure, bit-wise OR with requested 363 * security level. 364 */ 365 BT_SECURITY_FORCE_PAIR = BIT(7), 366 } bt_security_t; 367 368 /** Security Info Flags. */ 369 enum bt_security_flag { 370 /** Paired with Secure Connections. */ 371 BT_SECURITY_FLAG_SC = BIT(0), 372 /** Paired with Out of Band method. */ 373 BT_SECURITY_FLAG_OOB = BIT(1), 374 }; 375 376 /** Security Info Structure. */ 377 struct bt_security_info { 378 /** Security Level. */ 379 bt_security_t level; 380 /** Encryption Key Size. */ 381 uint8_t enc_key_size; 382 /** Flags. */ 383 enum bt_security_flag flags; 384 }; 385 386 /** Connection role (central or peripheral) */ 387 #define BT_CONN_ROLE_MASTER __DEPRECATED_MACRO BT_CONN_ROLE_CENTRAL 388 #define BT_CONN_ROLE_SLAVE __DEPRECATED_MACRO BT_CONN_ROLE_PERIPHERAL 389 390 /** Connection Info Structure */ 391 struct bt_conn_info { 392 /** Connection Type. */ 393 uint8_t type; 394 /** Connection Role. */ 395 uint8_t role; 396 /** Which local identity the connection was created with */ 397 uint8_t id; 398 /** Connection Type specific Info.*/ 399 union { 400 /** LE Connection specific Info. */ 401 struct bt_conn_le_info le; 402 /** BR/EDR Connection specific Info. */ 403 struct bt_conn_br_info br; 404 }; 405 /** Connection state. */ 406 enum bt_conn_state state; 407 /** Security specific info. */ 408 struct bt_security_info security; 409 }; 410 411 /** LE Connection Remote Info Structure */ 412 struct bt_conn_le_remote_info { 413 414 /** Remote LE feature set (bitmask). */ 415 const uint8_t *features; 416 }; 417 418 /** BR/EDR Connection Remote Info structure */ 419 struct bt_conn_br_remote_info { 420 421 /** Remote feature set (pages of bitmasks). */ 422 const uint8_t *features; 423 424 /** Number of pages in the remote feature set. */ 425 uint8_t num_pages; 426 }; 427 428 /** @brief Connection Remote Info Structure 429 * 430 * @note The version, manufacturer and subversion fields will only contain 431 * valid data if @kconfig{CONFIG_BT_REMOTE_VERSION} is enabled. 432 */ 433 struct bt_conn_remote_info { 434 /** Connection Type */ 435 uint8_t type; 436 437 /** Remote Link Layer version */ 438 uint8_t version; 439 440 /** Remote manufacturer identifier */ 441 uint16_t manufacturer; 442 443 /** Per-manufacturer unique revision */ 444 uint16_t subversion; 445 446 union { 447 /** LE connection remote info */ 448 struct bt_conn_le_remote_info le; 449 450 /** BR/EDR connection remote info */ 451 struct bt_conn_br_remote_info br; 452 }; 453 }; 454 455 enum bt_conn_le_tx_power_phy { 456 /** Convenience macro for when no PHY is set. */ 457 BT_CONN_LE_TX_POWER_PHY_NONE, 458 /** LE 1M PHY */ 459 BT_CONN_LE_TX_POWER_PHY_1M, 460 /** LE 2M PHY */ 461 BT_CONN_LE_TX_POWER_PHY_2M, 462 /** LE Coded PHY using S=8 coding. */ 463 BT_CONN_LE_TX_POWER_PHY_CODED_S8, 464 /** LE Coded PHY using S=2 coding. */ 465 BT_CONN_LE_TX_POWER_PHY_CODED_S2, 466 }; 467 468 /** LE Transmit Power Level Structure */ 469 struct bt_conn_le_tx_power { 470 471 /** Input: 1M, 2M, Coded S2 or Coded S8 */ 472 uint8_t phy; 473 474 /** Output: current transmit power level */ 475 int8_t current_level; 476 477 /** Output: maximum transmit power level */ 478 int8_t max_level; 479 }; 480 481 /** @brief Passkey Keypress Notification type 482 * 483 * The numeric values are the same as in the Core specification for Pairing 484 * Keypress Notification PDU. 485 */ 486 enum bt_conn_auth_keypress { 487 BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED = 0x00, 488 BT_CONN_AUTH_KEYPRESS_DIGIT_ENTERED = 0x01, 489 BT_CONN_AUTH_KEYPRESS_DIGIT_ERASED = 0x02, 490 BT_CONN_AUTH_KEYPRESS_CLEARED = 0x03, 491 BT_CONN_AUTH_KEYPRESS_ENTRY_COMPLETED = 0x04, 492 }; 493 494 /** @brief Get connection info 495 * 496 * @param conn Connection object. 497 * @param info Connection info object. 498 * 499 * @return Zero on success or (negative) error code on failure. 500 */ 501 int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info); 502 503 /** @brief Get connection info for the remote device. 504 * 505 * @param conn Connection object. 506 * @param remote_info Connection remote info object. 507 * 508 * @note In order to retrieve the remote version (version, manufacturer 509 * and subversion) @kconfig{CONFIG_BT_REMOTE_VERSION} must be enabled 510 * 511 * @note The remote information is exchanged directly after the connection has 512 * been established. The application can be notified about when the remote 513 * information is available through the remote_info_available callback. 514 * 515 * @return Zero on success or (negative) error code on failure. 516 * @return -EBUSY The remote information is not yet available. 517 */ 518 int bt_conn_get_remote_info(struct bt_conn *conn, 519 struct bt_conn_remote_info *remote_info); 520 521 /** @brief Get connection transmit power level. 522 * 523 * @param conn Connection object. 524 * @param tx_power_level Transmit power level descriptor. 525 * 526 * @return Zero on success or (negative) error code on failure. 527 * @return -ENOBUFS HCI command buffer is not available. 528 */ 529 int bt_conn_le_get_tx_power_level(struct bt_conn *conn, 530 struct bt_conn_le_tx_power *tx_power_level); 531 532 /** @brief Update the connection parameters. 533 * 534 * If the local device is in the peripheral role then updating the connection 535 * parameters will be delayed. This delay can be configured by through the 536 * @kconfig{CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT} option. 537 * 538 * @param conn Connection object. 539 * @param param Updated connection parameters. 540 * 541 * @return Zero on success or (negative) error code on failure. 542 */ 543 int bt_conn_le_param_update(struct bt_conn *conn, 544 const struct bt_le_conn_param *param); 545 546 /** @brief Update the connection transmit data length parameters. 547 * 548 * @param conn Connection object. 549 * @param param Updated data length parameters. 550 * 551 * @return Zero on success or (negative) error code on failure. 552 */ 553 int bt_conn_le_data_len_update(struct bt_conn *conn, 554 const struct bt_conn_le_data_len_param *param); 555 556 /** @brief Update the connection PHY parameters. 557 * 558 * Update the preferred transmit and receive PHYs of the connection. 559 * Use @ref BT_GAP_LE_PHY_NONE to indicate no preference. 560 * 561 * @param conn Connection object. 562 * @param param Updated connection parameters. 563 * 564 * @return Zero on success or (negative) error code on failure. 565 */ 566 int bt_conn_le_phy_update(struct bt_conn *conn, 567 const struct bt_conn_le_phy_param *param); 568 569 /** @brief Disconnect from a remote device or cancel pending connection. 570 * 571 * Disconnect an active connection with the specified reason code or cancel 572 * pending outgoing connection. 573 * 574 * The disconnect reason for a normal disconnect should be: 575 * @ref BT_HCI_ERR_REMOTE_USER_TERM_CONN. 576 * 577 * The following disconnect reasons are accepted: 578 * - @ref BT_HCI_ERR_AUTH_FAIL 579 * - @ref BT_HCI_ERR_REMOTE_USER_TERM_CONN 580 * - @ref BT_HCI_ERR_REMOTE_LOW_RESOURCES 581 * - @ref BT_HCI_ERR_REMOTE_POWER_OFF 582 * - @ref BT_HCI_ERR_UNSUPP_REMOTE_FEATURE 583 * - @ref BT_HCI_ERR_PAIRING_NOT_SUPPORTED 584 * - @ref BT_HCI_ERR_UNACCEPT_CONN_PARAM 585 * 586 * @param conn Connection to disconnect. 587 * @param reason Reason code for the disconnection. 588 * 589 * @return Zero on success or (negative) error code on failure. 590 */ 591 int bt_conn_disconnect(struct bt_conn *conn, uint8_t reason); 592 593 enum { 594 /** Convenience value when no options are specified. */ 595 BT_CONN_LE_OPT_NONE = 0, 596 597 /** @brief Enable LE Coded PHY. 598 * 599 * Enable scanning on the LE Coded PHY. 600 */ 601 BT_CONN_LE_OPT_CODED = BIT(0), 602 603 /** @brief Disable LE 1M PHY. 604 * 605 * Disable scanning on the LE 1M PHY. 606 * 607 * @note Requires @ref BT_CONN_LE_OPT_CODED. 608 */ 609 BT_CONN_LE_OPT_NO_1M = BIT(1), 610 }; 611 612 struct bt_conn_le_create_param { 613 614 /** Bit-field of create connection options. */ 615 uint32_t options; 616 617 /** Scan interval (N * 0.625 ms) */ 618 uint16_t interval; 619 620 /** Scan window (N * 0.625 ms) */ 621 uint16_t window; 622 623 /** @brief Scan interval LE Coded PHY (N * 0.625 MS) 624 * 625 * Set zero to use same as LE 1M PHY scan interval 626 */ 627 uint16_t interval_coded; 628 629 /** @brief Scan window LE Coded PHY (N * 0.625 MS) 630 * 631 * Set zero to use same as LE 1M PHY scan window. 632 */ 633 uint16_t window_coded; 634 635 /** @brief Connection initiation timeout (N * 10 MS) 636 * 637 * Set zero to use the default @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT} 638 * timeout. 639 * 640 * @note Unused in @ref bt_conn_le_create_auto 641 */ 642 uint16_t timeout; 643 }; 644 645 /** @brief Initialize create connection parameters 646 * 647 * @param _options Create connection options. 648 * @param _interval Create connection scan interval (N * 0.625 ms). 649 * @param _window Create connection scan window (N * 0.625 ms). 650 */ 651 #define BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \ 652 { \ 653 .options = (_options), \ 654 .interval = (_interval), \ 655 .window = (_window), \ 656 .interval_coded = 0, \ 657 .window_coded = 0, \ 658 .timeout = 0, \ 659 } 660 661 /** Helper to declare create connection parameters inline 662 * 663 * @param _options Create connection options. 664 * @param _interval Create connection scan interval (N * 0.625 ms). 665 * @param _window Create connection scan window (N * 0.625 ms). 666 */ 667 #define BT_CONN_LE_CREATE_PARAM(_options, _interval, _window) \ 668 ((struct bt_conn_le_create_param[]) { \ 669 BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \ 670 }) 671 672 /** Default LE create connection parameters. 673 * Scan continuously by setting scan interval equal to scan window. 674 */ 675 #define BT_CONN_LE_CREATE_CONN \ 676 BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \ 677 BT_GAP_SCAN_FAST_INTERVAL, \ 678 BT_GAP_SCAN_FAST_INTERVAL) 679 680 /** Default LE create connection using filter accept list parameters. 681 * Scan window: 30 ms. 682 * Scan interval: 60 ms. 683 */ 684 #define BT_CONN_LE_CREATE_CONN_AUTO \ 685 BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \ 686 BT_GAP_SCAN_FAST_INTERVAL, \ 687 BT_GAP_SCAN_FAST_WINDOW) 688 689 /** @brief Initiate an LE connection to a remote device. 690 * 691 * Allows initiate new LE link to remote peer using its address. 692 * 693 * The caller gets a new reference to the connection object which must be 694 * released with bt_conn_unref() once done using the object. 695 * 696 * This uses the General Connection Establishment procedure. 697 * 698 * The application must disable explicit scanning before initiating 699 * a new LE connection. 700 * 701 * @param[in] peer Remote address. 702 * @param[in] create_param Create connection parameters. 703 * @param[in] conn_param Initial connection parameters. 704 * @param[out] conn Valid connection object on success. 705 * 706 * @return Zero on success or (negative) error code on failure. 707 */ 708 int bt_conn_le_create(const bt_addr_le_t *peer, 709 const struct bt_conn_le_create_param *create_param, 710 const struct bt_le_conn_param *conn_param, 711 struct bt_conn **conn); 712 713 struct bt_conn_le_create_synced_param { 714 715 /** @brief Remote address 716 * 717 * The peer must be synchronized to the PAwR train. 718 * 719 */ 720 const bt_addr_le_t *peer; 721 722 /** The subevent where the connection will be initiated. */ 723 uint8_t subevent; 724 }; 725 726 /** @brief Create a connection to a synced device 727 * 728 * Initiate a connection to a synced device from a Periodic Advertising 729 * with Responses (PAwR) train. 730 * 731 * The caller gets a new reference to the connection object which must be 732 * released with bt_conn_unref() once done using the object. 733 * 734 * This uses the Periodic Advertising Connection Procedure. 735 * 736 * @param[in] adv The adverting set the PAwR advertiser belongs to. 737 * @param[in] synced_param Create connection parameters. 738 * @param[in] conn_param Initial connection parameters. 739 * @param[out] conn Valid connection object on success. 740 * 741 * @return Zero on success or (negative) error code on failure. 742 */ 743 int bt_conn_le_create_synced(const struct bt_le_ext_adv *adv, 744 const struct bt_conn_le_create_synced_param *synced_param, 745 const struct bt_le_conn_param *conn_param, struct bt_conn **conn); 746 747 /** @brief Automatically connect to remote devices in the filter accept list.. 748 * 749 * This uses the Auto Connection Establishment procedure. 750 * The procedure will continue until a single connection is established or the 751 * procedure is stopped through @ref bt_conn_create_auto_stop. 752 * To establish connections to all devices in the the filter accept list the 753 * procedure should be started again in the connected callback after a 754 * new connection has been established. 755 * 756 * @param create_param Create connection parameters 757 * @param conn_param Initial connection parameters. 758 * 759 * @return Zero on success or (negative) error code on failure. 760 * @return -ENOMEM No free connection object available. 761 */ 762 int bt_conn_le_create_auto(const struct bt_conn_le_create_param *create_param, 763 const struct bt_le_conn_param *conn_param); 764 765 /** @brief Stop automatic connect creation. 766 * 767 * @return Zero on success or (negative) error code on failure. 768 */ 769 int bt_conn_create_auto_stop(void); 770 771 /** @brief Automatically connect to remote device if it's in range. 772 * 773 * This function enables/disables automatic connection initiation. 774 * Every time the device loses the connection with peer, this connection 775 * will be re-established if connectable advertisement from peer is received. 776 * 777 * @note Auto connect is disabled during explicit scanning. 778 * 779 * @param addr Remote Bluetooth address. 780 * @param param If non-NULL, auto connect is enabled with the given 781 * parameters. If NULL, auto connect is disabled. 782 * 783 * @return Zero on success or error code otherwise. 784 */ 785 int bt_le_set_auto_conn(const bt_addr_le_t *addr, 786 const struct bt_le_conn_param *param); 787 788 /** @brief Set security level for a connection. 789 * 790 * This function enable security (encryption) for a connection. If the device 791 * has bond information for the peer with sufficiently strong key encryption 792 * will be enabled. If the connection is already encrypted with sufficiently 793 * strong key this function does nothing. 794 * 795 * If the device has no bond information for the peer and is not already paired 796 * then the pairing procedure will be initiated. Note that @p sec has no effect 797 * on the security level selected for the pairing process. The selection is 798 * instead controlled by the values of the registered @ref bt_conn_auth_cb. If 799 * the device has bond information or is already paired and the keys are too 800 * weak then the pairing procedure will be initiated. 801 * 802 * This function may return error if required level of security is not possible 803 * to achieve due to local or remote device limitation (e.g., input output 804 * capabilities), or if the maximum number of paired devices has been reached. 805 * 806 * This function may return error if the pairing procedure has already been 807 * initiated by the local device or the peer device. 808 * 809 * @note When @kconfig{CONFIG_BT_SMP_SC_ONLY} is enabled then the security 810 * level will always be level 4. 811 * 812 * @note When @kconfig{CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY} is enabled then the 813 * security level will always be level 3. 814 * 815 * @param conn Connection object. 816 * @param sec Requested security level. 817 * 818 * @return 0 on success or negative error 819 */ 820 int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec); 821 822 /** @brief Get security level for a connection. 823 * 824 * @return Connection security level 825 */ 826 bt_security_t bt_conn_get_security(const struct bt_conn *conn); 827 828 /** @brief Get encryption key size. 829 * 830 * This function gets encryption key size. 831 * If there is no security (encryption) enabled 0 will be returned. 832 * 833 * @param conn Existing connection object. 834 * 835 * @return Encryption key size. 836 */ 837 uint8_t bt_conn_enc_key_size(const struct bt_conn *conn); 838 839 enum bt_security_err { 840 /** Security procedure successful. */ 841 BT_SECURITY_ERR_SUCCESS, 842 843 /** Authentication failed. */ 844 BT_SECURITY_ERR_AUTH_FAIL, 845 846 /** PIN or encryption key is missing. */ 847 BT_SECURITY_ERR_PIN_OR_KEY_MISSING, 848 849 /** OOB data is not available. */ 850 BT_SECURITY_ERR_OOB_NOT_AVAILABLE, 851 852 /** The requested security level could not be reached. */ 853 BT_SECURITY_ERR_AUTH_REQUIREMENT, 854 855 /** Pairing is not supported */ 856 BT_SECURITY_ERR_PAIR_NOT_SUPPORTED, 857 858 /** Pairing is not allowed. */ 859 BT_SECURITY_ERR_PAIR_NOT_ALLOWED, 860 861 /** Invalid parameters. */ 862 BT_SECURITY_ERR_INVALID_PARAM, 863 864 /** Distributed Key Rejected */ 865 BT_SECURITY_ERR_KEY_REJECTED, 866 867 /** Pairing failed but the exact reason could not be specified. */ 868 BT_SECURITY_ERR_UNSPECIFIED, 869 }; 870 871 /** @brief Connection callback structure. 872 * 873 * This structure is used for tracking the state of a connection. 874 * It is registered with the help of the bt_conn_cb_register() API. 875 * It's permissible to register multiple instances of this @ref bt_conn_cb 876 * type, in case different modules of an application are interested in 877 * tracking the connection state. If a callback is not of interest for 878 * an instance, it may be set to NULL and will as a consequence not be 879 * used for that instance. 880 */ 881 struct bt_conn_cb { 882 /** @brief A new connection has been established. 883 * 884 * This callback notifies the application of a new connection. 885 * In case the err parameter is non-zero it means that the 886 * connection establishment failed. 887 * 888 * @note If the connection was established from an advertising set then 889 * the advertising set cannot be restarted directly from this 890 * callback. Instead use the connected callback of the 891 * advertising set. 892 * 893 * @param conn New connection object. 894 * @param err HCI error. Zero for success, non-zero otherwise. 895 * 896 * @p err can mean either of the following: 897 * - @ref BT_HCI_ERR_UNKNOWN_CONN_ID Creating the connection started by 898 * @ref bt_conn_le_create was canceled either by the user through 899 * @ref bt_conn_disconnect or by the timeout in the host through 900 * @ref bt_conn_le_create_param timeout parameter, which defaults to 901 * @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT} seconds. 902 * - @p BT_HCI_ERR_ADV_TIMEOUT High duty cycle directed connectable 903 * advertiser started by @ref bt_le_adv_start failed to be connected 904 * within the timeout. 905 */ 906 void (*connected)(struct bt_conn *conn, uint8_t err); 907 908 /** @brief A connection has been disconnected. 909 * 910 * This callback notifies the application that a connection 911 * has been disconnected. 912 * 913 * When this callback is called the stack still has one reference to 914 * the connection object. If the application in this callback tries to 915 * start either a connectable advertiser or create a new connection 916 * this might fail because there are no free connection objects 917 * available. 918 * To avoid this issue it is recommended to either start connectable 919 * advertise or create a new connection using @ref k_work_submit or 920 * increase @kconfig{CONFIG_BT_MAX_CONN}. 921 * 922 * @param conn Connection object. 923 * @param reason BT_HCI_ERR_* reason for the disconnection. 924 */ 925 void (*disconnected)(struct bt_conn *conn, uint8_t reason); 926 927 /** @brief LE connection parameter update request. 928 * 929 * This callback notifies the application that a remote device 930 * is requesting to update the connection parameters. The 931 * application accepts the parameters by returning true, or 932 * rejects them by returning false. Before accepting, the 933 * application may also adjust the parameters to better suit 934 * its needs. 935 * 936 * It is recommended for an application to have just one of these 937 * callbacks for simplicity. However, if an application registers 938 * multiple it needs to manage the potentially different 939 * requirements for each callback. Each callback gets the 940 * parameters as returned by previous callbacks, i.e. they are not 941 * necessarily the same ones as the remote originally sent. 942 * 943 * If the application does not have this callback then the default 944 * is to accept the parameters. 945 * 946 * @param conn Connection object. 947 * @param param Proposed connection parameters. 948 * 949 * @return true to accept the parameters, or false to reject them. 950 */ 951 bool (*le_param_req)(struct bt_conn *conn, 952 struct bt_le_conn_param *param); 953 954 /** @brief The parameters for an LE connection have been updated. 955 * 956 * This callback notifies the application that the connection 957 * parameters for an LE connection have been updated. 958 * 959 * @param conn Connection object. 960 * @param interval Connection interval. 961 * @param latency Connection latency. 962 * @param timeout Connection supervision timeout. 963 */ 964 void (*le_param_updated)(struct bt_conn *conn, uint16_t interval, 965 uint16_t latency, uint16_t timeout); 966 #if defined(CONFIG_BT_SMP) 967 /** @brief Remote Identity Address has been resolved. 968 * 969 * This callback notifies the application that a remote 970 * Identity Address has been resolved 971 * 972 * @param conn Connection object. 973 * @param rpa Resolvable Private Address. 974 * @param identity Identity Address. 975 */ 976 void (*identity_resolved)(struct bt_conn *conn, 977 const bt_addr_le_t *rpa, 978 const bt_addr_le_t *identity); 979 #endif /* CONFIG_BT_SMP */ 980 #if defined(CONFIG_BT_SMP) || defined(CONFIG_BT_BREDR) 981 /** @brief The security level of a connection has changed. 982 * 983 * This callback notifies the application that the security of a 984 * connection has changed. 985 * 986 * The security level of the connection can either have been increased 987 * or remain unchanged. An increased security level means that the 988 * pairing procedure has been performed or the bond information from 989 * a previous connection has been applied. If the security level 990 * remains unchanged this means that the encryption key has been 991 * refreshed for the connection. 992 * 993 * @param conn Connection object. 994 * @param level New security level of the connection. 995 * @param err Security error. Zero for success, non-zero otherwise. 996 */ 997 void (*security_changed)(struct bt_conn *conn, bt_security_t level, 998 enum bt_security_err err); 999 #endif /* defined(CONFIG_BT_SMP) || defined(CONFIG_BT_BREDR) */ 1000 1001 #if defined(CONFIG_BT_REMOTE_INFO) 1002 /** @brief Remote information procedures has completed. 1003 * 1004 * This callback notifies the application that the remote information 1005 * has been retrieved from the remote peer. 1006 * 1007 * @param conn Connection object. 1008 * @param remote_info Connection information of remote device. 1009 */ 1010 void (*remote_info_available)(struct bt_conn *conn, 1011 struct bt_conn_remote_info *remote_info); 1012 #endif /* defined(CONFIG_BT_REMOTE_INFO) */ 1013 1014 #if defined(CONFIG_BT_USER_PHY_UPDATE) 1015 /** @brief The PHY of the connection has changed. 1016 * 1017 * This callback notifies the application that the PHY of the 1018 * connection has changed. 1019 * 1020 * @param conn Connection object. 1021 * @param info Connection LE PHY information. 1022 */ 1023 void (*le_phy_updated)(struct bt_conn *conn, 1024 struct bt_conn_le_phy_info *param); 1025 #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */ 1026 1027 #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE) 1028 /** @brief The data length parameters of the connection has changed. 1029 * 1030 * This callback notifies the application that the maximum Link Layer 1031 * payload length or transmission time has changed. 1032 * 1033 * @param conn Connection object. 1034 * @param info Connection data length information. 1035 */ 1036 void (*le_data_len_updated)(struct bt_conn *conn, 1037 struct bt_conn_le_data_len_info *info); 1038 #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */ 1039 1040 #if defined(CONFIG_BT_DF_CONNECTION_CTE_RX) 1041 /** @brief Callback for IQ samples report collected when sampling 1042 * CTE received by data channel PDU. 1043 * 1044 * @param conn The connection object. 1045 * @param iq_report Report data for collected IQ samples. 1046 */ 1047 void (*cte_report_cb)(struct bt_conn *conn, 1048 const struct bt_df_conn_iq_samples_report *iq_report); 1049 #endif /* CONFIG_BT_DF_CONNECTION_CTE_RX */ 1050 1051 struct bt_conn_cb *_next; 1052 }; 1053 1054 /** @brief Register connection callbacks. 1055 * 1056 * Register callbacks to monitor the state of connections. 1057 * 1058 * @param cb Callback struct. Must point to memory that remains valid. 1059 */ 1060 void bt_conn_cb_register(struct bt_conn_cb *cb); 1061 1062 /** 1063 * @brief Register a callback structure for connection events. 1064 * 1065 * @param _name Name of callback structure. 1066 */ 1067 #define BT_CONN_CB_DEFINE(_name) \ 1068 static const STRUCT_SECTION_ITERABLE(bt_conn_cb, \ 1069 _CONCAT(bt_conn_cb_, \ 1070 _name)) 1071 1072 /** @brief Enable/disable bonding. 1073 * 1074 * Set/clear the Bonding flag in the Authentication Requirements of 1075 * SMP Pairing Request/Response data. 1076 * The initial value of this flag depends on BT_BONDABLE Kconfig setting. 1077 * For the vast majority of applications calling this function shouldn't be 1078 * needed. 1079 * 1080 * @param enable Value allowing/disallowing to be bondable. 1081 */ 1082 void bt_set_bondable(bool enable); 1083 1084 /** @brief Allow/disallow remote LE SC OOB data to be used for pairing. 1085 * 1086 * Set/clear the OOB data flag for LE SC SMP Pairing Request/Response data. 1087 * 1088 * @param enable Value allowing/disallowing remote LE SC OOB data. 1089 */ 1090 void bt_le_oob_set_sc_flag(bool enable); 1091 1092 /** @brief Allow/disallow remote legacy OOB data to be used for pairing. 1093 * 1094 * Set/clear the OOB data flag for legacy SMP Pairing Request/Response data. 1095 * 1096 * @param enable Value allowing/disallowing remote legacy OOB data. 1097 */ 1098 void bt_le_oob_set_legacy_flag(bool enable); 1099 1100 /** @brief Set OOB Temporary Key to be used for pairing 1101 * 1102 * This function allows to set OOB data for the LE legacy pairing procedure. 1103 * The function should only be called in response to the oob_data_request() 1104 * callback provided that the legacy method is user pairing. 1105 * 1106 * @param conn Connection object 1107 * @param tk Pointer to 16 byte long TK array 1108 * 1109 * @return Zero on success or -EINVAL if NULL 1110 */ 1111 int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const uint8_t *tk); 1112 1113 /** @brief Set OOB data during LE Secure Connections (SC) pairing procedure 1114 * 1115 * This function allows to set OOB data during the LE SC pairing procedure. 1116 * The function should only be called in response to the oob_data_request() 1117 * callback provided that LE SC method is used for pairing. 1118 * 1119 * The user should submit OOB data according to the information received in the 1120 * callback. This may yield three different configurations: with only local OOB 1121 * data present, with only remote OOB data present or with both local and 1122 * remote OOB data present. 1123 * 1124 * @param conn Connection object 1125 * @param oobd_local Local OOB data or NULL if not present 1126 * @param oobd_remote Remote OOB data or NULL if not present 1127 * 1128 * @return Zero on success or error code otherwise, positive in case of 1129 * protocol error or negative (POSIX) in case of stack internal error. 1130 */ 1131 int bt_le_oob_set_sc_data(struct bt_conn *conn, 1132 const struct bt_le_oob_sc_data *oobd_local, 1133 const struct bt_le_oob_sc_data *oobd_remote); 1134 1135 /** @brief Get OOB data used for LE Secure Connections (SC) pairing procedure 1136 * 1137 * This function allows to get OOB data during the LE SC pairing procedure that 1138 * were set by the bt_le_oob_set_sc_data() API. 1139 * 1140 * @note The OOB data will only be available as long as the connection object 1141 * associated with it is valid. 1142 * 1143 * @param conn Connection object 1144 * @param oobd_local Local OOB data or NULL if not set 1145 * @param oobd_remote Remote OOB data or NULL if not set 1146 * 1147 * @return Zero on success or error code otherwise, positive in case of 1148 * protocol error or negative (POSIX) in case of stack internal error. 1149 */ 1150 int bt_le_oob_get_sc_data(struct bt_conn *conn, 1151 const struct bt_le_oob_sc_data **oobd_local, 1152 const struct bt_le_oob_sc_data **oobd_remote); 1153 1154 /** 1155 * Special passkey value that can be used to disable a previously 1156 * set fixed passkey. 1157 */ 1158 #define BT_PASSKEY_INVALID 0xffffffff 1159 1160 /** @brief Set a fixed passkey to be used for pairing. 1161 * 1162 * This API is only available when the CONFIG_BT_FIXED_PASSKEY 1163 * configuration option has been enabled. 1164 * 1165 * Sets a fixed passkey to be used for pairing. If set, the 1166 * pairing_confirm() callback will be called for all incoming pairings. 1167 * 1168 * @param passkey A valid passkey (0 - 999999) or BT_PASSKEY_INVALID 1169 * to disable a previously set fixed passkey. 1170 * 1171 * @return 0 on success or a negative error code on failure. 1172 */ 1173 int bt_passkey_set(unsigned int passkey); 1174 1175 /** Info Structure for OOB pairing */ 1176 struct bt_conn_oob_info { 1177 /** Type of OOB pairing method */ 1178 enum { 1179 /** LE legacy pairing */ 1180 BT_CONN_OOB_LE_LEGACY, 1181 1182 /** LE SC pairing */ 1183 BT_CONN_OOB_LE_SC, 1184 } type; 1185 1186 union { 1187 /** LE Secure Connections OOB pairing parameters */ 1188 struct { 1189 /** OOB data configuration */ 1190 enum { 1191 /** Local OOB data requested */ 1192 BT_CONN_OOB_LOCAL_ONLY, 1193 1194 /** Remote OOB data requested */ 1195 BT_CONN_OOB_REMOTE_ONLY, 1196 1197 /** Both local and remote OOB data requested */ 1198 BT_CONN_OOB_BOTH_PEERS, 1199 1200 /** No OOB data requested */ 1201 BT_CONN_OOB_NO_DATA, 1202 } oob_config; 1203 } lesc; 1204 }; 1205 }; 1206 1207 #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT) 1208 /** @brief Pairing request and pairing response info structure. 1209 * 1210 * This structure is the same for both smp_pairing_req and smp_pairing_rsp 1211 * and a subset of the packet data, except for the initial Code octet. 1212 * It is documented in Core Spec. Vol. 3, Part H, 3.5.1 and 3.5.2. 1213 */ 1214 struct bt_conn_pairing_feat { 1215 /** IO Capability, Core Spec. Vol 3, Part H, 3.5.1, Table 3.4 */ 1216 uint8_t io_capability; 1217 1218 /** OOB data flag, Core Spec. Vol 3, Part H, 3.5.1, Table 3.5 */ 1219 uint8_t oob_data_flag; 1220 1221 /** AuthReq, Core Spec. Vol 3, Part H, 3.5.1, Fig. 3.3 */ 1222 uint8_t auth_req; 1223 1224 /** Maximum Encryption Key Size, Core Spec. Vol 3, Part H, 3.5.1 */ 1225 uint8_t max_enc_key_size; 1226 1227 /** Initiator Key Distribution/Generation, Core Spec. Vol 3, Part H, 1228 * 3.6.1, Fig. 3.11 1229 */ 1230 uint8_t init_key_dist; 1231 1232 /** Responder Key Distribution/Generation, Core Spec. Vol 3, Part H 1233 * 3.6.1, Fig. 3.11 1234 */ 1235 uint8_t resp_key_dist; 1236 }; 1237 #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */ 1238 1239 /** Authenticated pairing callback structure */ 1240 struct bt_conn_auth_cb { 1241 #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT) 1242 /** @brief Query to proceed incoming pairing or not. 1243 * 1244 * On any incoming pairing req/rsp this callback will be called for 1245 * the application to decide whether to allow for the pairing to 1246 * continue. 1247 * 1248 * The pairing info received from the peer is passed to assist 1249 * making the decision. 1250 * 1251 * As this callback is synchronous the application should return 1252 * a response value immediately. Otherwise it may affect the 1253 * timing during pairing. Hence, this information should not be 1254 * conveyed to the user to take action. 1255 * 1256 * The remaining callbacks are not affected by this, but do notice 1257 * that other callbacks can be called during the pairing. Eg. if 1258 * pairing_confirm is registered both will be called for Just-Works 1259 * pairings. 1260 * 1261 * This callback may be unregistered in which case pairing continues 1262 * as if the Kconfig flag was not set. 1263 * 1264 * This callback is not called for BR/EDR Secure Simple Pairing (SSP). 1265 * 1266 * @param conn Connection where pairing is initiated. 1267 * @param feat Pairing req/resp info. 1268 */ 1269 enum bt_security_err (*pairing_accept)(struct bt_conn *conn, 1270 const struct bt_conn_pairing_feat *const feat); 1271 #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */ 1272 1273 /** @brief Display a passkey to the user. 1274 * 1275 * When called the application is expected to display the given 1276 * passkey to the user, with the expectation that the passkey will 1277 * then be entered on the peer device. The passkey will be in the 1278 * range of 0 - 999999, and is expected to be padded with zeroes so 1279 * that six digits are always shown. E.g. the value 37 should be 1280 * shown as 000037. 1281 * 1282 * This callback may be set to NULL, which means that the local 1283 * device lacks the ability do display a passkey. If set 1284 * to non-NULL the cancel callback must also be provided, since 1285 * this is the only way the application can find out that it should 1286 * stop displaying the passkey. 1287 * 1288 * @param conn Connection where pairing is currently active. 1289 * @param passkey Passkey to show to the user. 1290 */ 1291 void (*passkey_display)(struct bt_conn *conn, unsigned int passkey); 1292 1293 #if defined(CONFIG_BT_PASSKEY_KEYPRESS) 1294 /** @brief Receive Passkey Keypress Notification during pairing 1295 * 1296 * This allows the remote device to use the local device to give users 1297 * feedback on the progress of entering the passkey over there. This is 1298 * useful when the remote device itself has no display suitable for 1299 * showing the progress. 1300 * 1301 * The handler of this callback is expected to keep track of the number 1302 * of digits entered and show a password-field-like feedback to the 1303 * user. 1304 * 1305 * This callback is only relevant while the local side does Passkey 1306 * Display. 1307 * 1308 * The event type is verified to be in range of the enum. No other 1309 * sanitization has been done. The remote could send a large number of 1310 * events of any type in any order. 1311 * 1312 * @param conn The related connection. 1313 * @param type Type of event. Verified in range of the enum. 1314 */ 1315 void (*passkey_display_keypress)(struct bt_conn *conn, 1316 enum bt_conn_auth_keypress type); 1317 #endif 1318 1319 /** @brief Request the user to enter a passkey. 1320 * 1321 * When called the user is expected to enter a passkey. The passkey 1322 * must be in the range of 0 - 999999, and should be expected to 1323 * be zero-padded, as that's how the peer device will typically be 1324 * showing it (e.g. 37 would be shown as 000037). 1325 * 1326 * Once the user has entered the passkey its value should be given 1327 * to the stack using the bt_conn_auth_passkey_entry() API. 1328 * 1329 * This callback may be set to NULL, which means that the local 1330 * device lacks the ability to enter a passkey. If set to non-NULL 1331 * the cancel callback must also be provided, since this is the 1332 * only way the application can find out that it should stop 1333 * requesting the user to enter a passkey. 1334 * 1335 * @param conn Connection where pairing is currently active. 1336 */ 1337 void (*passkey_entry)(struct bt_conn *conn); 1338 1339 /** @brief Request the user to confirm a passkey. 1340 * 1341 * When called the user is expected to confirm that the given 1342 * passkey is also shown on the peer device.. The passkey will 1343 * be in the range of 0 - 999999, and should be zero-padded to 1344 * always be six digits (e.g. 37 would be shown as 000037). 1345 * 1346 * Once the user has confirmed the passkey to match, the 1347 * bt_conn_auth_passkey_confirm() API should be called. If the 1348 * user concluded that the passkey doesn't match the 1349 * bt_conn_auth_cancel() API should be called. 1350 * 1351 * This callback may be set to NULL, which means that the local 1352 * device lacks the ability to confirm a passkey. If set to non-NULL 1353 * the cancel callback must also be provided, since this is the 1354 * only way the application can find out that it should stop 1355 * requesting the user to confirm a passkey. 1356 * 1357 * @param conn Connection where pairing is currently active. 1358 * @param passkey Passkey to be confirmed. 1359 */ 1360 void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey); 1361 1362 /** @brief Request the user to provide Out of Band (OOB) data. 1363 * 1364 * When called the user is expected to provide OOB data. The required 1365 * data are indicated by the information structure. 1366 * 1367 * For LE Secure Connections OOB pairing, the user should provide 1368 * local OOB data, remote OOB data or both depending on their 1369 * availability. Their value should be given to the stack using the 1370 * bt_le_oob_set_sc_data() API. 1371 * 1372 * This callback must be set to non-NULL in order to support OOB 1373 * pairing. 1374 * 1375 * @param conn Connection where pairing is currently active. 1376 * @param info OOB pairing information. 1377 */ 1378 void (*oob_data_request)(struct bt_conn *conn, 1379 struct bt_conn_oob_info *info); 1380 1381 /** @brief Cancel the ongoing user request. 1382 * 1383 * This callback will be called to notify the application that it 1384 * should cancel any previous user request (passkey display, entry 1385 * or confirmation). 1386 * 1387 * This may be set to NULL, but must always be provided whenever the 1388 * passkey_display, passkey_entry passkey_confirm or pairing_confirm 1389 * callback has been provided. 1390 * 1391 * @param conn Connection where pairing is currently active. 1392 */ 1393 void (*cancel)(struct bt_conn *conn); 1394 1395 /** @brief Request confirmation for an incoming pairing. 1396 * 1397 * This callback will be called to confirm an incoming pairing 1398 * request where none of the other user callbacks is applicable. 1399 * 1400 * If the user decides to accept the pairing the 1401 * bt_conn_auth_pairing_confirm() API should be called. If the 1402 * user decides to reject the pairing the bt_conn_auth_cancel() API 1403 * should be called. 1404 * 1405 * This callback may be set to NULL, which means that the local 1406 * device lacks the ability to confirm a pairing request. If set 1407 * to non-NULL the cancel callback must also be provided, since 1408 * this is the only way the application can find out that it should 1409 * stop requesting the user to confirm a pairing request. 1410 * 1411 * @param conn Connection where pairing is currently active. 1412 */ 1413 void (*pairing_confirm)(struct bt_conn *conn); 1414 1415 #if defined(CONFIG_BT_BREDR) 1416 /** @brief Request the user to enter a passkey. 1417 * 1418 * This callback will be called for a BR/EDR (Bluetooth Classic) 1419 * connection where pairing is being performed. Once called the 1420 * user is expected to enter a PIN code with a length between 1421 * 1 and 16 digits. If the @a highsec parameter is set to true 1422 * the PIN code must be 16 digits long. 1423 * 1424 * Once entered, the PIN code should be given to the stack using 1425 * the bt_conn_auth_pincode_entry() API. 1426 * 1427 * This callback may be set to NULL, however in that case pairing 1428 * over BR/EDR will not be possible. If provided, the cancel 1429 * callback must be provided as well. 1430 * 1431 * @param conn Connection where pairing is currently active. 1432 * @param highsec true if 16 digit PIN is required. 1433 */ 1434 void (*pincode_entry)(struct bt_conn *conn, bool highsec); 1435 #endif 1436 }; 1437 1438 /** Authenticated pairing information callback structure */ 1439 struct bt_conn_auth_info_cb { 1440 /** @brief notify that pairing procedure was complete. 1441 * 1442 * This callback notifies the application that the pairing procedure 1443 * has been completed. 1444 * 1445 * @param conn Connection object. 1446 * @param bonded Bond information has been distributed during the 1447 * pairing procedure. 1448 */ 1449 void (*pairing_complete)(struct bt_conn *conn, bool bonded); 1450 1451 /** @brief notify that pairing process has failed. 1452 * 1453 * @param conn Connection object. 1454 * @param reason Pairing failed reason 1455 */ 1456 void (*pairing_failed)(struct bt_conn *conn, 1457 enum bt_security_err reason); 1458 1459 /** @brief Notify that bond has been deleted. 1460 * 1461 * This callback notifies the application that the bond information 1462 * for the remote peer has been deleted 1463 * 1464 * @param id Which local identity had the bond. 1465 * @param peer Remote address. 1466 */ 1467 void (*bond_deleted)(uint8_t id, const bt_addr_le_t *peer); 1468 1469 /** Internally used field for list handling */ 1470 sys_snode_t node; 1471 }; 1472 1473 /** @brief Register authentication callbacks. 1474 * 1475 * Register callbacks to handle authenticated pairing. Passing NULL 1476 * unregisters a previous callbacks structure. 1477 * 1478 * @param cb Callback struct. 1479 * 1480 * @return Zero on success or negative error code otherwise 1481 */ 1482 int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb); 1483 1484 /** @brief Overlay authentication callbacks used for a given connection. 1485 * 1486 * This function can be used only for Bluetooth LE connections. 1487 * The @kconfig{CONFIG_BT_SMP} must be enabled for this function. 1488 * 1489 * The authentication callbacks for a given connection cannot be overlaid if 1490 * security procedures in the SMP module have already started. This function 1491 * can be called only once per connection. 1492 * 1493 * @param conn Connection object. 1494 * @param cb Callback struct. 1495 * 1496 * @return Zero on success or negative error code otherwise 1497 */ 1498 int bt_conn_auth_cb_overlay(struct bt_conn *conn, const struct bt_conn_auth_cb *cb); 1499 1500 /** @brief Register authentication information callbacks. 1501 * 1502 * Register callbacks to get authenticated pairing information. Multiple 1503 * registrations can be done. 1504 * 1505 * @param cb Callback struct. 1506 * 1507 * @return Zero on success or negative error code otherwise 1508 */ 1509 int bt_conn_auth_info_cb_register(struct bt_conn_auth_info_cb *cb); 1510 1511 /** @brief Unregister authentication information callbacks. 1512 * 1513 * Unregister callbacks to stop getting authenticated pairing information. 1514 * 1515 * @param cb Callback struct. 1516 * 1517 * @return Zero on success or negative error code otherwise 1518 */ 1519 int bt_conn_auth_info_cb_unregister(struct bt_conn_auth_info_cb *cb); 1520 1521 /** @brief Reply with entered passkey. 1522 * 1523 * This function should be called only after passkey_entry callback from 1524 * bt_conn_auth_cb structure was called. 1525 * 1526 * @param conn Connection object. 1527 * @param passkey Entered passkey. 1528 * 1529 * @return Zero on success or negative error code otherwise 1530 */ 1531 int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey); 1532 1533 /** @brief Send Passkey Keypress Notification during pairing 1534 * 1535 * This function may be called only after passkey_entry callback from 1536 * bt_conn_auth_cb structure was called. 1537 * 1538 * Requires @kconfig{CONFIG_BT_PASSKEY_KEYPRESS}. 1539 * 1540 * @param conn Destination for the notification. 1541 * @param type What keypress event type to send. @see bt_conn_auth_keypress. 1542 * 1543 * @retval 0 Success 1544 * @retval -EINVAL Improper use of the API. 1545 * @retval -ENOMEM Failed to allocate. 1546 * @retval -ENOBUFS Failed to allocate. 1547 */ 1548 int bt_conn_auth_keypress_notify(struct bt_conn *conn, enum bt_conn_auth_keypress type); 1549 1550 /** @brief Cancel ongoing authenticated pairing. 1551 * 1552 * This function allows to cancel ongoing authenticated pairing. 1553 * 1554 * @param conn Connection object. 1555 * 1556 * @return Zero on success or negative error code otherwise 1557 */ 1558 int bt_conn_auth_cancel(struct bt_conn *conn); 1559 1560 /** @brief Reply if passkey was confirmed to match by user. 1561 * 1562 * This function should be called only after passkey_confirm callback from 1563 * bt_conn_auth_cb structure was called. 1564 * 1565 * @param conn Connection object. 1566 * 1567 * @return Zero on success or negative error code otherwise 1568 */ 1569 int bt_conn_auth_passkey_confirm(struct bt_conn *conn); 1570 1571 /** @brief Reply if incoming pairing was confirmed by user. 1572 * 1573 * This function should be called only after pairing_confirm callback from 1574 * bt_conn_auth_cb structure was called if user confirmed incoming pairing. 1575 * 1576 * @param conn Connection object. 1577 * 1578 * @return Zero on success or negative error code otherwise 1579 */ 1580 int bt_conn_auth_pairing_confirm(struct bt_conn *conn); 1581 1582 /** @brief Reply with entered PIN code. 1583 * 1584 * This function should be called only after PIN code callback from 1585 * bt_conn_auth_cb structure was called. It's for legacy 2.0 devices. 1586 * 1587 * @param conn Connection object. 1588 * @param pin Entered PIN code. 1589 * 1590 * @return Zero on success or negative error code otherwise 1591 */ 1592 int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin); 1593 1594 /** Connection parameters for BR/EDR connections */ 1595 struct bt_br_conn_param { 1596 bool allow_role_switch; 1597 }; 1598 1599 /** @brief Initialize BR/EDR connection parameters 1600 * 1601 * @param role_switch True if role switch is allowed 1602 */ 1603 #define BT_BR_CONN_PARAM_INIT(role_switch) \ 1604 { \ 1605 .allow_role_switch = (role_switch), \ 1606 } 1607 1608 /** Helper to declare BR/EDR connection parameters inline 1609 * 1610 * @param role_switch True if role switch is allowed 1611 */ 1612 #define BT_BR_CONN_PARAM(role_switch) \ 1613 ((struct bt_br_conn_param[]) { \ 1614 BT_BR_CONN_PARAM_INIT(role_switch) \ 1615 }) 1616 1617 /** Default BR/EDR connection parameters: 1618 * Role switch allowed 1619 */ 1620 #define BT_BR_CONN_PARAM_DEFAULT BT_BR_CONN_PARAM(true) 1621 1622 1623 /** @brief Initiate an BR/EDR connection to a remote device. 1624 * 1625 * Allows initiate new BR/EDR link to remote peer using its address. 1626 * 1627 * The caller gets a new reference to the connection object which must be 1628 * released with bt_conn_unref() once done using the object. 1629 * 1630 * @param peer Remote address. 1631 * @param param Initial connection parameters. 1632 * 1633 * @return Valid connection object on success or NULL otherwise. 1634 */ 1635 struct bt_conn *bt_conn_create_br(const bt_addr_t *peer, 1636 const struct bt_br_conn_param *param); 1637 1638 /** @brief Initiate an SCO connection to a remote device. 1639 * 1640 * Allows initiate new SCO link to remote peer using its address. 1641 * 1642 * The caller gets a new reference to the connection object which must be 1643 * released with bt_conn_unref() once done using the object. 1644 * 1645 * @param peer Remote address. 1646 * 1647 * @return Valid connection object on success or NULL otherwise. 1648 */ 1649 struct bt_conn *bt_conn_create_sco(const bt_addr_t *peer); 1650 1651 #ifdef __cplusplus 1652 } 1653 #endif 1654 1655 /** 1656 * @} 1657 */ 1658 1659 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_ */ 1660
