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