LCOV - code coverage report
Current view: top level - zephyr/bluetooth - conn.h Coverage Total Hit
Test: new.info Lines: 88.5 % 355 314
Test Date: 2025-09-05 16:43:28

            Line data    Source code
       1            1 : /** @file
       2              :  *  @brief Bluetooth connection handling
       3              :  */
       4              : 
       5              : /*
       6              :  * Copyright (c) 2015-2016 Intel Corporation
       7              :  * Copyright (c) 2025 Nordic Semiconductor ASA
       8              :  *
       9              :  * SPDX-License-Identifier: Apache-2.0
      10              :  */
      11              : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_
      12              : #define ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_
      13              : 
      14              : /**
      15              :  * @brief Connection management
      16              :  * @defgroup bt_conn Connection management
      17              :  * @ingroup bluetooth
      18              :  * @{
      19              :  */
      20              : 
      21              : #include <stdbool.h>
      22              : #include <stdint.h>
      23              : 
      24              : #include <zephyr/bluetooth/addr.h>
      25              : #include <zephyr/bluetooth/bluetooth.h>
      26              : #include <zephyr/bluetooth/direction.h>
      27              : #include <zephyr/bluetooth/gap.h>
      28              : #include <zephyr/bluetooth/hci_types.h>
      29              : #include <zephyr/net_buf.h>
      30              : #include <zephyr/sys/iterable_sections.h>
      31              : #include <zephyr/sys/slist.h>
      32              : #include <zephyr/sys/util_macro.h>
      33              : #include <zephyr/toolchain.h>
      34              : 
      35              : #ifdef __cplusplus
      36              : extern "C" {
      37              : #endif
      38              : 
      39              : /** Opaque type representing a connection to a remote device */
      40              : struct bt_conn;
      41              : 
      42              : /** Connection parameters for LE connections */
      43            1 : struct bt_le_conn_param {
      44            0 :         uint16_t interval_min;
      45            0 :         uint16_t interval_max;
      46            0 :         uint16_t latency;
      47            0 :         uint16_t timeout;
      48              : };
      49              : 
      50              : /** @brief Initialize connection parameters
      51              :  *
      52              :  *  @param int_min  Minimum Connection Interval (N * 1.25 ms)
      53              :  *  @param int_max  Maximum Connection Interval (N * 1.25 ms)
      54              :  *  @param lat      Connection Latency
      55              :  *  @param to       Supervision Timeout (N * 10 ms)
      56              :  */
      57            1 : #define BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
      58              : { \
      59              :         .interval_min = (int_min), \
      60              :         .interval_max = (int_max), \
      61              :         .latency = (lat), \
      62              :         .timeout = (to), \
      63              : }
      64              : 
      65              : /** Helper to declare connection parameters inline
      66              :  *
      67              :  *  @param int_min  Minimum Connection Interval (N * 1.25 ms)
      68              :  *  @param int_max  Maximum Connection Interval (N * 1.25 ms)
      69              :  *  @param lat      Connection Latency
      70              :  *  @param to       Supervision Timeout (N * 10 ms)
      71              :  */
      72            1 : #define BT_LE_CONN_PARAM(int_min, int_max, lat, to) \
      73              :         ((struct bt_le_conn_param[]) { \
      74              :                 BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
      75              :          })
      76              : 
      77              : /** Default LE connection parameters:
      78              :  *    Connection Interval: 30-50 ms
      79              :  *    Latency: 0
      80              :  *    Timeout: 4 s
      81              :  */
      82            1 : #define BT_LE_CONN_PARAM_DEFAULT                                                                   \
      83              :         BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, BT_GAP_INIT_CONN_INT_MAX, 0,                    \
      84              :                          BT_GAP_MS_TO_CONN_TIMEOUT(4000))
      85              : 
      86              : /** Connection PHY information for LE connections */
      87            1 : struct bt_conn_le_phy_info {
      88            0 :         uint8_t tx_phy; /** Connection transmit PHY */
      89            1 :         uint8_t rx_phy; /** Connection receive PHY */
      90              : };
      91              : 
      92              : /** Connection PHY options */
      93            1 : enum {
      94              :         /** Convenience value when no options are specified. */
      95              :         BT_CONN_LE_PHY_OPT_NONE = 0,
      96              : 
      97              :         /** LE Coded using S=2 coding preferred when transmitting. */
      98              :         BT_CONN_LE_PHY_OPT_CODED_S2  = BIT(0),
      99              : 
     100              :         /** LE Coded using S=8 coding preferred when transmitting. */
     101              :         BT_CONN_LE_PHY_OPT_CODED_S8  = BIT(1),
     102              : };
     103              : 
     104              : /** Preferred PHY parameters for LE connections */
     105            1 : struct bt_conn_le_phy_param {
     106            1 :         uint16_t options; /**< Connection PHY options. */
     107            1 :         uint8_t  pref_tx_phy; /**< Bitmask of preferred transmit PHYs */
     108            1 :         uint8_t  pref_rx_phy; /**< Bitmask of preferred receive PHYs */
     109              : };
     110              : 
     111              : /** Initialize PHY parameters
     112              :  *
     113              :  * @param _pref_tx_phy Bitmask of preferred transmit PHYs.
     114              :  * @param _pref_rx_phy Bitmask of preferred receive PHYs.
     115              :  */
     116            1 : #define BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
     117              : { \
     118              :         .options = BT_CONN_LE_PHY_OPT_NONE, \
     119              :         .pref_tx_phy = (_pref_tx_phy), \
     120              :         .pref_rx_phy = (_pref_rx_phy), \
     121              : }
     122              : 
     123              : /** Helper to declare PHY parameters inline
     124              :  *
     125              :  * @param _pref_tx_phy Bitmask of preferred transmit PHYs.
     126              :  * @param _pref_rx_phy Bitmask of preferred receive PHYs.
     127              :  */
     128            1 : #define BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy) \
     129              :         ((struct bt_conn_le_phy_param []) { \
     130              :                 BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
     131              :          })
     132              : 
     133              : /** Only LE 1M PHY */
     134            1 : #define BT_CONN_LE_PHY_PARAM_1M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M, \
     135              :                                                      BT_GAP_LE_PHY_1M)
     136              : 
     137              : /** Only LE 2M PHY */
     138            1 : #define BT_CONN_LE_PHY_PARAM_2M BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_2M, \
     139              :                                                      BT_GAP_LE_PHY_2M)
     140              : 
     141              : /** Only LE Coded PHY. */
     142            1 : #define BT_CONN_LE_PHY_PARAM_CODED BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_CODED, \
     143              :                                                         BT_GAP_LE_PHY_CODED)
     144              : 
     145              : /** All LE PHYs. */
     146            1 : #define BT_CONN_LE_PHY_PARAM_ALL BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M |   \
     147              :                                                       BT_GAP_LE_PHY_2M |   \
     148              :                                                       BT_GAP_LE_PHY_CODED, \
     149              :                                                       BT_GAP_LE_PHY_1M |   \
     150              :                                                       BT_GAP_LE_PHY_2M |   \
     151              :                                                       BT_GAP_LE_PHY_CODED)
     152              : 
     153              : /** Connection data length information for LE connections */
     154            1 : struct bt_conn_le_data_len_info {
     155              :         /** Maximum Link Layer transmission payload size in bytes. */
     156            1 :         uint16_t tx_max_len;
     157              :         /** Maximum Link Layer transmission payload time in us. */
     158            1 :         uint16_t tx_max_time;
     159              :         /** Maximum Link Layer reception payload size in bytes. */
     160            1 :         uint16_t rx_max_len;
     161              :         /** Maximum Link Layer reception payload time in us. */
     162            1 :         uint16_t rx_max_time;
     163              : };
     164              : 
     165              : /** Connection data length parameters for LE connections */
     166            1 : struct bt_conn_le_data_len_param {
     167              :         /** Maximum Link Layer transmission payload size in bytes. */
     168            1 :         uint16_t tx_max_len;
     169              :         /** Maximum Link Layer transmission payload time in us. */
     170            1 :         uint16_t tx_max_time;
     171              : };
     172              : 
     173              : /** Initialize transmit data length parameters
     174              :  *
     175              :  * @param  _tx_max_len  Maximum Link Layer transmission payload size in bytes.
     176              :  * @param  _tx_max_time Maximum Link Layer transmission payload time in us.
     177              :  */
     178            1 : #define BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
     179              : { \
     180              :         .tx_max_len = (_tx_max_len), \
     181              :         .tx_max_time = (_tx_max_time), \
     182              : }
     183              : 
     184              : /** Helper to declare transmit data length parameters inline
     185              :  *
     186              :  * @param  _tx_max_len  Maximum Link Layer transmission payload size in bytes.
     187              :  * @param  _tx_max_time Maximum Link Layer transmission payload time in us.
     188              :  */
     189            1 : #define BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time) \
     190              :         ((struct bt_conn_le_data_len_param[]) { \
     191              :                 BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
     192              :          })
     193              : 
     194              : /** Default LE data length parameters. */
     195            1 : #define BT_LE_DATA_LEN_PARAM_DEFAULT \
     196              :         BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_DEFAULT, \
     197              :                                   BT_GAP_DATA_TIME_DEFAULT)
     198              : 
     199              : /** Maximum LE data length parameters. */
     200            1 : #define BT_LE_DATA_LEN_PARAM_MAX \
     201              :         BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_MAX, \
     202              :                                   BT_GAP_DATA_TIME_MAX)
     203              : 
     204              : /** Connection subrating parameters for LE connections */
     205            1 : struct bt_conn_le_subrate_param {
     206              :         /** Minimum subrate factor. */
     207            1 :         uint16_t subrate_min;
     208              :         /** Maximum subrate factor. */
     209            1 :         uint16_t subrate_max;
     210              :         /** Maximum Peripheral latency in units of subrated connection intervals. */
     211            1 :         uint16_t max_latency;
     212              :         /** Minimum number of underlying connection events to remain active
     213              :          *  after a packet containing a Link Layer PDU with a non-zero Length
     214              :          *  field is sent or received.
     215              :          */
     216            1 :         uint16_t continuation_number;
     217              :         /** Connection Supervision timeout (N * 10 ms).
     218              :          *  If using @ref bt_conn_le_subrate_set_defaults, this is the
     219              :          *  maximum supervision timeout allowed in requests by a peripheral.
     220              :          */
     221            1 :         uint16_t supervision_timeout;
     222              : };
     223              : 
     224              : /** Subrating information for LE connections */
     225            1 : struct bt_conn_le_subrating_info {
     226              :         /** Connection subrate factor. */
     227            1 :         uint16_t factor;
     228              :         /** Number of underlying connection events to remain active after
     229              :          *  a packet containing a Link Layer PDU with a non-zero Length
     230              :          *  field is sent or received.
     231              :          */
     232            1 :         uint16_t continuation_number;
     233              : };
     234              : 
     235              : /** Updated subrating connection parameters for LE connections */
     236            1 : struct bt_conn_le_subrate_changed {
     237              :         /** HCI Status from LE Subrate Changed event.
     238              :          *  The remaining parameters will be unchanged if status is not
     239              :          *  BT_HCI_ERR_SUCCESS.
     240              :          */
     241            1 :         uint8_t status;
     242              :         /** Connection subrate factor. */
     243            1 :         uint16_t factor;
     244              :         /** Number of underlying connection events to remain active after
     245              :          *  a packet containing a Link Layer PDU with a non-zero Length
     246              :          *  field is sent or received.
     247              :          */
     248            1 :         uint16_t continuation_number;
     249              :         /** Peripheral latency in units of subrated connection intervals. */
     250            1 :         uint16_t peripheral_latency;
     251              :         /** Connection Supervision timeout (N * 10 ms). */
     252            1 :         uint16_t supervision_timeout;
     253              : };
     254              : 
     255              : /** Read all remote features complete callback params */
     256            1 : struct bt_conn_le_read_all_remote_feat_complete {
     257              :         /** @brief  HCI Status from LE Read All Remote Features Complete event.
     258              :          *
     259              :          *  The remaining parameters will be unchanged if status is not @ref BT_HCI_ERR_SUCCESS.
     260              :          */
     261            1 :         uint8_t status;
     262              :         /** Number of pages supported by remote device. */
     263            1 :         uint8_t max_remote_page;
     264              :         /** Number of pages fetched from remote device. */
     265            1 :         uint8_t max_valid_page;
     266              :         /** @brief Pointer to array of size 248, with feature bits of remote supported features.
     267              :          *
     268              :          *  Page 0 being 8 bytes, with the following 10 pages of 24 bytes.
     269              :          *  Refer to BT_LE_FEAT_BIT_* for values.
     270              :          *  Refer to the BT_FEAT_LE_* macros for value comparison.
     271              :          *  See Bluetooth Core Specification, Vol 6, Part B, Section 4.6.
     272              :          */
     273            1 :         const uint8_t *features;
     274              : };
     275              : 
     276            0 : #define BT_CONN_LE_FRAME_SPACE_TYPES_MASK_ACL_IFS                    \
     277              :         (BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_IFS_ACL_CP_MASK | \
     278              :          BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_IFS_ACL_PC_MASK)
     279              : 
     280            0 : #define BT_CONN_LE_FRAME_SPACE_TYPES_MASK_ACL                        \
     281              :         (BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_IFS_ACL_CP_MASK | \
     282              :          BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_IFS_ACL_PC_MASK | \
     283              :          BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_MCES_MASK)
     284              : 
     285            0 : #define BT_CONN_LE_FRAME_SPACE_TYPES_MASK_CIS                     \
     286              :         (BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_IFS_CIS_MASK | \
     287              :          BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_MSS_CIS_MASK)
     288              : 
     289              : /** Maximum frame space in microseconds.
     290              :  *  As defined in Bluetooth Core Specification, Vol 4, Part E, Section 7.8.151.
     291              :  */
     292            1 : #define BT_CONN_LE_FRAME_SPACE_MAX (10000U)
     293              : 
     294              : /** Frame space update initiator. */
     295            1 : enum bt_conn_le_frame_space_update_initiator {
     296              :         /** Initiated by local host */
     297              :         BT_CONN_LE_FRAME_SPACE_UPDATE_INITIATOR_LOCAL_HOST =
     298              :                 BT_HCI_LE_FRAME_SPACE_UPDATE_INITIATOR_LOCAL_HOST,
     299              :         /** Initiated by local controller */
     300              :         BT_CONN_LE_FRAME_SPACE_UPDATE_INITIATOR_LOCAL_CONTROLLER =
     301              :                 BT_HCI_LE_FRAME_SPACE_UPDATE_INITIATOR_LOCAL_CONTROLLER,
     302              :         /** Initiated by peer */
     303              :         BT_CONN_LE_FRAME_SPACE_UPDATE_INITIATOR_PEER =
     304              :                 BT_HCI_LE_FRAME_SPACE_UPDATE_INITIATOR_PEER
     305              : };
     306              : 
     307              : /** Frame space update params */
     308            1 : struct bt_conn_le_frame_space_update_param {
     309              :         /** Phy mask of the PHYs to be updated.
     310              :          *  Refer to BT_HCI_LE_FRAME_SPACE_UPDATE_PHY_* for values.
     311              :          */
     312            1 :         uint8_t phys;
     313              :         /** Spacing types mask of the spacing types to be updated.
     314              :          *  Refer to BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_* and
     315              :          *  BT_CONN_LE_FRAME_SPACE_TYPES_MASK_* for values.
     316              :          */
     317            1 :         uint16_t spacing_types;
     318              :         /** Minimum frame space in microseconds.
     319              :          *  Bluetooth Core Specification, Vol 4, Part E, Section 7.8.151
     320              :          *  allows for a range of frame space from 0 to 10000 microseconds.
     321              :          *  The actual supported frame space values will be dependent on
     322              :          *  the controller's capabilities.
     323              :          */
     324            1 :         uint16_t frame_space_min;
     325              :         /** Maximum frame space in microseconds.
     326              :          *  Bluetooth Core Specification, Vol 4, Part E, Section 7.8.151
     327              :          *  allows for a range of frame space from 0 to 10000 microseconds.
     328              :          *  The actual supported frame space values will be dependent on
     329              :          *  the controller's capabilities.
     330              :          */
     331            1 :         uint16_t frame_space_max;
     332              : };
     333              : 
     334              : /** Frame space updated callback params */
     335            1 : struct bt_conn_le_frame_space_updated {
     336              :         /** HCI Status from LE Frame Space Update Complete event.
     337              :          *  The remaining parameters will be invalid if status is not
     338              :          *  @ref BT_HCI_ERR_SUCCESS.
     339              :          */
     340            1 :         uint8_t status;
     341              :         /** Initiator of the frame space update. */
     342            1 :         enum bt_conn_le_frame_space_update_initiator initiator;
     343              :         /** Updated frame space in microseconds. */
     344            1 :         uint16_t frame_space;
     345              :         /** Phy mask of the PHYs updated.
     346              :          *  Refer to BT_HCI_LE_FRAME_SPACE_UPDATE_PHY_* for values.
     347              :          */
     348            1 :         uint8_t phys;
     349              :         /** Spacing types mask of the spacing types updated.
     350              :          *  Refer to BT_HCI_LE_FRAME_SPACE_UPDATE_SPACING_TYPE_* and
     351              :          *  BT_CONN_LE_FRAME_SPACE_TYPES_MASK_* for values.
     352              :          */
     353            1 :         uint16_t spacing_types;
     354              : };
     355              : 
     356              : /** Connection Type */
     357            1 : enum __packed bt_conn_type {
     358              :         /** LE Connection Type */
     359              :         BT_CONN_TYPE_LE = BIT(0),
     360              :         /** BR/EDR Connection Type */
     361              :         BT_CONN_TYPE_BR = BIT(1),
     362              :         /** SCO Connection Type */
     363              :         BT_CONN_TYPE_SCO = BIT(2),
     364              :         /** ISO Connection Type */
     365              :         BT_CONN_TYPE_ISO = BIT(3),
     366              :         /** All Connection Type */
     367              :         BT_CONN_TYPE_ALL = BT_CONN_TYPE_LE | BT_CONN_TYPE_BR |
     368              :                            BT_CONN_TYPE_SCO | BT_CONN_TYPE_ISO,
     369              : };
     370              : 
     371              : /** Supported AA-Only RTT precision. */
     372            1 : enum bt_conn_le_cs_capability_rtt_aa_only {
     373              :         /** AA-Only RTT variant is not supported. */
     374              :         BT_CONN_LE_CS_RTT_AA_ONLY_NOT_SUPP = 0,
     375              :         /** 10ns time-of-flight accuracy. */
     376              :         BT_CONN_LE_CS_RTT_AA_ONLY_10NS,
     377              :         /** 150ns time-of-flight accuracy. */
     378              :         BT_CONN_LE_CS_RTT_AA_ONLY_150NS,
     379              : };
     380              : 
     381              : /** Supported Sounding Sequence RTT precision. */
     382            1 : enum bt_conn_le_cs_capability_rtt_sounding {
     383              :         /** Sounding Sequence RTT variant is not supported. */
     384              :         BT_CONN_LE_CS_RTT_SOUNDING_NOT_SUPP = 0,
     385              :         /** 10ns time-of-flight accuracy. */
     386              :         BT_CONN_LE_CS_RTT_SOUNDING_10NS,
     387              :         /** 150ns time-of-flight accuracy. */
     388              :         BT_CONN_LE_CS_RTT_SOUNDING_150NS,
     389              : };
     390              : 
     391              : /** Supported Random Payload RTT precision. */
     392            1 : enum bt_conn_le_cs_capability_rtt_random_payload {
     393              :         /** Random Payload RTT variant is not supported. */
     394              :         BT_CONN_LE_CS_RTT_RANDOM_PAYLOAD_NOT_SUPP = 0,
     395              :         /** 10ns time-of-flight accuracy. */
     396              :         BT_CONN_LE_CS_RTT_RANDOM_PAYLOAD_10NS,
     397              :         /** 150ns time-of-flight accuracy. */
     398              :         BT_CONN_LE_CS_RTT_RANDOM_PAYLOAD_150NS,
     399              : };
     400              : 
     401              : /** Remote channel sounding capabilities for LE connections supporting CS */
     402            1 : struct bt_conn_le_cs_capabilities {
     403              :         /** Number of CS configurations */
     404            1 :         uint8_t num_config_supported;
     405              :         /** Maximum number of consecutive CS procedures.
     406              :          *
     407              :          * When set to zero, indicates support for both fixed and indefinite
     408              :          * numbers of CS procedures before termination.
     409              :          */
     410            1 :         uint16_t max_consecutive_procedures_supported;
     411              :         /** Number of antennas. */
     412            1 :         uint8_t num_antennas_supported;
     413              :         /** Maximum number of antenna paths. */
     414            1 :         uint8_t max_antenna_paths_supported;
     415              :         /** Initiator role. */
     416            1 :         bool initiator_supported;
     417              :         /** Reflector role. */
     418            1 :         bool reflector_supported;
     419              :         /** Mode-3 */
     420            1 :         bool mode_3_supported;
     421              :         /** RTT AA-Only */
     422            1 :         enum bt_conn_le_cs_capability_rtt_aa_only rtt_aa_only_precision;
     423              :         /** RTT Sounding */
     424            1 :         enum bt_conn_le_cs_capability_rtt_sounding rtt_sounding_precision;
     425              :         /** RTT Random Payload */
     426            1 :         enum bt_conn_le_cs_capability_rtt_random_payload rtt_random_payload_precision;
     427              :         /** Number of CS steps needed to achieve the
     428              :          * accuracy requirements for RTT AA Only.
     429              :          *
     430              :          * Set to 0 if RTT AA Only isn't supported.
     431              :          */
     432            1 :         uint8_t rtt_aa_only_n;
     433              :         /** Number of CS steps needed to achieve the
     434              :          * accuracy requirements for RTT Sounding.
     435              :          *
     436              :          * Set to 0 if RTT Sounding isn't supported
     437              :          */
     438            1 :         uint8_t rtt_sounding_n;
     439              :         /** Number of CS steps needed to achieve the
     440              :          * accuracy requirements for RTT Random Payload.
     441              :          *
     442              :          * Set to 0 if RTT Random Payload isn't supported.
     443              :          */
     444            1 :         uint8_t rtt_random_payload_n;
     445              :         /** Phase-based normalized attack detector metric
     446              :          * when a CS_SYNC with sounding sequence is received.
     447              :          */
     448            1 :         bool phase_based_nadm_sounding_supported;
     449              :         /** Phase-based normalized attack detector metric
     450              :          * when a CS_SYNC with random sequence is received.
     451              :          */
     452            1 :         bool phase_based_nadm_random_supported;
     453              :         /** CS_SYNC LE 2M PHY. */
     454            1 :         bool cs_sync_2m_phy_supported;
     455              :         /** CS_SYNC LE 2M 2BT PHY. */
     456            1 :         bool cs_sync_2m_2bt_phy_supported;
     457              :         /** Subfeature: CS with no Frequency Actuation Error. */
     458            1 :         bool cs_without_fae_supported;
     459              :         /** Subfeature: Channel Selection Algorithm #3c */
     460            1 :         bool chsel_alg_3c_supported;
     461              :         /** Subfeature: Phase-based Ranging from RTT sounding sequence. */
     462            1 :         bool pbr_from_rtt_sounding_seq_supported;
     463              :         /** Optional T_IP1 time durations during CS steps.
     464              :          *
     465              :          *  - Bit 0: 10 us
     466              :          *  - Bit 1: 20 us
     467              :          *  - Bit 2: 30 us
     468              :          *  - Bit 3: 40 us
     469              :          *  - Bit 4: 50 us
     470              :          *  - Bit 5: 60 us
     471              :          *  - Bit 6: 80 us
     472              :          */
     473            1 :         uint16_t t_ip1_times_supported;
     474              :         /** Optional T_IP2 time durations during CS steps.
     475              :          *
     476              :          *  - Bit 0: 10 us
     477              :          *  - Bit 1: 20 us
     478              :          *  - Bit 2: 30 us
     479              :          *  - Bit 3: 40 us
     480              :          *  - Bit 4: 50 us
     481              :          *  - Bit 5: 60 us
     482              :          *  - Bit 6: 80 us
     483              :          */
     484            1 :         uint16_t t_ip2_times_supported;
     485              :         /** Optional T_FCS time durations during CS steps.
     486              :          *
     487              :          *  - Bit 0: 15 us
     488              :          *  - Bit 1: 20 us
     489              :          *  - Bit 2: 30 us
     490              :          *  - Bit 3: 40 us
     491              :          *  - Bit 4: 50 us
     492              :          *  - Bit 5: 60 us
     493              :          *  - Bit 6: 80 us
     494              :          *  - Bit 7: 100 us
     495              :          *  - Bit 8: 120 us
     496              :          */
     497            1 :         uint16_t t_fcs_times_supported;
     498              :         /** Optional T_PM time durations during CS steps.
     499              :          *
     500              :          *  - Bit 0: 10 us
     501              :          *  - Bit 1: 20 us
     502              :          */
     503            1 :         uint16_t t_pm_times_supported;
     504              :         /** Time in microseconds for the antenna switch period of the CS tones. */
     505            1 :         uint8_t t_sw_time;
     506              :         /** Supported SNR levels used in RTT packets.
     507              :          *
     508              :          *  - Bit 0: 18dB
     509              :          *  - Bit 1: 21dB
     510              :          *  - Bit 2: 24dB
     511              :          *  - Bit 3: 27dB
     512              :          *  - Bit 4: 30dB
     513              :          */
     514            1 :         uint8_t tx_snr_capability;
     515              : };
     516              : 
     517              : /** Remote FAE Table for LE connections supporting CS */
     518            1 : struct bt_conn_le_cs_fae_table {
     519            0 :         int8_t *remote_fae_table;
     520              : };
     521              : 
     522              : /** @brief Extract main mode part from @ref bt_conn_le_cs_mode
     523              :  *
     524              :  * @private
     525              :  *
     526              :  * @param x @ref bt_conn_le_cs_mode value
     527              :  * @retval 1 Matches @ref BT_HCI_OP_LE_CS_MAIN_MODE_1 (0x01)
     528              :  * @retval 2 Matches @ref BT_HCI_OP_LE_CS_MAIN_MODE_2 (0x02)
     529              :  * @retval 3 Matches @ref BT_HCI_OP_LE_CS_MAIN_MODE_3 (0x03)
     530              :  *
     531              :  * @note Returned values match the HCI main mode values.
     532              :  */
     533            1 : #define BT_CONN_LE_CS_MODE_MAIN_MODE_PART(x) ((x) & 0x3)
     534              : 
     535              : /** @brief Extract sub-mode part from @ref bt_conn_le_cs_mode
     536              :  *
     537              :  * @private
     538              :  *
     539              :  * @param x @ref bt_conn_le_cs_mode value
     540              :  * @retval 0 Internal encoding for @ref BT_HCI_OP_LE_CS_SUB_MODE_UNUSED (0xFF)
     541              :  * @retval 1 Matches @ref BT_HCI_OP_LE_CS_SUB_MODE_1 (0x01)
     542              :  * @retval 2 Matches @ref BT_HCI_OP_LE_CS_SUB_MODE_2 (0x02)
     543              :  * @retval 3 Matches @ref BT_HCI_OP_LE_CS_SUB_MODE_3 (0x03)
     544              :  *
     545              :  * @note The value 0 encodes HCI 0xFF. This allows @ref bt_conn_le_cs_mode to
     546              :  * fit in one byte. To obtain the HCI sub-mode value, use `(sub_mode == 0 ? 0xFF
     547              :  * : sub_mode)`, where `sub_mode` is the value returned by this macro.
     548              :  */
     549            1 : #define BT_CONN_LE_CS_MODE_SUB_MODE_PART(x)  (((x) >> 4) & 0x3)
     550              : 
     551              : /** @brief Channel sounding mode (main and sub-mode)
     552              :  *
     553              :  * Represents the combination of Channel Sounding (CS) main mode and sub-mode.
     554              :  *
     555              :  * @note The underlying numeric values are an internal encoding and are
     556              :  * not stable API. Do not assume a direct concatenation of HCI values
     557              :  * when inspecting the raw enum value.
     558              :  *
     559              :  * @sa BT_CONN_LE_CS_MODE_MAIN_MODE_PART
     560              :  * @sa BT_CONN_LE_CS_MODE_SUB_MODE_PART
     561              :  */
     562            1 : enum bt_conn_le_cs_mode {
     563              :         /** Main mode 1 (RTT), sub-mode: unused */
     564              :         BT_CONN_LE_CS_MAIN_MODE_1_NO_SUB_MODE = BT_HCI_OP_LE_CS_MAIN_MODE_1,
     565              :         /** Main mode 2 (PBR), sub-mode: unused */
     566              :         BT_CONN_LE_CS_MAIN_MODE_2_NO_SUB_MODE = BT_HCI_OP_LE_CS_MAIN_MODE_2,
     567              :         /** Main mode 3 (RTT and PBR), sub-mode: unused */
     568              :         BT_CONN_LE_CS_MAIN_MODE_3_NO_SUB_MODE = BT_HCI_OP_LE_CS_MAIN_MODE_3,
     569              :         /** Main mode 2 (PBR), sub-mode 1 (RTT) */
     570              :         BT_CONN_LE_CS_MAIN_MODE_2_SUB_MODE_1 = BT_HCI_OP_LE_CS_MAIN_MODE_2 |
     571              :                                               (BT_HCI_OP_LE_CS_SUB_MODE_1 << 4),
     572              :         /** Main mode 2 (PBR), sub-mode 3 (RTT and PBR) */
     573              :         BT_CONN_LE_CS_MAIN_MODE_2_SUB_MODE_3 = BT_HCI_OP_LE_CS_MAIN_MODE_2 |
     574              :                                               (BT_HCI_OP_LE_CS_SUB_MODE_3 << 4),
     575              :         /** Main mode 3 (RTT and PBR), sub-mode 2 (PBR) */
     576              :         BT_CONN_LE_CS_MAIN_MODE_3_SUB_MODE_2 = BT_HCI_OP_LE_CS_MAIN_MODE_3 |
     577              :                                               (BT_HCI_OP_LE_CS_SUB_MODE_2 << 4),
     578              : };
     579              : 
     580              : /** Channel sounding role */
     581            1 : enum bt_conn_le_cs_role {
     582              :         /** CS initiator role */
     583              :         BT_CONN_LE_CS_ROLE_INITIATOR,
     584              :         /** CS reflector role */
     585              :         BT_CONN_LE_CS_ROLE_REFLECTOR,
     586              : };
     587              : 
     588              : /** Channel sounding RTT type */
     589            1 : enum bt_conn_le_cs_rtt_type {
     590              :         /** RTT AA only */
     591              :         BT_CONN_LE_CS_RTT_TYPE_AA_ONLY = BT_HCI_OP_LE_CS_RTT_TYPE_AA_ONLY,
     592              :         /** RTT with 32-bit sounding sequence */
     593              :         BT_CONN_LE_CS_RTT_TYPE_32_BIT_SOUNDING = BT_HCI_OP_LE_CS_RTT_TYPE_32BIT_SOUND,
     594              :         /** RTT with 96-bit sounding sequence */
     595              :         BT_CONN_LE_CS_RTT_TYPE_96_BIT_SOUNDING = BT_HCI_OP_LE_CS_RTT_TYPE_96BIT_SOUND,
     596              :         /** RTT with 32-bit random sequence */
     597              :         BT_CONN_LE_CS_RTT_TYPE_32_BIT_RANDOM = BT_HCI_OP_LE_CS_RTT_TYPE_32BIT_RAND,
     598              :         /** RTT with 64-bit random sequence */
     599              :         BT_CONN_LE_CS_RTT_TYPE_64_BIT_RANDOM = BT_HCI_OP_LE_CS_RTT_TYPE_64BIT_RAND,
     600              :         /** RTT with 96-bit random sequence */
     601              :         BT_CONN_LE_CS_RTT_TYPE_96_BIT_RANDOM = BT_HCI_OP_LE_CS_RTT_TYPE_96BIT_RAND,
     602              :         /** RTT with 128-bit random sequence */
     603              :         BT_CONN_LE_CS_RTT_TYPE_128_BIT_RANDOM = BT_HCI_OP_LE_CS_RTT_TYPE_128BIT_RAND,
     604              : };
     605              : 
     606              : /** Channel sounding PHY used for CS sync */
     607            1 : enum bt_conn_le_cs_sync_phy {
     608              :         /** LE 1M PHY */
     609              :         BT_CONN_LE_CS_SYNC_1M_PHY = BT_HCI_OP_LE_CS_CS_SYNC_1M,
     610              :         /** LE 2M PHY */
     611              :         BT_CONN_LE_CS_SYNC_2M_PHY = BT_HCI_OP_LE_CS_CS_SYNC_2M,
     612              :         /** LE 2M 2BT PHY */
     613              :         BT_CONN_LE_CS_SYNC_2M_2BT_PHY = BT_HCI_OP_LE_CS_CS_SYNC_2M_2BT,
     614              : };
     615              : 
     616              : /** Channel sounding channel selection type */
     617            1 : enum bt_conn_le_cs_chsel_type {
     618              :         /** Use Channel Selection Algorithm #3b for non-mode-0 CS steps */
     619              :         BT_CONN_LE_CS_CHSEL_TYPE_3B = BT_HCI_OP_LE_CS_TEST_CHSEL_TYPE_3B,
     620              :         /** Use Channel Selection Algorithm #3c for non-mode-0 CS steps */
     621              :         BT_CONN_LE_CS_CHSEL_TYPE_3C = BT_HCI_OP_LE_CS_TEST_CHSEL_TYPE_3C,
     622              : };
     623              : 
     624              : /** Channel sounding channel sequence shape */
     625            1 : enum bt_conn_le_cs_ch3c_shape {
     626              :         /** Use Hat shape for user-specified channel sequence */
     627              :         BT_CONN_LE_CS_CH3C_SHAPE_HAT = BT_HCI_OP_LE_CS_TEST_CH3C_SHAPE_HAT,
     628              :         /** Use X shape for user-specified channel sequence */
     629              :         BT_CONN_LE_CS_CH3C_SHAPE_X = BT_HCI_OP_LE_CS_TEST_CH3C_SHAPE_X,
     630              : };
     631              : 
     632              : /** Channel sounding configuration */
     633            1 : struct bt_conn_le_cs_config {
     634              :         /** CS configuration ID */
     635            1 :         uint8_t id;
     636              :         /** CS main and sub mode */
     637            1 :         enum bt_conn_le_cs_mode mode;
     638              :         /** Minimum number of CS main mode steps to be executed before a submode step is executed */
     639            1 :         uint8_t min_main_mode_steps;
     640              :         /** Maximum number of CS main mode steps to be executed before a submode step is executed */
     641            1 :         uint8_t max_main_mode_steps;
     642              :         /** Number of main mode steps taken from the end of the last CS subevent to be repeated
     643              :          *  at the beginning of the current CS subevent directly after the last mode-0 step of that
     644              :          *  event
     645              :          */
     646            1 :         uint8_t main_mode_repetition;
     647              :         /** Number of CS mode-0 steps to be included at the beginning of each CS subevent */
     648            1 :         uint8_t mode_0_steps;
     649              :         /** CS role */
     650            1 :         enum bt_conn_le_cs_role role;
     651              :         /** RTT type */
     652            1 :         enum bt_conn_le_cs_rtt_type rtt_type;
     653              :         /** CS Sync PHY */
     654            1 :         enum bt_conn_le_cs_sync_phy cs_sync_phy;
     655              :         /** The number of times the Channel_Map field will be cycled through for non-mode-0 steps
     656              :          *  within a CS procedure
     657              :          */
     658            1 :         uint8_t channel_map_repetition;
     659              :         /** Channel selection type */
     660            1 :         enum bt_conn_le_cs_chsel_type channel_selection_type;
     661              :         /** User-specified channel sequence shape */
     662            1 :         enum bt_conn_le_cs_ch3c_shape ch3c_shape;
     663              :         /** Number of channels skipped in each rising and falling sequence  */
     664            1 :         uint8_t ch3c_jump;
     665              :         /** Interlude time in microseconds between the RTT packets */
     666            1 :         uint8_t t_ip1_time_us;
     667              :         /** Interlude time in microseconds between the CS tones */
     668            1 :         uint8_t t_ip2_time_us;
     669              :         /** Time in microseconds for frequency changes */
     670            1 :         uint8_t t_fcs_time_us;
     671              :         /** Time in microseconds for the phase measurement period of the CS tones */
     672            1 :         uint8_t t_pm_time_us;
     673              :         /** Channel map used for CS procedure
     674              :          *  Channels n = 0, 1, 23, 24, 25, 77, and 78 are not allowed and shall be set to zero.
     675              :          *  Channel 79 is reserved for future use and shall be set to zero.
     676              :          *  At least 15 channels shall be enabled.
     677              :          */
     678            1 :         uint8_t channel_map[10];
     679              : };
     680              : 
     681              : /** Procedure done status */
     682            0 : enum bt_conn_le_cs_procedure_done_status {
     683              :         BT_CONN_LE_CS_PROCEDURE_COMPLETE = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_COMPLETE,
     684              :         BT_CONN_LE_CS_PROCEDURE_INCOMPLETE = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_PARTIAL,
     685              :         BT_CONN_LE_CS_PROCEDURE_ABORTED = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_ABORTED,
     686              : };
     687              : 
     688              : /** Subevent done status */
     689            0 : enum bt_conn_le_cs_subevent_done_status {
     690              :         BT_CONN_LE_CS_SUBEVENT_COMPLETE = BT_HCI_LE_CS_SUBEVENT_DONE_STATUS_COMPLETE,
     691              :         BT_CONN_LE_CS_SUBEVENT_ABORTED = BT_HCI_LE_CS_SUBEVENT_DONE_STATUS_ABORTED,
     692              : };
     693              : 
     694              : /** Procedure abort reason */
     695            0 : enum bt_conn_le_cs_procedure_abort_reason {
     696              :         BT_CONN_LE_CS_PROCEDURE_NOT_ABORTED = BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_NO_ABORT,
     697              :         BT_CONN_LE_CS_PROCEDURE_ABORT_REQUESTED =
     698              :                 BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_LOCAL_HOST_OR_REMOTE_REQUEST,
     699              :         BT_CONN_LE_CS_PROCEDURE_ABORT_TOO_FEW_CHANNELS =
     700              :                 BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_TOO_FEW_CHANNELS,
     701              :         BT_CONN_LE_CS_PROCEDURE_ABORT_CHMAP_INSTANT_PASSED =
     702              :                 BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_CHMAP_INSTANT_PASSED,
     703              :         BT_CONN_LE_CS_PROCEDURE_ABORT_UNSPECIFIED = BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_UNSPECIFIED,
     704              : };
     705              : 
     706              : /** Subevent abort reason */
     707            0 : enum bt_conn_le_cs_subevent_abort_reason {
     708              :         BT_CONN_LE_CS_SUBEVENT_NOT_ABORTED = BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_NO_ABORT,
     709              :         BT_CONN_LE_CS_SUBEVENT_ABORT_REQUESTED =
     710              :                 BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_LOCAL_HOST_OR_REMOTE_REQUEST,
     711              :         BT_CONN_LE_CS_SUBEVENT_ABORT_NO_CS_SYNC =
     712              :                 BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_NO_CS_SYNC_RECEIVED,
     713              :         BT_CONN_LE_CS_SUBEVENT_ABORT_SCHED_CONFLICT =
     714              :                 BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_SCHED_CONFLICT,
     715              :         BT_CONN_LE_CS_SUBEVENT_ABORT_UNSPECIFIED = BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_UNSPECIFIED,
     716              : };
     717              : 
     718              : /** Subevent data for LE connections supporting CS */
     719            1 : struct bt_conn_le_cs_subevent_result {
     720              :         struct {
     721              :                 /** CS configuration identifier.
     722              :                  *
     723              :                  *  Range: 0 to 3
     724              :                  *
     725              :                  *  If these results were generated by a CS Test,
     726              :                  *  this value will be set to 0 and has no meaning.
     727              :                  */
     728            1 :                 uint8_t config_id;
     729              :                 /** Starting ACL connection event counter.
     730              :                  *
     731              :                  *  If these results were generated by a CS Test,
     732              :                  *  this value will be set to 0 and has no meaning.
     733              :                  */
     734            1 :                 uint16_t start_acl_conn_event;
     735              :                 /** CS procedure count associated with these results.
     736              :                  *
     737              :                  *  This is the CS procedure count since the completion of
     738              :                  *  the Channel Sounding Security Start procedure.
     739              :                  */
     740            1 :                 uint16_t procedure_counter;
     741              :                 /** Frequency compensation value in units of 0.01 ppm.
     742              :                  *
     743              :                  *  This is a 15-bit signed integer in the range [-100, 100] ppm.
     744              :                  *
     745              :                  *  A value of @ref BT_HCI_LE_CS_SUBEVENT_RESULT_FREQ_COMPENSATION_NOT_AVAILABLE
     746              :                  *  indicates that the role is not the initiator, or that the
     747              :                  *  frequency compensation value is unavailable.
     748              :                  */
     749            1 :                 uint16_t frequency_compensation;
     750              :                 /** Reference power level in dBm.
     751              :                  *
     752              :                  *  Range: -127 to 20
     753              :                  *
     754              :                  *  A value of @ref BT_HCI_LE_CS_REF_POWER_LEVEL_UNAVAILABLE indicates
     755              :                  *  that the reference power level was not available during a subevent.
     756              :                  */
     757            1 :                 int8_t reference_power_level;
     758              :                 /** Procedure status. */
     759            1 :                 enum bt_conn_le_cs_procedure_done_status procedure_done_status;
     760              :                 /** Subevent status
     761              :                  *
     762              :                  *  For aborted subevents, this will be set to @ref BT_CONN_LE_CS_SUBEVENT_ABORTED
     763              :                  *  and abort_step will contain the step number on which the subevent was aborted.
     764              :                  *  Consider the following example:
     765              :                  *
     766              :                  *  subevent_done_status = @ref BT_CONN_LE_CS_SUBEVENT_ABORTED
     767              :                  *  num_steps_reported = 160
     768              :                  *  abort_step = 100
     769              :                  *
     770              :                  *  this would mean that steps from 0 to 99 are complete and steps from 100 to 159
     771              :                  *  are aborted.
     772              :                  */
     773            1 :                 enum bt_conn_le_cs_subevent_done_status subevent_done_status;
     774              :                 /** Abort reason.
     775              :                  *
     776              :                  *  If the procedure status is
     777              :                  *  @ref BT_CONN_LE_CS_PROCEDURE_ABORTED, this field will
     778              :                  *  specify the reason for the abortion.
     779              :                  */
     780            1 :                 enum bt_conn_le_cs_procedure_abort_reason procedure_abort_reason;
     781              :                 /** Abort reason.
     782              :                  *
     783              :                  *  If the subevent status is
     784              :                  *  @ref BT_CONN_LE_CS_SUBEVENT_ABORTED, this field will
     785              :                  *  specify the reason for the abortion.
     786              :                  */
     787            1 :                 enum bt_conn_le_cs_subevent_abort_reason subevent_abort_reason;
     788              :                 /** Number of antenna paths used during the phase measurement stage.
     789              :                  */
     790            1 :                 uint8_t num_antenna_paths;
     791              :                 /** Number of CS steps in the subevent.
     792              :                  */
     793            1 :                 uint8_t num_steps_reported;
     794              :                 /** Step number, on which the subevent was aborted
     795              :                  *  if subevent_done_status is @ref BT_CONN_LE_CS_SUBEVENT_COMPLETE
     796              :                  *  then abort_step will be unused and set to 255
     797              :                  */
     798            1 :                 uint8_t abort_step;
     799            0 :         } header;
     800              :         /** Pointer to buffer containing step data.
     801              :          *  NULL if num_steps_reported is 0.
     802              :          */
     803            1 :         struct net_buf_simple *step_data_buf;
     804              : };
     805              : 
     806              : /** @brief Increment a connection's reference count.
     807              :  *
     808              :  *  Increment the reference count of a connection object.
     809              :  *
     810              :  *  @note Will return NULL if the reference count is zero.
     811              :  *
     812              :  *  @param conn Connection object.
     813              :  *
     814              :  *  @return Connection object with incremented reference count, or NULL if the
     815              :  *          reference count is zero.
     816              :  */
     817            1 : struct bt_conn *bt_conn_ref(struct bt_conn *conn);
     818              : 
     819              : /** @brief Decrement a connection's reference count.
     820              :  *
     821              :  *  Decrement the reference count of a connection object.
     822              :  *
     823              :  *  @param conn Connection object.
     824              :  */
     825            1 : void bt_conn_unref(struct bt_conn *conn);
     826              : 
     827              : /** @brief Iterate through all bt_conn objects.
     828              :  *
     829              :  * Iterates through all bt_conn objects that are alive in the Host allocator.
     830              :  *
     831              :  * To find established connections, combine this with @ref bt_conn_get_info.
     832              :  * Check that @ref bt_conn_info.state is @ref BT_CONN_STATE_CONNECTED.
     833              :  *
     834              :  * Thread safety: This API is thread safe, but it does not guarantee a
     835              :  * sequentially-consistent view for objects allocated during the current
     836              :  * invocation of this API. E.g. If preempted while allocations A then B then C
     837              :  * happen then results may include A and C but miss B.
     838              :  *
     839              :  * @param type  Connection Type
     840              :  * @param func  Function to call for each connection.
     841              :  * @param data  Data to pass to the callback function.
     842              :  */
     843            1 : void bt_conn_foreach(enum bt_conn_type type,
     844              :                      void (*func)(struct bt_conn *conn, void *data),
     845              :                      void *data);
     846              : 
     847              : /** @brief Look up an existing connection by address.
     848              :  *
     849              :  *  Look up an existing connection based on the remote address.
     850              :  *
     851              :  *  The caller gets a new reference to the connection object which must be
     852              :  *  released with bt_conn_unref() once done using the object.
     853              :  *
     854              :  *  @param id   Local identity (in most cases BT_ID_DEFAULT).
     855              :  *  @param peer Remote address.
     856              :  *
     857              :  *  @return Connection object or NULL if not found.
     858              :  */
     859            1 : struct bt_conn *bt_conn_lookup_addr_le(uint8_t id, const bt_addr_le_t *peer);
     860              : 
     861              : /** @brief Get destination (peer) address of a connection.
     862              :  *
     863              :  *  @param conn Connection object.
     864              :  *
     865              :  *  @return Destination address if @p conn is a valid @ref BT_CONN_TYPE_LE connection
     866              :  */
     867            1 : const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn);
     868              : 
     869              : /** @brief Get array index of a connection
     870              :  *
     871              :  *  This function is used to map bt_conn to index of an array of
     872              :  *  connections. The array has CONFIG_BT_MAX_CONN elements.
     873              :  *
     874              :  *  @param conn Connection object.
     875              :  *
     876              :  *  @return Index of the connection object.
     877              :  *          The range of the returned value is 0..CONFIG_BT_MAX_CONN-1
     878              :  */
     879            1 : uint8_t bt_conn_index(const struct bt_conn *conn);
     880              : 
     881              : /** LE Connection Info Structure */
     882            1 : struct bt_conn_le_info {
     883              :         /** Source (Local) Identity Address */
     884            1 :         const bt_addr_le_t *src;
     885              :         /** Destination (Remote) Identity Address or remote Resolvable Private
     886              :          *  Address (RPA) before identity has been resolved.
     887              :          */
     888            1 :         const bt_addr_le_t *dst;
     889              :         /** Local device address used during connection setup. */
     890            1 :         const bt_addr_le_t *local;
     891              :         /** Remote device address used during connection setup. */
     892            1 :         const bt_addr_le_t *remote;
     893            1 :         uint16_t interval; /**< Connection interval */
     894            1 :         uint16_t latency; /**< Connection peripheral latency */
     895            1 :         uint16_t timeout; /**< Connection supervision timeout */
     896              : 
     897              : #if defined(CONFIG_BT_USER_PHY_UPDATE)
     898            0 :         const struct bt_conn_le_phy_info      *phy;
     899              : #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
     900              : 
     901              : #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
     902              :         /* Connection maximum single fragment parameters */
     903            0 :         const struct bt_conn_le_data_len_info *data_len;
     904              : #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
     905              : 
     906              : #if defined(CONFIG_BT_SUBRATING)
     907              :         /* Connection subrating parameters */
     908              :         const struct bt_conn_le_subrating_info *subrate;
     909              : #endif /* defined(CONFIG_BT_SUBRATING) */
     910              : };
     911              : 
     912              : /** @brief Convert connection interval to milliseconds
     913              :  *
     914              :  *  Multiply by 1.25 to get milliseconds.
     915              :  *
     916              :  *  Note that this may be inaccurate, as something like 7.5 ms cannot be
     917              :  *  accurately presented with integers.
     918              :  */
     919            1 : #define BT_CONN_INTERVAL_TO_MS(interval) ((interval) * 5U / 4U)
     920              : 
     921              : /** @brief Convert connection interval to microseconds
     922              :  *
     923              :  *  Multiply by 1250 to get microseconds.
     924              :  */
     925            1 : #define BT_CONN_INTERVAL_TO_US(interval) ((interval) * 1250U)
     926              : 
     927              : /** BR/EDR Connection Info Structure */
     928            1 : struct bt_conn_br_info {
     929            1 :         const bt_addr_t *dst; /**< Destination (Remote) BR/EDR address */
     930              : };
     931              : 
     932              : /** SCO Connection Info Structure */
     933            1 : struct bt_conn_sco_info {
     934            1 :         uint8_t link_type; /**< SCO link type */
     935            1 :         uint8_t air_mode;  /**< SCO air mode (codec type) */
     936              : };
     937              : 
     938            0 : enum {
     939              :         BT_CONN_ROLE_CENTRAL = 0,
     940              :         BT_CONN_ROLE_PERIPHERAL = 1,
     941              : };
     942              : 
     943            0 : enum bt_conn_state {
     944              :         /** Channel disconnected */
     945              :         BT_CONN_STATE_DISCONNECTED,
     946              :         /** Channel in connecting state */
     947              :         BT_CONN_STATE_CONNECTING,
     948              :         /** Channel connected and ready for upper layer traffic on it */
     949              :         BT_CONN_STATE_CONNECTED,
     950              :         /** Channel in disconnecting state */
     951              :         BT_CONN_STATE_DISCONNECTING,
     952              : };
     953              : 
     954              : /** Security level. */
     955            1 : typedef enum __packed {
     956              :         /** Level 0: Only for BR/EDR special cases, like SDP */
     957              :         BT_SECURITY_L0,
     958              :         /** Level 1: No encryption and no authentication. */
     959              :         BT_SECURITY_L1,
     960              :         /** Level 2: Encryption and no authentication (no MITM). */
     961              :         BT_SECURITY_L2,
     962              :         /** Level 3: Encryption and authentication (MITM). */
     963              :         BT_SECURITY_L3,
     964              :         /** Level 4: Authenticated Secure Connections and 128-bit key. */
     965              :         BT_SECURITY_L4,
     966              :         /** Bit to force new pairing procedure, bit-wise OR with requested
     967              :          *  security level.
     968              :          */
     969              :         BT_SECURITY_FORCE_PAIR = BIT(7),
     970              : } bt_security_t;
     971              : 
     972              : /** Security Info Flags. */
     973            1 : enum bt_security_flag {
     974              :         /** Paired with Secure Connections. */
     975              :         BT_SECURITY_FLAG_SC = BIT(0),
     976              :         /** Paired with Out of Band method. */
     977              :         BT_SECURITY_FLAG_OOB = BIT(1),
     978              : };
     979              : 
     980              : /** Security Info Structure. */
     981            1 : struct bt_security_info {
     982              :         /** Security Level. */
     983            1 :         bt_security_t level;
     984              :         /** Encryption Key Size. */
     985            1 :         uint8_t enc_key_size;
     986              :         /** Flags. */
     987            1 :         enum bt_security_flag flags;
     988              : };
     989              : 
     990              : /** Connection Info Structure */
     991            1 : struct bt_conn_info {
     992              :         /** Connection Type. */
     993            1 :         enum bt_conn_type type;
     994              :         /** Connection Role. */
     995            1 :         uint8_t role;
     996              :         /** Which local identity the connection was created with */
     997            1 :         uint8_t id;
     998              :         /** Connection Type specific Info.*/
     999              :         union {
    1000              :                 /** LE Connection specific Info. */
    1001            1 :                 struct bt_conn_le_info le;
    1002              :                 /** BR/EDR Connection specific Info. */
    1003            1 :                 struct bt_conn_br_info br;
    1004              :                 /** SCO Connection specific Info. */
    1005            1 :                 struct bt_conn_sco_info sco;
    1006            1 :         };
    1007              :         /** Connection state. */
    1008            1 :         enum bt_conn_state state;
    1009              :         /** Security specific info. */
    1010            1 :         struct bt_security_info security;
    1011              : };
    1012              : 
    1013              : /** LE Connection Remote Info Structure */
    1014            1 : struct bt_conn_le_remote_info {
    1015              : 
    1016              :         /** Remote LE feature set (bitmask). */
    1017            1 :         const uint8_t *features;
    1018              : };
    1019              : 
    1020              : /** BR/EDR Connection Remote Info structure */
    1021            1 : struct bt_conn_br_remote_info {
    1022              : 
    1023              :         /** Remote feature set (pages of bitmasks). */
    1024            1 :         const uint8_t *features;
    1025              : 
    1026              :         /** Number of pages in the remote feature set. */
    1027            1 :         uint8_t num_pages;
    1028              : };
    1029              : 
    1030              : /** @brief Connection Remote Info Structure
    1031              :  *
    1032              :  *  @note The version, manufacturer and subversion fields will only contain
    1033              :  *        valid data if @kconfig{CONFIG_BT_REMOTE_VERSION} is enabled.
    1034              :  */
    1035            1 : struct bt_conn_remote_info {
    1036              :         /** Connection Type */
    1037            1 :         uint8_t  type;
    1038              : 
    1039              :         /** Remote Link Layer version */
    1040            1 :         uint8_t  version;
    1041              : 
    1042              :         /** Remote manufacturer identifier */
    1043            1 :         uint16_t manufacturer;
    1044              : 
    1045              :         /** Per-manufacturer unique revision */
    1046            1 :         uint16_t subversion;
    1047              : 
    1048              :         union {
    1049              :                 /** LE connection remote info */
    1050            1 :                 struct bt_conn_le_remote_info le;
    1051              : 
    1052              :                 /** BR/EDR connection remote info */
    1053            1 :                 struct bt_conn_br_remote_info br;
    1054            0 :         };
    1055              : };
    1056              : 
    1057            0 : enum bt_conn_le_tx_power_phy {
    1058              :         /** Convenience macro for when no PHY is set. */
    1059              :         BT_CONN_LE_TX_POWER_PHY_NONE,
    1060              :         /** LE 1M PHY */
    1061              :         BT_CONN_LE_TX_POWER_PHY_1M,
    1062              :          /** LE 2M PHY */
    1063              :         BT_CONN_LE_TX_POWER_PHY_2M,
    1064              :         /** LE Coded PHY using S=8 coding. */
    1065              :         BT_CONN_LE_TX_POWER_PHY_CODED_S8,
    1066              :         /** LE Coded PHY using S=2 coding. */
    1067              :         BT_CONN_LE_TX_POWER_PHY_CODED_S2,
    1068              : };
    1069              : 
    1070              : /** LE Transmit Power Level Structure */
    1071            1 : struct bt_conn_le_tx_power {
    1072              : 
    1073              :         /** Input: 1M, 2M, Coded S2 or Coded S8 */
    1074            1 :         uint8_t phy;
    1075              : 
    1076              :         /** Output: current transmit power level */
    1077            1 :         int8_t current_level;
    1078              : 
    1079              :         /** Output: maximum transmit power level */
    1080            1 :         int8_t max_level;
    1081              : };
    1082              : 
    1083              : 
    1084              : /** LE Transmit Power Reporting Structure */
    1085            1 : struct bt_conn_le_tx_power_report {
    1086              : 
    1087              :         /** Reason for Transmit power reporting,
    1088              :          * as documented in Core Spec. Version 5.4 Vol. 4, Part E, 7.7.65.33.
    1089              :          */
    1090            1 :         uint8_t reason;
    1091              : 
    1092              :         /** Phy of Transmit power reporting. */
    1093            1 :         enum bt_conn_le_tx_power_phy phy;
    1094              : 
    1095              :         /** Transmit power level
    1096              :          * - 0xXX - Transmit power level
    1097              :          *  + Range: -127 to 20
    1098              :          *  + Units: dBm
    1099              :          *
    1100              :          * - 0x7E - Remote device is not managing power levels on this PHY.
    1101              :          * - 0x7F - Transmit power level is not available
    1102              :          */
    1103            1 :         int8_t tx_power_level;
    1104              : 
    1105              :         /** Bit 0: Transmit power level is at minimum level.
    1106              :          *  Bit 1: Transmit power level is at maximum level.
    1107              :          */
    1108            1 :         uint8_t tx_power_level_flag;
    1109              : 
    1110              :         /** Change in transmit power level
    1111              :          * - 0xXX - Change in transmit power level (positive indicates increased
    1112              :          *   power, negative indicates decreased power, zero indicates unchanged)
    1113              :          *   Units: dB
    1114              :          * - 0x7F - Change is not available or is out of range.
    1115              :          */
    1116            1 :         int8_t delta;
    1117              : };
    1118              : 
    1119              : /** @brief Path Loss zone that has been entered.
    1120              :  *
    1121              :  *  The path loss zone that has been entered in the most recent LE Path Loss Monitoring
    1122              :  *  Threshold Change event as documented in Core Spec. Version 5.4 Vol.4, Part E, 7.7.65.32.
    1123              :  *
    1124              :  *  @note BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE has been added to notify when path loss becomes
    1125              :  *        unavailable.
    1126              :  */
    1127            1 : enum bt_conn_le_path_loss_zone {
    1128              :         /** Low path loss zone entered. */
    1129              :         BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW,
    1130              :         /** Middle path loss zone entered. */
    1131              :         BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE,
    1132              :         /** High path loss zone entered. */
    1133              :         BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH,
    1134              :         /** Path loss has become unavailable. */
    1135              :         BT_CONN_LE_PATH_LOSS_ZONE_UNAVAILABLE,
    1136              : };
    1137              : 
    1138              : BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_LOW == BT_HCI_LE_ZONE_ENTERED_LOW);
    1139              : BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_MIDDLE == BT_HCI_LE_ZONE_ENTERED_MIDDLE);
    1140              : BUILD_ASSERT(BT_CONN_LE_PATH_LOSS_ZONE_ENTERED_HIGH == BT_HCI_LE_ZONE_ENTERED_HIGH);
    1141              : 
    1142              : /** @brief LE Path Loss Monitoring Threshold Change Report Structure. */
    1143            1 : struct bt_conn_le_path_loss_threshold_report {
    1144              : 
    1145              :         /** Path Loss zone as documented in Core Spec. Version 5.4 Vol.4, Part E, 7.7.65.32. */
    1146            1 :         enum bt_conn_le_path_loss_zone zone;
    1147              : 
    1148              :         /** Current path loss (dB). */
    1149            1 :         uint8_t path_loss;
    1150              : };
    1151              : 
    1152              : /** @brief LE Path Loss Monitoring Parameters Structure as defined in Core Spec. Version 5.4
    1153              :  *         Vol.4, Part E, 7.8.119 LE Set Path Loss Reporting Parameters command.
    1154              :  */
    1155            1 : struct bt_conn_le_path_loss_reporting_param {
    1156              :         /** High threshold for the path loss (dB). */
    1157            1 :         uint8_t high_threshold;
    1158              :         /** Hysteresis value for the high threshold (dB). */
    1159            1 :         uint8_t high_hysteresis;
    1160              :         /** Low threshold for the path loss (dB). */
    1161            1 :         uint8_t low_threshold;
    1162              :         /** Hysteresis value for the low threshold (dB). */
    1163            1 :         uint8_t low_hysteresis;
    1164              :         /** Minimum time in number of connection events to be observed once the
    1165              :          *  path loss crosses the threshold before an event is generated.
    1166              :          */
    1167            1 :         uint16_t min_time_spent;
    1168              : };
    1169              : 
    1170              : /** @brief Passkey Keypress Notification type
    1171              :  *
    1172              :  *  The numeric values are the same as in the Core specification for Pairing
    1173              :  *  Keypress Notification PDU.
    1174              :  */
    1175            0 : enum bt_conn_auth_keypress {
    1176              :         BT_CONN_AUTH_KEYPRESS_ENTRY_STARTED = 0x00,
    1177              :         BT_CONN_AUTH_KEYPRESS_DIGIT_ENTERED = 0x01,
    1178              :         BT_CONN_AUTH_KEYPRESS_DIGIT_ERASED = 0x02,
    1179              :         BT_CONN_AUTH_KEYPRESS_CLEARED = 0x03,
    1180              :         BT_CONN_AUTH_KEYPRESS_ENTRY_COMPLETED = 0x04,
    1181              : };
    1182              : 
    1183              : /** @brief Get connection info
    1184              :  *
    1185              :  *  @param conn Connection object.
    1186              :  *  @param info Connection info object.
    1187              :  *
    1188              :  *  @return Zero on success or (negative) error code on failure.
    1189              :  */
    1190            1 : int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info);
    1191              : 
    1192              : /** @brief Function to determine the type of a connection
    1193              :  *
    1194              :  *  @param conn The connection object
    1195              :  *  @param type The types to check against. It is possible to supply multiple types,
    1196              :  *              e.g. BT_CONN_TYPE_LE | BT_CONN_TYPE_SCO.
    1197              :  *
    1198              :  *  @retval true @p conn is of type @p type
    1199              :  *  @retval false @p conn is either NULL or not of type @p type
    1200              :  */
    1201            1 : bool bt_conn_is_type(const struct bt_conn *conn, enum bt_conn_type type);
    1202              : 
    1203              : /** @brief Get connection info for the remote device.
    1204              :  *
    1205              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    1206              :  *  @param remote_info Connection remote info object.
    1207              :  *
    1208              :  *  @note In order to retrieve the remote version (version, manufacturer
    1209              :  *  and subversion) @kconfig{CONFIG_BT_REMOTE_VERSION} must be enabled
    1210              :  *
    1211              :  *  @note The remote information is exchanged directly after the connection has
    1212              :  *  been established. The application can be notified about when the remote
    1213              :  *  information is available through the remote_info_available callback.
    1214              :  *
    1215              :  *  @return Zero on success or (negative) error code on failure.
    1216              :  *  @return -EBUSY The remote information is not yet available.
    1217              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection.
    1218              :  */
    1219            1 : int bt_conn_get_remote_info(const struct bt_conn *conn, struct bt_conn_remote_info *remote_info);
    1220              : 
    1221              : /** @brief Get connection transmit power level.
    1222              :  *
    1223              :  *  @param conn           @ref BT_CONN_TYPE_LE connection object.
    1224              :  *  @param tx_power_level Transmit power level descriptor.
    1225              :  *
    1226              :  *  @return Zero on success or (negative) error code on failure.
    1227              :  *  @return -ENOBUFS HCI command buffer is not available.
    1228              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1229              :  */
    1230            1 : int bt_conn_le_get_tx_power_level(struct bt_conn *conn,
    1231              :                                   struct bt_conn_le_tx_power *tx_power_level);
    1232              : 
    1233              : /** @brief Get local enhanced connection transmit power level.
    1234              :  *
    1235              :  *  @param conn           @ref BT_CONN_TYPE_LE connection object.
    1236              :  *  @param tx_power       Transmit power level descriptor.
    1237              :  *
    1238              :  *  @return Zero on success or (negative) error code on failure.
    1239              :  *  @retval -ENOBUFS HCI command buffer is not available.
    1240              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1241              :  */
    1242            1 : int bt_conn_le_enhanced_get_tx_power_level(struct bt_conn *conn,
    1243              :                                            struct bt_conn_le_tx_power *tx_power);
    1244              : 
    1245              : /** @brief Get remote (peer) transmit power level.
    1246              :  *
    1247              :  *  @param conn           @ref BT_CONN_TYPE_LE connection object.
    1248              :  *  @param phy            PHY information.
    1249              :  *
    1250              :  *  @return Zero on success or (negative) error code on failure.
    1251              :  *  @retval -ENOBUFS HCI command buffer is not available.
    1252              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1253              :  */
    1254            1 : int bt_conn_le_get_remote_tx_power_level(struct bt_conn *conn,
    1255              :                                          enum bt_conn_le_tx_power_phy phy);
    1256              : 
    1257              : /** @brief Enable transmit power reporting.
    1258              :  *
    1259              :  *  @param conn           @ref BT_CONN_TYPE_LE connection object.
    1260              :  *  @param local_enable   Enable/disable reporting for local.
    1261              :  *  @param remote_enable  Enable/disable reporting for remote.
    1262              :  *
    1263              :  *  @return Zero on success or (negative) error code on failure.
    1264              :  *  @retval -ENOBUFS HCI command buffer is not available.
    1265              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1266              :  */
    1267            1 : int bt_conn_le_set_tx_power_report_enable(struct bt_conn *conn,
    1268              :                                           bool local_enable,
    1269              :                                           bool remote_enable);
    1270              : 
    1271              : /** @brief Set Path Loss Monitoring Parameters.
    1272              :  *
    1273              :  *  Change the configuration for path loss threshold change events for a given conn handle.
    1274              :  *
    1275              :  *  @note To use this API @kconfig{CONFIG_BT_PATH_LOSS_MONITORING} must be set.
    1276              :  *
    1277              :  *  @param conn  @ref BT_CONN_TYPE_LE connection object.
    1278              :  *  @param param Path Loss Monitoring parameters
    1279              :  *
    1280              :  *  @return Zero on success or (negative) error code on failure.
    1281              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1282              :  */
    1283            1 : int bt_conn_le_set_path_loss_mon_param(struct bt_conn *conn,
    1284              :                                        const struct bt_conn_le_path_loss_reporting_param *param);
    1285              : 
    1286              : /** @brief Enable or Disable Path Loss Monitoring.
    1287              :  *
    1288              :  * Enable or disable Path Loss Monitoring, which will decide whether Path Loss Threshold events
    1289              :  * are sent from the controller to the host.
    1290              :  *
    1291              :  * @note To use this API @kconfig{CONFIG_BT_PATH_LOSS_MONITORING} must be set.
    1292              :  *
    1293              :  * @param conn  @ref BT_CONN_TYPE_LE connection object.
    1294              :  * @param enable Enable/disable path loss reporting.
    1295              :  *
    1296              :  * @return Zero on success or (negative) error code on failure.
    1297              :  * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1298              :  */
    1299            1 : int bt_conn_le_set_path_loss_mon_enable(struct bt_conn *conn, bool enable);
    1300              : 
    1301              : /** @brief Set Default Connection Subrating Parameters.
    1302              :  *
    1303              :  *  Change the default subrating parameters for all future
    1304              :  *  ACL connections where the local device is the central.
    1305              :  *  This command does not affect any existing connection.
    1306              :  *  Parameters set for specific connection will always have precedence.
    1307              :  *
    1308              :  *  @note To use this API @kconfig{CONFIG_BT_SUBRATING} and
    1309              :  *        @kconfig{CONFIG_BT_CENTRAL} must be set.
    1310              :  *
    1311              :  *  @param params Subrating parameters.
    1312              :  *
    1313              :  *  @return Zero on success or (negative) error code on failure.
    1314              :  */
    1315            1 : int bt_conn_le_subrate_set_defaults(const struct bt_conn_le_subrate_param *params);
    1316              : 
    1317              : /** @brief Request New Subrating Parameters.
    1318              :  *
    1319              :  *  Request a change to the subrating parameters of a connection.
    1320              :  *
    1321              :  *  @note To use this API @kconfig{CONFIG_BT_SUBRATING} must be set.
    1322              :  *
    1323              :  *  @param conn   @ref BT_CONN_TYPE_LE connection object.
    1324              :  *  @param params Subrating parameters.
    1325              :  *
    1326              :  *  @return Zero on success or (negative) error code on failure.
    1327              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1328              :  */
    1329            1 : int bt_conn_le_subrate_request(struct bt_conn *conn,
    1330              :                                const struct bt_conn_le_subrate_param *params);
    1331              : 
    1332              : /** @brief Read remote feature pages.
    1333              :  *
    1334              :  *  Request remote feature pages, from 0 up to pages_requested or the number
    1335              :  *  of pages supported by the peer. There is a maximum of 10 pages.
    1336              :  *  This function will trigger the read_all_remote_feat_complete callback
    1337              :  *  when the procedure is completed.
    1338              :  *
    1339              :  *  @kconfig_dep{CONFIG_BT_LE_EXTENDED_FEAT_SET}
    1340              :  *
    1341              :  *  @param conn @ref BT_CONN_TYPE_LE connection object.
    1342              :  *  @param pages_requested Number of feature pages to be requested from peer.
    1343              :  *                         There is a maximum of 10 pages.
    1344              :  *
    1345              :  *  @return Zero on success or (negative) error code on failure.
    1346              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1347              :  */
    1348            1 : int bt_conn_le_read_all_remote_features(struct bt_conn *conn, uint8_t pages_requested);
    1349              : 
    1350              : /** @brief Update frame space.
    1351              :  *
    1352              :  *  Request a change to the frame space parameters of a connection.
    1353              :  *  This function will trigger the frame_space_updated callback when the
    1354              :  *  procedure is completed.
    1355              :  *
    1356              :  *  @kconfig_dep{CONFIG_BT_FRAME_SPACE_UPDATE}.
    1357              :  *
    1358              :  *  @param conn   @ref BT_CONN_TYPE_LE connection object.
    1359              :  *  @param params Frame Space Update parameters.
    1360              :  *
    1361              :  *  @return Zero on success or (negative) error code on failure.
    1362              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1363              :  */
    1364            1 : int bt_conn_le_frame_space_update(struct bt_conn *conn,
    1365              :                                   const struct bt_conn_le_frame_space_update_param *params);
    1366              : 
    1367              : /** @brief Update the connection parameters.
    1368              :  *
    1369              :  *  If the local device is in the peripheral role then updating the connection
    1370              :  *  parameters will be delayed. This delay can be configured by through the
    1371              :  *  @kconfig{CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT} option.
    1372              :  *
    1373              :  *  @param conn  @ref BT_CONN_TYPE_LE connection object.
    1374              :  *  @param param Updated connection parameters.
    1375              :  *
    1376              :  *  @return Zero on success or (negative) error code on failure.
    1377              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1378              :  */
    1379            1 : int bt_conn_le_param_update(struct bt_conn *conn,
    1380              :                             const struct bt_le_conn_param *param);
    1381              : 
    1382              : /** @brief Update the connection transmit data length parameters.
    1383              :  *
    1384              :  *  @param conn  @ref BT_CONN_TYPE_LE connection object.
    1385              :  *  @param param Updated data length parameters.
    1386              :  *
    1387              :  *  @return Zero on success or (negative) error code on failure.
    1388              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1389              :  */
    1390            1 : int bt_conn_le_data_len_update(struct bt_conn *conn,
    1391              :                                const struct bt_conn_le_data_len_param *param);
    1392              : 
    1393              : /** @brief Update the connection PHY parameters.
    1394              :  *
    1395              :  *  Update the preferred transmit and receive PHYs of the connection.
    1396              :  *  Use @ref BT_GAP_LE_PHY_NONE to indicate no preference.
    1397              :  *
    1398              :  *  @param conn  @ref BT_CONN_TYPE_LE connection object.
    1399              :  *  @param param Updated connection parameters.
    1400              :  *
    1401              :  *  @return Zero on success or (negative) error code on failure.
    1402              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    1403              :  */
    1404            1 : int bt_conn_le_phy_update(struct bt_conn *conn,
    1405              :                           const struct bt_conn_le_phy_param *param);
    1406              : 
    1407              : /** @brief Update the default PHY parameters to be used for all subsequent
    1408              :  * connections over the LE transport.
    1409              :  *
    1410              :  *  Update the preferred transmit and receive PHYs of LE transport.
    1411              :  *  Use @ref BT_GAP_LE_PHY_NONE to indicate no preference.
    1412              :  *  For possible PHY values see @ref bt_gap_le_phy.
    1413              :  *
    1414              :  *  @param pref_tx_phy  Preferred transmitter phy prarameters.
    1415              :  *  @param pref_rx_phy  Preferred receiver phy prameters.
    1416              :  *
    1417              :  *  @return Zero on success or (negative) error code on failure.
    1418              :  */
    1419            1 : int bt_conn_le_set_default_phy(uint8_t pref_tx_phy, uint8_t pref_rx_phy);
    1420              : 
    1421              : /** @brief Disconnect from a remote device or cancel pending connection.
    1422              :  *
    1423              :  *  Disconnect an active connection with the specified reason code or cancel
    1424              :  *  pending outgoing connection.
    1425              :  *
    1426              :  *  The disconnect reason for a normal disconnect should be:
    1427              :  *  @ref BT_HCI_ERR_REMOTE_USER_TERM_CONN.
    1428              :  *
    1429              :  *  The following disconnect reasons are accepted:
    1430              :  *   - @ref BT_HCI_ERR_AUTH_FAIL
    1431              :  *   - @ref BT_HCI_ERR_REMOTE_USER_TERM_CONN
    1432              :  *   - @ref BT_HCI_ERR_REMOTE_LOW_RESOURCES
    1433              :  *   - @ref BT_HCI_ERR_REMOTE_POWER_OFF
    1434              :  *   - @ref BT_HCI_ERR_UNSUPP_REMOTE_FEATURE
    1435              :  *   - @ref BT_HCI_ERR_PAIRING_NOT_SUPPORTED
    1436              :  *   - @ref BT_HCI_ERR_UNACCEPT_CONN_PARAM
    1437              :  *
    1438              :  *  @param conn Connection to disconnect.
    1439              :  *  @param reason Reason code for the disconnection.
    1440              :  *
    1441              :  *  @return Zero on success or (negative) error code on failure.
    1442              :  */
    1443            1 : int bt_conn_disconnect(struct bt_conn *conn, uint8_t reason);
    1444              : 
    1445            0 : enum {
    1446              :         /** Convenience value when no options are specified. */
    1447              :         BT_CONN_LE_OPT_NONE = 0,
    1448              : 
    1449              :         /** @brief Enable LE Coded PHY.
    1450              :          *
    1451              :          *  Enable scanning on the LE Coded PHY.
    1452              :          */
    1453              :         BT_CONN_LE_OPT_CODED = BIT(0),
    1454              : 
    1455              :         /** @brief Disable LE 1M PHY.
    1456              :          *
    1457              :          *  Disable scanning on the LE 1M PHY.
    1458              :          *
    1459              :          *  @note Requires @ref BT_CONN_LE_OPT_CODED.
    1460              :          */
    1461              :         BT_CONN_LE_OPT_NO_1M = BIT(1),
    1462              : };
    1463              : 
    1464            0 : struct bt_conn_le_create_param {
    1465              : 
    1466              :         /** Bit-field of create connection options. */
    1467            1 :         uint32_t options;
    1468              : 
    1469              :         /** Scan interval (N * 0.625 ms)
    1470              :          *
    1471              :          * @note When @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL} is enabled
    1472              :          *       and the application wants to scan and connect in parallel,
    1473              :          *       the Bluetooth Controller may require the scan interval used
    1474              :          *       for scanning and connection establishment to be equal to
    1475              :          *       obtain the best performance.
    1476              :          */
    1477            1 :         uint16_t interval;
    1478              : 
    1479              :         /** Scan window (N * 0.625 ms)
    1480              :          *
    1481              :          * @note When @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL} is enabled
    1482              :          *       and the application wants to scan and connect in parallel,
    1483              :          *       the Bluetooth Controller may require the scan window used
    1484              :          *       for scanning and connection establishment to be equal to
    1485              :          *       obtain the best performance.
    1486              :          */
    1487            1 :         uint16_t window;
    1488              : 
    1489              :         /** @brief Scan interval LE Coded PHY (N * 0.625 MS)
    1490              :          *
    1491              :          *  Set zero to use same as LE 1M PHY scan interval
    1492              :          */
    1493            1 :         uint16_t interval_coded;
    1494              : 
    1495              :         /** @brief Scan window LE Coded PHY (N * 0.625 MS)
    1496              :          *
    1497              :          *  Set zero to use same as LE 1M PHY scan window.
    1498              :          */
    1499            1 :         uint16_t window_coded;
    1500              : 
    1501              :         /** @brief Connection initiation timeout (N * 10 MS)
    1502              :          *
    1503              :          *  Set zero to use the default @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT}
    1504              :          *  timeout.
    1505              :          *
    1506              :          *  @note Unused in @ref bt_conn_le_create_auto
    1507              :          */
    1508            1 :         uint16_t timeout;
    1509              : };
    1510              : 
    1511              : /** @brief Initialize create connection parameters
    1512              :  *
    1513              :  *  @param _options  Create connection options.
    1514              :  *  @param _interval Create connection scan interval (N * 0.625 ms).
    1515              :  *  @param _window   Create connection scan window (N * 0.625 ms).
    1516              :  */
    1517            1 : #define BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
    1518              : { \
    1519              :         .options = (_options), \
    1520              :         .interval = (_interval), \
    1521              :         .window = (_window), \
    1522              :         .interval_coded = 0, \
    1523              :         .window_coded = 0, \
    1524              :         .timeout = 0, \
    1525              : }
    1526              : 
    1527              : /** Helper to declare create connection parameters inline
    1528              :  *
    1529              :  *  @param _options  Create connection options.
    1530              :  *  @param _interval Create connection scan interval (N * 0.625 ms).
    1531              :  *  @param _window   Create connection scan window (N * 0.625 ms).
    1532              :  */
    1533            1 : #define BT_CONN_LE_CREATE_PARAM(_options, _interval, _window) \
    1534              :         ((struct bt_conn_le_create_param[]) { \
    1535              :                 BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
    1536              :          })
    1537              : 
    1538              : /** Default LE create connection parameters.
    1539              :  *  Scan continuously by setting scan interval equal to scan window.
    1540              :  */
    1541            1 : #define BT_CONN_LE_CREATE_CONN \
    1542              :         BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
    1543              :                                 BT_GAP_SCAN_FAST_INTERVAL, \
    1544              :                                 BT_GAP_SCAN_FAST_INTERVAL)
    1545              : 
    1546              : /** Default LE create connection using filter accept list parameters.
    1547              :  *  Scan window:   30 ms.
    1548              :  *  Scan interval: 60 ms.
    1549              :  */
    1550            1 : #define BT_CONN_LE_CREATE_CONN_AUTO \
    1551              :         BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
    1552              :                                 BT_GAP_SCAN_FAST_INTERVAL, \
    1553              :                                 BT_GAP_SCAN_FAST_WINDOW)
    1554              : 
    1555              : /** @brief Initiate an LE connection to a remote device.
    1556              :  *
    1557              :  *  Allows initiate new LE link to remote peer using its address.
    1558              :  *
    1559              :  *  The caller gets a new reference to the connection object which must be
    1560              :  *  released with bt_conn_unref() once done using the object. If
    1561              :  *  @kconfig{CONFIG_BT_CONN_CHECK_NULL_BEFORE_CREATE} is enabled, this function
    1562              :  *  will return -EINVAL if dereferenced @p conn is not NULL.
    1563              :  *
    1564              :  *  This uses the General Connection Establishment procedure.
    1565              :  *
    1566              :  *  The application must disable explicit scanning before initiating
    1567              :  *  a new LE connection if @kconfig{CONFIG_BT_SCAN_AND_INITIATE_IN_PARALLEL}
    1568              :  *  is not enabled.
    1569              :  *
    1570              :  *  @param[in]  peer         Remote address.
    1571              :  *  @param[in]  create_param Create connection parameters.
    1572              :  *  @param[in]  conn_param   Initial connection parameters.
    1573              :  *  @param[out] conn         Valid connection object on success.
    1574              :  *
    1575              :  *  @return Zero on success or (negative) error code on failure.
    1576              :  */
    1577            1 : int bt_conn_le_create(const bt_addr_le_t *peer,
    1578              :                       const struct bt_conn_le_create_param *create_param,
    1579              :                       const struct bt_le_conn_param *conn_param,
    1580              :                       struct bt_conn **conn);
    1581              : 
    1582            0 : struct bt_conn_le_create_synced_param {
    1583              : 
    1584              :         /** @brief Remote address
    1585              :          *
    1586              :          * The peer must be synchronized to the PAwR train.
    1587              :          *
    1588              :          */
    1589            1 :         const bt_addr_le_t *peer;
    1590              : 
    1591              :         /** The subevent where the connection will be initiated. */
    1592            1 :         uint8_t subevent;
    1593              : };
    1594              : 
    1595              : /** @brief Create a connection to a synced device
    1596              :  *
    1597              :  *  Initiate a connection to a synced device from a Periodic Advertising
    1598              :  *  with Responses (PAwR) train.
    1599              :  *
    1600              :  *  The caller gets a new reference to the connection object which must be
    1601              :  *  released with bt_conn_unref() once done using the object. If
    1602              :  *  @kconfig{CONFIG_BT_CONN_CHECK_NULL_BEFORE_CREATE} is enabled, this function
    1603              :  *  will return -EINVAL if dereferenced @p conn is not NULL.
    1604              :  *
    1605              :  *  This uses the Periodic Advertising Connection Procedure.
    1606              :  *
    1607              :  *  @param[in]  adv          The adverting set the PAwR advertiser belongs to.
    1608              :  *  @param[in]  synced_param Create connection parameters.
    1609              :  *  @param[in]  conn_param   Initial connection parameters.
    1610              :  *  @param[out] conn         Valid connection object on success.
    1611              :  *
    1612              :  *  @return Zero on success or (negative) error code on failure.
    1613              :  */
    1614            1 : int bt_conn_le_create_synced(const struct bt_le_ext_adv *adv,
    1615              :                              const struct bt_conn_le_create_synced_param *synced_param,
    1616              :                              const struct bt_le_conn_param *conn_param, struct bt_conn **conn);
    1617              : 
    1618              : /** @brief Automatically connect to remote devices in the filter accept list.
    1619              :  *
    1620              :  *  This uses the Auto Connection Establishment procedure.
    1621              :  *  The procedure will continue until a single connection is established or the
    1622              :  *  procedure is stopped through @ref bt_conn_create_auto_stop.
    1623              :  *  To establish connections to all devices in the filter accept list the
    1624              :  *  procedure should be started again in the connected callback after a
    1625              :  *  new connection has been established.
    1626              :  *
    1627              :  *  @param create_param Create connection parameters
    1628              :  *  @param conn_param   Initial connection parameters.
    1629              :  *
    1630              :  *  @return Zero on success or (negative) error code on failure.
    1631              :  *  @return -ENOMEM No free connection object available.
    1632              :  */
    1633            1 : int bt_conn_le_create_auto(const struct bt_conn_le_create_param *create_param,
    1634              :                            const struct bt_le_conn_param *conn_param);
    1635              : 
    1636              : /** @brief Stop automatic connect creation.
    1637              :  *
    1638              :  *  @return Zero on success or (negative) error code on failure.
    1639              :  */
    1640            1 : int bt_conn_create_auto_stop(void);
    1641              : 
    1642              : /** @brief Automatically connect to remote device if it's in range.
    1643              :  *
    1644              :  *  This function enables/disables automatic connection initiation.
    1645              :  *  Every time the device loses the connection with peer, this connection
    1646              :  *  will be re-established if connectable advertisement from peer is received.
    1647              :  *
    1648              :  *  @note Auto connect is disabled during explicit scanning.
    1649              :  *
    1650              :  *  @param addr Remote Bluetooth address.
    1651              :  *  @param param If non-NULL, auto connect is enabled with the given
    1652              :  *  parameters. If NULL, auto connect is disabled.
    1653              :  *
    1654              :  *  @return Zero on success or error code otherwise.
    1655              :  */
    1656            1 : __deprecated int bt_le_set_auto_conn(const bt_addr_le_t *addr,
    1657              :                                      const struct bt_le_conn_param *param);
    1658              : 
    1659              : /** @brief Set security level for a connection.
    1660              :  *
    1661              :  *  This function enable security (encryption) for a connection. If the device
    1662              :  *  has bond information for the peer with sufficiently strong key encryption
    1663              :  *  will be enabled. If the connection is already encrypted with sufficiently
    1664              :  *  strong key this function does nothing.
    1665              :  *
    1666              :  *  If the device has no bond information for the peer and is not already paired
    1667              :  *  then the pairing procedure will be initiated. Note that @p sec has no effect
    1668              :  *  on the security level selected for the pairing process. The selection is
    1669              :  *  instead controlled by the values of the registered @ref bt_conn_auth_cb. If
    1670              :  *  the device has bond information or is already paired and the keys are too
    1671              :  *  weak then the pairing procedure will be initiated.
    1672              :  *
    1673              :  *  This function may return an error if the required level of security defined using
    1674              :  *  @p sec is not possible to achieve due to local or remote device limitation
    1675              :  *  (e.g., input output capabilities), or if the maximum number of paired devices
    1676              :  *  has been reached.
    1677              :  *
    1678              :  *  This function may return an error if the pairing procedure has already been
    1679              :  *  initiated by the local device or the peer device.
    1680              :  *
    1681              :  *  @note When @kconfig{CONFIG_BT_SMP_SC_ONLY} is enabled then the security
    1682              :  *        level will always be level 4.
    1683              :  *
    1684              :  *  @note When @kconfig{CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY} is enabled then the
    1685              :  *        security level will always be level 3.
    1686              :  *
    1687              :  *  @note When @ref BT_SECURITY_FORCE_PAIR within @p sec is enabled then the pairing
    1688              :  *        procedure will always be initiated.
    1689              :  *
    1690              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    1691              :  *  @param sec Requested minimum security level.
    1692              :  *
    1693              :  *  @return 0 on success or negative error
    1694              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection.
    1695              :  */
    1696            1 : int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec);
    1697              : 
    1698              : /** @brief Get security level for a connection.
    1699              :  *
    1700              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    1701              :  *
    1702              :  *  @return Connection security level if @kconfig{CONFIG_BT_SMP} or @kconfig{CONFIG_BT_CLASSIC} is
    1703              :  *          enabled, else @ref BT_SECURITY_L1
    1704              :  *  @return @ref BT_SECURITY_L0 @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR
    1705              :  *          connection.
    1706              :  */
    1707            1 : bt_security_t bt_conn_get_security(const struct bt_conn *conn);
    1708              : 
    1709              : /** @brief Get encryption key size.
    1710              :  *
    1711              :  *  This function gets encryption key size.
    1712              :  *  If there is no security (encryption) enabled 0 will be returned.
    1713              :  *
    1714              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    1715              :  *
    1716              :  *  @return Encryption key size.
    1717              :  *  @return 0 @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection.
    1718              :  */
    1719            1 : uint8_t bt_conn_enc_key_size(const struct bt_conn *conn);
    1720              : 
    1721            0 : enum bt_security_err {
    1722              :         /** Security procedure successful. */
    1723              :         BT_SECURITY_ERR_SUCCESS,
    1724              : 
    1725              :         /** Authentication failed. */
    1726              :         BT_SECURITY_ERR_AUTH_FAIL,
    1727              : 
    1728              :         /** PIN or encryption key is missing. */
    1729              :         BT_SECURITY_ERR_PIN_OR_KEY_MISSING,
    1730              : 
    1731              :         /** OOB data is not available.  */
    1732              :         BT_SECURITY_ERR_OOB_NOT_AVAILABLE,
    1733              : 
    1734              :         /** The requested security level could not be reached. */
    1735              :         BT_SECURITY_ERR_AUTH_REQUIREMENT,
    1736              : 
    1737              :         /** Pairing is not supported */
    1738              :         BT_SECURITY_ERR_PAIR_NOT_SUPPORTED,
    1739              : 
    1740              :         /** Pairing is not allowed. */
    1741              :         BT_SECURITY_ERR_PAIR_NOT_ALLOWED,
    1742              : 
    1743              :         /** Invalid parameters. */
    1744              :         BT_SECURITY_ERR_INVALID_PARAM,
    1745              : 
    1746              :         /** Distributed Key Rejected */
    1747              :         BT_SECURITY_ERR_KEY_REJECTED,
    1748              : 
    1749              :         /** Pairing failed but the exact reason could not be specified. */
    1750              :         BT_SECURITY_ERR_UNSPECIFIED,
    1751              : };
    1752              : 
    1753            0 : enum bt_conn_le_cs_procedure_enable_state {
    1754              :         BT_CONN_LE_CS_PROCEDURES_DISABLED = BT_HCI_OP_LE_CS_PROCEDURES_DISABLED,
    1755              :         BT_CONN_LE_CS_PROCEDURES_ENABLED = BT_HCI_OP_LE_CS_PROCEDURES_ENABLED,
    1756              : };
    1757              : 
    1758              : /** CS Test Tone Antenna Config Selection.
    1759              :  *
    1760              :  *  These enum values are indices in the following table, where N_AP is the maximum
    1761              :  *  number of antenna paths (in the range [1, 4]).
    1762              :  *
    1763              :  * +--------------+-------------+-------------------+-------------------+--------+
    1764              :  * | Config Index | Total Paths | Dev A: # Antennas | Dev B: # Antennas | Config |
    1765              :  * +--------------+-------------+-------------------+-------------------+--------+
    1766              :  * |            0 |           1 |                 1 |                 1 | 1:1    |
    1767              :  * |            1 |           2 |                 2 |                 1 | N_AP:1 |
    1768              :  * |            2 |           3 |                 3 |                 1 | N_AP:1 |
    1769              :  * |            3 |           4 |                 4 |                 1 | N_AP:1 |
    1770              :  * |            4 |           2 |                 1 |                 2 | 1:N_AP |
    1771              :  * |            5 |           3 |                 1 |                 3 | 1:N_AP |
    1772              :  * |            6 |           4 |                 1 |                 4 | 1:N_AP |
    1773              :  * |            7 |           4 |                 2 |                 2 | 2:2    |
    1774              :  * +--------------+-------------+-------------------+-------------------+--------+
    1775              :  *
    1776              :  *  There are therefore four groups of possible antenna configurations:
    1777              :  *
    1778              :  *  - 1:1 configuration, where both A and B support 1 antenna each
    1779              :  *  - 1:N_AP configuration, where A supports 1 antenna, B supports N_AP antennas, and
    1780              :  *    N_AP is a value in the range [2, 4]
    1781              :  *  - N_AP:1 configuration, where A supports N_AP antennas, B supports 1 antenna, and
    1782              :  *    N_AP is a value in the range [2, 4]
    1783              :  *  - 2:2 configuration, where both A and B support 2 antennas and N_AP = 4
    1784              :  */
    1785            0 : enum bt_conn_le_cs_tone_antenna_config_selection {
    1786              :         BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A1_B1 = BT_HCI_OP_LE_CS_ACI_0,
    1787              :         BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A2_B1 = BT_HCI_OP_LE_CS_ACI_1,
    1788              :         BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A3_B1 = BT_HCI_OP_LE_CS_ACI_2,
    1789              :         BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A4_B1 = BT_HCI_OP_LE_CS_ACI_3,
    1790              :         BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A1_B2 = BT_HCI_OP_LE_CS_ACI_4,
    1791              :         BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A1_B3 = BT_HCI_OP_LE_CS_ACI_5,
    1792              :         BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A1_B4 = BT_HCI_OP_LE_CS_ACI_6,
    1793              :         BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A2_B2 = BT_HCI_OP_LE_CS_ACI_7,
    1794              : };
    1795              : 
    1796            0 : struct bt_conn_le_cs_procedure_enable_complete {
    1797              :         /* The ID associated with the desired configuration (0 to 3) */
    1798            0 :         uint8_t config_id;
    1799              : 
    1800              :         /* State of the CS procedure */
    1801            0 :         enum bt_conn_le_cs_procedure_enable_state state;
    1802              : 
    1803              :         /* Antenna configuration index */
    1804            0 :         enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
    1805              : 
    1806              :         /* Transmit power level used for CS procedures (-127 to 20 dB; 0x7F if unavailable) */
    1807            0 :         int8_t selected_tx_power;
    1808              : 
    1809              :         /* Duration of each CS subevent in microseconds (1250 us to 4 s) */
    1810            0 :         uint32_t subevent_len;
    1811              : 
    1812              :         /* Number of CS subevents anchored off the same ACL connection event (0x01 to 0x20) */
    1813            0 :         uint8_t subevents_per_event;
    1814              : 
    1815              :         /* Time between consecutive CS subevents anchored off the same ACL connection event in
    1816              :          * units of 0.625 ms
    1817              :          */
    1818            0 :         uint16_t subevent_interval;
    1819              : 
    1820              :         /* Number of ACL connection events between consecutive CS event anchor points */
    1821            0 :         uint16_t event_interval;
    1822              : 
    1823              :         /* Number of ACL connection events between consecutive CS procedure anchor points */
    1824            0 :         uint16_t procedure_interval;
    1825              : 
    1826              :         /* Number of CS procedures to be scheduled (0 if procedures to continue until disabled) */
    1827            0 :         uint16_t procedure_count;
    1828              : 
    1829              :         /* Maximum duration for each procedure in units of 0.625 ms (0x0001 to 0xFFFF) */
    1830            0 :         uint16_t max_procedure_len;
    1831              : };
    1832              : 
    1833              : /** @brief Connection callback structure.
    1834              :  *
    1835              :  *  This structure is used for tracking the state of a connection.
    1836              :  *  It is registered with the help of the bt_conn_cb_register() API.
    1837              :  *  It's permissible to register multiple instances of this @ref bt_conn_cb
    1838              :  *  type, in case different modules of an application are interested in
    1839              :  *  tracking the connection state. If a callback is not of interest for
    1840              :  *  an instance, it may be set to NULL and will as a consequence not be
    1841              :  *  used for that instance.
    1842              :  */
    1843            1 : struct bt_conn_cb {
    1844              :         /** @brief A new connection has been established.
    1845              :          *
    1846              :          *  This callback notifies the application of a new connection.
    1847              :          *  In case the err parameter is non-zero it means that the
    1848              :          *  connection establishment failed.
    1849              :          *
    1850              :          *  @note If the connection was established from an advertising set then
    1851              :          *        the advertising set cannot be restarted directly from this
    1852              :          *        callback. Instead use the connected callback of the
    1853              :          *        advertising set.
    1854              :          *
    1855              :          *  @param conn New connection object.
    1856              :          *  @param err HCI error. Zero for success, non-zero otherwise.
    1857              :          *
    1858              :          *  @p err can mean either of the following:
    1859              :          *  - @ref BT_HCI_ERR_UNKNOWN_CONN_ID Creating the connection started by
    1860              :          *    @ref bt_conn_le_create was canceled either by the user through
    1861              :          *    @ref bt_conn_disconnect or by the timeout in the host through
    1862              :          *    @ref bt_conn_le_create_param timeout parameter, which defaults to
    1863              :          *    @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT} seconds.
    1864              :          *  - @p BT_HCI_ERR_ADV_TIMEOUT High duty cycle directed connectable
    1865              :          *    advertiser started by @ref bt_le_adv_start failed to be connected
    1866              :          *    within the timeout.
    1867              :          */
    1868            1 :         void (*connected)(struct bt_conn *conn, uint8_t err);
    1869              : 
    1870              :         /** @brief A connection has been disconnected.
    1871              :          *
    1872              :          *  This callback notifies the application that a connection
    1873              :          *  has been disconnected.
    1874              :          *
    1875              :          *  When this callback is called the stack still has one reference to
    1876              :          *  the connection object. If the application in this callback tries to
    1877              :          *  start either a connectable advertiser or create a new connection
    1878              :          *  this might fail because there are no free connection objects
    1879              :          *  available.
    1880              :          *  To avoid this issue it is recommended to either start connectable
    1881              :          *  advertise or create a new connection using @ref k_work_submit or
    1882              :          *  increase @kconfig{CONFIG_BT_MAX_CONN}.
    1883              :          *
    1884              :          *  @param conn Connection object.
    1885              :          *  @param reason BT_HCI_ERR_* reason for the disconnection.
    1886              :          */
    1887            1 :         void (*disconnected)(struct bt_conn *conn, uint8_t reason);
    1888              : 
    1889              :         /** @brief A connection object has been returned to the pool.
    1890              :          *
    1891              :          * This callback notifies the application that it might be able to
    1892              :          * allocate a connection object. No guarantee, first come, first serve.
    1893              :          *
    1894              :          * Use this to e.g. re-start connectable advertising or scanning.
    1895              :          *
    1896              :          * Treat this callback as an ISR, as it originates from
    1897              :          * @ref bt_conn_unref which is used by the BT stack. Making
    1898              :          * Bluetooth API calls in this context is error-prone and strongly
    1899              :          * discouraged.
    1900              :          */
    1901            1 :         void (*recycled)(void);
    1902              : 
    1903              :         /** @brief LE connection parameter update request.
    1904              :          *
    1905              :          *  This callback notifies the application that a remote device
    1906              :          *  is requesting to update the connection parameters. The
    1907              :          *  application accepts the parameters by returning true, or
    1908              :          *  rejects them by returning false. Before accepting, the
    1909              :          *  application may also adjust the parameters to better suit
    1910              :          *  its needs.
    1911              :          *
    1912              :          *  It is recommended for an application to have just one of these
    1913              :          *  callbacks for simplicity. However, if an application registers
    1914              :          *  multiple it needs to manage the potentially different
    1915              :          *  requirements for each callback. Each callback gets the
    1916              :          *  parameters as returned by previous callbacks, i.e. they are not
    1917              :          *  necessarily the same ones as the remote originally sent.
    1918              :          *
    1919              :          *  If the application does not have this callback then the default
    1920              :          *  is to accept the parameters.
    1921              :          *
    1922              :          *  @param conn Connection object.
    1923              :          *  @param param Proposed connection parameters.
    1924              :          *
    1925              :          *  @return true to accept the parameters, or false to reject them.
    1926              :          */
    1927            1 :         bool (*le_param_req)(struct bt_conn *conn,
    1928              :                              struct bt_le_conn_param *param);
    1929              : 
    1930              :         /** @brief The parameters for an LE connection have been updated.
    1931              :          *
    1932              :          *  This callback notifies the application that the connection
    1933              :          *  parameters for an LE connection have been updated.
    1934              :          *
    1935              :          *  @param conn Connection object.
    1936              :          *  @param interval Connection interval.
    1937              :          *  @param latency Connection latency.
    1938              :          *  @param timeout Connection supervision timeout.
    1939              :          */
    1940            1 :         void (*le_param_updated)(struct bt_conn *conn, uint16_t interval,
    1941              :                                  uint16_t latency, uint16_t timeout);
    1942              : #if defined(CONFIG_BT_SMP)
    1943              :         /** @brief Remote Identity Address has been resolved.
    1944              :          *
    1945              :          *  This callback notifies the application that a remote
    1946              :          *  Identity Address has been resolved
    1947              :          *
    1948              :          *  @param conn Connection object.
    1949              :          *  @param rpa Resolvable Private Address.
    1950              :          *  @param identity Identity Address.
    1951              :          */
    1952            1 :         void (*identity_resolved)(struct bt_conn *conn,
    1953              :                                   const bt_addr_le_t *rpa,
    1954              :                                   const bt_addr_le_t *identity);
    1955              : #endif /* CONFIG_BT_SMP */
    1956              : #if defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC)
    1957              :         /** @brief The security level of a connection has changed.
    1958              :          *
    1959              :          *  This callback notifies the application that the security of a
    1960              :          *  connection has changed.
    1961              :          *
    1962              :          *  The security level of the connection can either have been increased
    1963              :          *  or remain unchanged. An increased security level means that the
    1964              :          *  pairing procedure has been performed or the bond information from
    1965              :          *  a previous connection has been applied. If the security level
    1966              :          *  remains unchanged this means that the encryption key has been
    1967              :          *  refreshed for the connection.
    1968              :          *
    1969              :          *  @param conn Connection object.
    1970              :          *  @param level New security level of the connection.
    1971              :          *  @param err Security error. Zero for success, non-zero otherwise.
    1972              :          */
    1973            1 :         void (*security_changed)(struct bt_conn *conn, bt_security_t level,
    1974              :                                  enum bt_security_err err);
    1975              : #endif /* defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC) */
    1976              : 
    1977              : #if defined(CONFIG_BT_REMOTE_INFO)
    1978              :         /** @brief Remote information procedures has completed.
    1979              :          *
    1980              :          *  This callback notifies the application that the remote information
    1981              :          *  has been retrieved from the remote peer.
    1982              :          *
    1983              :          *  @param conn Connection object.
    1984              :          *  @param remote_info Connection information of remote device.
    1985              :          */
    1986            1 :         void (*remote_info_available)(struct bt_conn *conn,
    1987              :                                       struct bt_conn_remote_info *remote_info);
    1988              : #endif /* defined(CONFIG_BT_REMOTE_INFO) */
    1989              : 
    1990              : #if defined(CONFIG_BT_USER_PHY_UPDATE)
    1991              :         /** @brief The PHY of the connection has changed.
    1992              :          *
    1993              :          *  This callback notifies the application that the PHY of the
    1994              :          *  connection has changed.
    1995              :          *
    1996              :          *  @param conn Connection object.
    1997              :          *  @param info Connection LE PHY information.
    1998              :          */
    1999            1 :         void (*le_phy_updated)(struct bt_conn *conn,
    2000              :                                struct bt_conn_le_phy_info *param);
    2001              : #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
    2002              : 
    2003              : #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
    2004              :         /** @brief The data length parameters of the connection has changed.
    2005              :          *
    2006              :          *  This callback notifies the application that the maximum Link Layer
    2007              :          *  payload length or transmission time has changed.
    2008              :          *
    2009              :          *  @param conn Connection object.
    2010              :          *  @param info Connection data length information.
    2011              :          */
    2012            1 :         void (*le_data_len_updated)(struct bt_conn *conn,
    2013              :                                     struct bt_conn_le_data_len_info *info);
    2014              : #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
    2015              : 
    2016              : #if defined(CONFIG_BT_DF_CONNECTION_CTE_RX)
    2017              :         /** @brief Callback for IQ samples report collected when sampling
    2018              :          *        CTE received by data channel PDU.
    2019              :          *
    2020              :          * @param conn      The connection object.
    2021              :          * @param iq_report Report data for collected IQ samples.
    2022              :          */
    2023              :         void (*cte_report_cb)(struct bt_conn *conn,
    2024              :                               const struct bt_df_conn_iq_samples_report *iq_report);
    2025              : #endif /* CONFIG_BT_DF_CONNECTION_CTE_RX */
    2026              : 
    2027              : #if defined(CONFIG_BT_TRANSMIT_POWER_CONTROL)
    2028              :         /** @brief LE Read Remote Transmit Power Level procedure has completed or LE
    2029              :          *  Transmit Power Reporting event.
    2030              :          *
    2031              :          *  This callback notifies the application that either the remote transmit power level
    2032              :          *  has been read from the peer or transmit power level has changed for the local or
    2033              :          *  remote controller when transmit power reporting is enabled for the respective side
    2034              :          *  using @ref bt_conn_le_set_tx_power_report_enable.
    2035              :          *
    2036              :          *  @param conn Connection object.
    2037              :          *  @param report Transmit power report.
    2038              :          */
    2039              :         void (*tx_power_report)(struct bt_conn *conn,
    2040              :                                 const struct bt_conn_le_tx_power_report *report);
    2041              : #endif /* CONFIG_BT_TRANSMIT_POWER_CONTROL */
    2042              : 
    2043              : #if defined(CONFIG_BT_PATH_LOSS_MONITORING)
    2044              :         /** @brief LE Path Loss Threshold event.
    2045              :          *
    2046              :          *  This callback notifies the application that there has been a path loss threshold
    2047              :          *  crossing or reporting the initial path loss threshold zone after using
    2048              :          *  @ref bt_conn_le_set_path_loss_mon_enable.
    2049              :          *
    2050              :          *  @param conn Connection object.
    2051              :          *  @param report Path loss threshold report.
    2052              :          */
    2053              :         void (*path_loss_threshold_report)(struct bt_conn *conn,
    2054              :                                 const struct bt_conn_le_path_loss_threshold_report *report);
    2055              : #endif /* CONFIG_BT_PATH_LOSS_MONITORING */
    2056              : 
    2057              : #if defined(CONFIG_BT_SUBRATING)
    2058              :         /** @brief LE Subrate Changed event.
    2059              :          *
    2060              :          *  This callback notifies the application that the subrating parameters
    2061              :          *  of the connection may have changed.
    2062              :          *  The connection subrating parameters will be unchanged
    2063              :          *  if status is not BT_HCI_ERR_SUCCESS.
    2064              :          *
    2065              :          *  @param conn   Connection object.
    2066              :          *  @param params New subrating parameters.
    2067              :          */
    2068              :         void (*subrate_changed)(struct bt_conn *conn,
    2069              :                                 const struct bt_conn_le_subrate_changed *params);
    2070              : #endif /* CONFIG_BT_SUBRATING */
    2071              : 
    2072              : #if defined(CONFIG_BT_LE_EXTENDED_FEAT_SET)
    2073              :         /** @brief Read all remote features complete event.
    2074              :          *
    2075              :          *  This callback notifies the application that a 'read all remote
    2076              :          *  features' procedure of the connection is completed. The other params
    2077              :          *  will not be populated if status is not @ref BT_HCI_ERR_SUCCESS.
    2078              :          *
    2079              :          *  This callback can be triggered by calling @ref
    2080              :          *  bt_conn_le_read_all_remote_features or by the procedure running
    2081              :          *  autonomously in the controller.
    2082              :          *
    2083              :          *  @param conn   Connection object.
    2084              :          *  @param params Remote features.
    2085              :          */
    2086              :         void (*read_all_remote_feat_complete)(
    2087              :                 struct bt_conn *conn,
    2088              :                 const struct bt_conn_le_read_all_remote_feat_complete *params);
    2089              : #endif /* CONFIG_BT_LE_EXTENDED_FEAT_SET */
    2090              : 
    2091              : #if defined(CONFIG_BT_FRAME_SPACE_UPDATE)
    2092              :         /** @brief Frame Space Update Complete event.
    2093              :          *
    2094              :          *  This callback notifies the application that the frame space of
    2095              :          *  the connection may have changed.
    2096              :          *  The frame space update parameters will be invalid
    2097              :          *  if status is not @ref BT_HCI_ERR_SUCCESS.
    2098              :          *
    2099              :          *  This callback can be triggered by calling @ref
    2100              :          *  bt_conn_le_frame_space_update, by the procedure running
    2101              :          *  autonomously in the controller or by the peer.
    2102              :          *
    2103              :          *  @param conn   Connection object.
    2104              :          *  @param params New frame space update parameters.
    2105              :          */
    2106              :         void (*frame_space_updated)(
    2107              :                 struct bt_conn *conn,
    2108              :                 const struct bt_conn_le_frame_space_updated *params);
    2109              : #endif /* CONFIG_BT_FRAME_SPACE_UPDATE */
    2110              : 
    2111              : #if defined(CONFIG_BT_CHANNEL_SOUNDING)
    2112              :         /** @brief LE CS Read Remote Supported Capabilities Complete event.
    2113              :          *
    2114              :          *  This callback notifies the application that a Channel Sounding
    2115              :          *  Capabilities Exchange procedure has completed.
    2116              :          *
    2117              :          *  If status is BT_HCI_ERR_SUCCESS, the remote channel
    2118              :          *  sounding capabilities have been received from the peer.
    2119              :          *
    2120              :          *  @param conn Connection object.
    2121              :          *  @param status HCI status of complete event.
    2122              :          *  @param remote_cs_capabilities Pointer to CS Capabilities on success or NULL otherwise.
    2123              :          */
    2124              :         void (*le_cs_read_remote_capabilities_complete)(struct bt_conn *conn,
    2125              :                                                         uint8_t status,
    2126              :                                                         struct bt_conn_le_cs_capabilities *params);
    2127              : 
    2128              :         /** @brief LE CS Read Remote FAE Table Complete event.
    2129              :          *
    2130              :          *  This callback notifies the application that a Channel Sounding
    2131              :          *  Mode-0 FAE Table Request procedure has completed.
    2132              :          *
    2133              :          *  If status is BT_HCI_ERR_SUCCESS, the remote mode-0
    2134              :          *  FAE Table has been received from the peer.
    2135              :          *
    2136              :          *  @param conn Connection object.
    2137              :          *  @param status HCI status of complete event.
    2138              :          *  @param params Pointer to FAE Table on success or NULL otherwise.
    2139              :          */
    2140              :         void (*le_cs_read_remote_fae_table_complete)(struct bt_conn *conn,
    2141              :                                                      uint8_t status,
    2142              :                                                      struct bt_conn_le_cs_fae_table *params);
    2143              : 
    2144              :         /** @brief LE CS Config created.
    2145              :          *
    2146              :          *  This callback notifies the application that a Channel Sounding
    2147              :          *  Configuration procedure has completed.
    2148              :          *
    2149              :          *  If status is BT_HCI_ERR_SUCCESS, a new CS config is created.
    2150              :          *
    2151              :          *  @param conn Connection object.
    2152              :          *  @param status HCI status of complete event.
    2153              :          *  @param config Pointer to CS configuration on success or NULL otherwise.
    2154              :          */
    2155              :         void (*le_cs_config_complete)(struct bt_conn *conn,
    2156              :                                       uint8_t status,
    2157              :                                       struct bt_conn_le_cs_config *config);
    2158              : 
    2159              :         /** @brief LE CS Config removed.
    2160              :          *
    2161              :          *  This callback notifies the application that a Channel Sounding
    2162              :          *  Configuration procedure has completed and a CS config is removed
    2163              :          *
    2164              :          *  @param conn Connection object.
    2165              :          *  @param config_id ID of the CS configuration that was removed.
    2166              :          */
    2167              :         void (*le_cs_config_removed)(struct bt_conn *conn, uint8_t config_id);
    2168              : 
    2169              :         /** @brief Subevent Results from a CS procedure are available.
    2170              :          *
    2171              :          * This callback notifies the user that CS subevent results are
    2172              :          * available for the given connection object.
    2173              :          *
    2174              :          * @param conn Connection objects.
    2175              :          * @param result Subevent results
    2176              :          */
    2177              :         void (*le_cs_subevent_data_available)(struct bt_conn *conn,
    2178              :                                               struct bt_conn_le_cs_subevent_result *result);
    2179              : 
    2180              :         /** @brief LE CS Security Enabled.
    2181              :          *
    2182              :          *  This callback notifies the application that a Channel Sounding
    2183              :          *  Security Enable procedure has completed.
    2184              :          *
    2185              :          *  If status is BT_HCI_ERR_SUCCESS, CS Security is enabled.
    2186              :          *
    2187              :          *  @param conn Connection object.
    2188              :          *  @param status HCI status of complete event.
    2189              :          */
    2190              :         void (*le_cs_security_enable_complete)(struct bt_conn *conn, uint8_t status);
    2191              : 
    2192              :         /** @brief LE CS Procedure Enabled.
    2193              :          *
    2194              :          *  This callback notifies the application that a Channel Sounding
    2195              :          *  Procedure Enable procedure has completed.
    2196              :          *
    2197              :          *  If status is BT_HCI_ERR_SUCCESS, CS procedure is enabled.
    2198              :          *
    2199              :          *  @param conn Connection object.
    2200              :          *  @param status HCI status.
    2201              :          *  @param params Pointer to CS Procedure Enable parameters on success or NULL otherwise.
    2202              :          */
    2203              :         void (*le_cs_procedure_enable_complete)(
    2204              :                 struct bt_conn *conn, uint8_t status,
    2205              :                 struct bt_conn_le_cs_procedure_enable_complete *params);
    2206              : 
    2207              : #endif
    2208              : 
    2209              : #if defined(CONFIG_BT_CLASSIC)
    2210              :         /** @brief The role of the connection has changed.
    2211              :          *
    2212              :          *  This callback notifies the application that the role switch procedure has completed.
    2213              :          *
    2214              :          *  @param conn Connection object.
    2215              :          *  @param status HCI status of role change event.
    2216              :          */
    2217            1 :         void (*role_changed)(struct bt_conn *conn, uint8_t status);
    2218              : #endif
    2219              : 
    2220              : #if defined(CONFIG_BT_CONN_DYNAMIC_CALLBACKS)
    2221              :         /** @internal Internally used field for list handling */
    2222              :         sys_snode_t _node;
    2223              : #endif
    2224              : };
    2225              : 
    2226              : /** @brief Register connection callbacks.
    2227              :  *
    2228              :  *  Register callbacks to monitor the state of connections.
    2229              :  *
    2230              :  *  @param cb Callback struct. Must point to memory that remains valid.
    2231              :  *
    2232              :  * @retval 0 Success.
    2233              :  * @retval -EEXIST if @p cb was already registered.
    2234              :  */
    2235            1 : int bt_conn_cb_register(struct bt_conn_cb *cb);
    2236              : 
    2237              : /**
    2238              :  * @brief Unregister connection callbacks.
    2239              :  *
    2240              :  * Unregister the state of connections callbacks.
    2241              :  *
    2242              :  * @param cb Callback struct point to memory that remains valid.
    2243              :  *
    2244              :  * @retval 0 Success
    2245              :  * @retval -EINVAL If @p cb is NULL
    2246              :  * @retval -ENOENT if @p cb was not registered
    2247              :  */
    2248            1 : int bt_conn_cb_unregister(struct bt_conn_cb *cb);
    2249              : 
    2250              : /**
    2251              :  *  @brief Register a callback structure for connection events.
    2252              :  *
    2253              :  *  @param _name Name of callback structure.
    2254              :  */
    2255            1 : #define BT_CONN_CB_DEFINE(_name)                                        \
    2256              :         static const STRUCT_SECTION_ITERABLE(bt_conn_cb,                \
    2257              :                                                 _CONCAT(bt_conn_cb_,    \
    2258              :                                                         _name))
    2259              : 
    2260              : /** Converts a security error to string.
    2261              :  *
    2262              :  * @return The string representation of the security error code.
    2263              :  *         If @kconfig{CONFIG_BT_SECURITY_ERR_TO_STR} is not enabled,
    2264              :  *         this just returns the empty string
    2265              :  */
    2266              : #if defined(CONFIG_BT_SECURITY_ERR_TO_STR)
    2267              : const char *bt_security_err_to_str(enum bt_security_err err);
    2268              : #else
    2269            1 : static inline const char *bt_security_err_to_str(enum bt_security_err err)
    2270              : {
    2271              :         ARG_UNUSED(err);
    2272              : 
    2273              :         return "";
    2274              : }
    2275              : #endif
    2276              : 
    2277              : /** @brief Enable/disable bonding.
    2278              :  *
    2279              :  *  Set/clear the Bonding flag in the Authentication Requirements of
    2280              :  *  SMP Pairing Request/Response data.
    2281              :  *  The initial value of this flag depends on BT_BONDABLE Kconfig setting.
    2282              :  *  For the vast majority of applications calling this function shouldn't be
    2283              :  *  needed.
    2284              :  *
    2285              :  *  @param enable Value allowing/disallowing to be bondable.
    2286              :  */
    2287            1 : void bt_set_bondable(bool enable);
    2288              : 
    2289              : /** @brief Get bonding flag.
    2290              :  *
    2291              :  *  Get current bonding flag.
    2292              :  *  The initial value of this flag depends on @kconfig{CONFIG_BT_BONDABLE} Kconfig
    2293              :  *  setting.
    2294              :  *  The Bonding flag can be updated using bt_set_bondable().
    2295              :  *
    2296              :  *  @return Current bonding flag.
    2297              :  */
    2298            1 : bool bt_get_bondable(void);
    2299              : 
    2300              : /** @brief Set/clear the bonding flag for a given connection.
    2301              :  *
    2302              :  *  Set/clear the Bonding flag in the Authentication Requirements of
    2303              :  *  SMP Pairing Request/Response data for a given connection.
    2304              :  *
    2305              :  *  The bonding flag for a given connection cannot be set/cleared if
    2306              :  *  security procedures in the SMP module have already started.
    2307              :  *  This function can be called only once per connection.
    2308              :  *
    2309              :  *  If the bonding flag is not set/cleared for a given connection,
    2310              :  *  the value will depend on global configuration which is set using
    2311              :  *  bt_set_bondable.
    2312              :  *  The default value of the global configuration is defined using
    2313              :  *  CONFIG_BT_BONDABLE Kconfig option.
    2314              :  *
    2315              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    2316              :  *  @param enable Value allowing/disallowing to be bondable.
    2317              :  *
    2318              :  *  @retval 0 Success
    2319              :  *  @retval -EALREADY Already in the requested state
    2320              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
    2321              :  *  @return -EINVAL @p conn is a valid @ref BT_CONN_TYPE_LE but could not get SMP context
    2322              :  */
    2323            1 : int bt_conn_set_bondable(struct bt_conn *conn, bool enable);
    2324              : 
    2325              : /** @brief Allow/disallow remote LE SC OOB data to be used for pairing.
    2326              :  *
    2327              :  *  Set/clear the OOB data flag for LE SC SMP Pairing Request/Response data.
    2328              :  *
    2329              :  *  @param enable Value allowing/disallowing remote LE SC OOB data.
    2330              :  */
    2331            1 : void bt_le_oob_set_sc_flag(bool enable);
    2332              : 
    2333              : /** @brief Allow/disallow remote legacy OOB data to be used for pairing.
    2334              :  *
    2335              :  *  Set/clear the OOB data flag for legacy SMP Pairing Request/Response data.
    2336              :  *
    2337              :  *  @param enable Value allowing/disallowing remote legacy OOB data.
    2338              :  */
    2339            1 : void bt_le_oob_set_legacy_flag(bool enable);
    2340              : 
    2341              : /** @brief Set OOB Temporary Key to be used for pairing
    2342              :  *
    2343              :  *  This function allows to set OOB data for the LE legacy pairing procedure.
    2344              :  *  The function should only be called in response to the oob_data_request()
    2345              :  *  callback provided that the legacy method is user pairing.
    2346              :  *
    2347              :  *  @param conn  @ref BT_CONN_TYPE_LE connection object.
    2348              :  *  @param tk Pointer to 16 byte long TK array
    2349              :  *
    2350              :  *  @retval 0 Success
    2351              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    2352              :  *  @return -EINVAL @p tk is NULL.
    2353              :  */
    2354            1 : int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const uint8_t *tk);
    2355              : 
    2356              : /** @brief Set OOB data during LE Secure Connections (SC) pairing procedure
    2357              :  *
    2358              :  *  This function allows to set OOB data during the LE SC pairing procedure.
    2359              :  *  The function should only be called in response to the oob_data_request()
    2360              :  *  callback provided that LE SC method is used for pairing.
    2361              :  *
    2362              :  *  The user should submit OOB data according to the information received in the
    2363              :  *  callback. This may yield three different configurations: with only local OOB
    2364              :  *  data present, with only remote OOB data present or with both local and
    2365              :  *  remote OOB data present.
    2366              :  *
    2367              :  *  @param conn  @ref BT_CONN_TYPE_LE connection object.
    2368              :  *  @param oobd_local Local OOB data or NULL if not present
    2369              :  *  @param oobd_remote Remote OOB data or NULL if not present
    2370              :  *
    2371              :  *  @return Zero on success or error code otherwise, positive in case of
    2372              :  *          protocol error or negative (POSIX) in case of stack internal error.
    2373              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    2374              :  */
    2375            1 : int bt_le_oob_set_sc_data(struct bt_conn *conn,
    2376              :                           const struct bt_le_oob_sc_data *oobd_local,
    2377              :                           const struct bt_le_oob_sc_data *oobd_remote);
    2378              : 
    2379              : /** @brief Get OOB data used for LE Secure Connections (SC) pairing procedure
    2380              :  *
    2381              :  *  This function allows to get OOB data during the LE SC pairing procedure that
    2382              :  *  were set by the bt_le_oob_set_sc_data() API.
    2383              :  *
    2384              :  *  @note The OOB data will only be available as long as the connection object
    2385              :  *  associated with it is valid.
    2386              :  *
    2387              :  *  @param conn  @ref BT_CONN_TYPE_LE connection object.
    2388              :  *  @param oobd_local Local OOB data or NULL if not set
    2389              :  *  @param oobd_remote Remote OOB data or NULL if not set
    2390              :  *
    2391              :  *  @return Zero on success or error code otherwise, positive in case of
    2392              :  *          protocol error or negative (POSIX) in case of stack internal error.
    2393              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
    2394              :  */
    2395            1 : int bt_le_oob_get_sc_data(struct bt_conn *conn,
    2396              :                           const struct bt_le_oob_sc_data **oobd_local,
    2397              :                           const struct bt_le_oob_sc_data **oobd_remote);
    2398              : 
    2399              : /**
    2400              :  *  Special passkey value that can be used to disable a previously
    2401              :  *  set fixed passkey.
    2402              :  */
    2403            1 : #define BT_PASSKEY_INVALID 0xffffffff
    2404              : 
    2405              : /** @brief Set a fixed passkey to be used for pairing.
    2406              :  *
    2407              :  *  This API is only available when the CONFIG_BT_FIXED_PASSKEY
    2408              :  *  configuration option has been enabled.
    2409              :  *
    2410              :  *  Sets a fixed passkey to be used for pairing. If set, the
    2411              :  *  pairing_confirm() callback will be called for all incoming pairings.
    2412              :  *
    2413              :  *  @param passkey A valid passkey (0 - 999999) or BT_PASSKEY_INVALID
    2414              :  *                 to disable a previously set fixed passkey.
    2415              :  *
    2416              :  *  @return 0 on success or a negative error code on failure.
    2417              :  */
    2418            1 : int bt_passkey_set(unsigned int passkey);
    2419              : 
    2420              : /** Info Structure for OOB pairing */
    2421            1 : struct bt_conn_oob_info {
    2422              :         /** Type of OOB pairing method */
    2423            1 :         enum {
    2424              :                 /** LE legacy pairing */
    2425              :                 BT_CONN_OOB_LE_LEGACY,
    2426              : 
    2427              :                 /** LE SC pairing */
    2428              :                 BT_CONN_OOB_LE_SC,
    2429            1 :         } type;
    2430              : 
    2431              :         union {
    2432              :                 /** LE Secure Connections OOB pairing parameters */
    2433              :                 struct {
    2434              :                         /** OOB data configuration */
    2435              :                         enum {
    2436              :                                 /** Local OOB data requested */
    2437              :                                 BT_CONN_OOB_LOCAL_ONLY,
    2438              : 
    2439              :                                 /** Remote OOB data requested */
    2440              :                                 BT_CONN_OOB_REMOTE_ONLY,
    2441              : 
    2442              :                                 /** Both local and remote OOB data requested */
    2443              :                                 BT_CONN_OOB_BOTH_PEERS,
    2444              : 
    2445              :                                 /** No OOB data requested */
    2446              :                                 BT_CONN_OOB_NO_DATA,
    2447            1 :                         } oob_config;
    2448            1 :                 } lesc;
    2449            0 :         };
    2450              : };
    2451              : 
    2452              : #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
    2453              : /** @brief Pairing request and pairing response info structure.
    2454              :  *
    2455              :  *  This structure is the same for both smp_pairing_req and smp_pairing_rsp
    2456              :  *  and a subset of the packet data, except for the initial Code octet.
    2457              :  *  It is documented in Core Spec. Vol. 3, Part H, 3.5.1 and 3.5.2.
    2458              :  */
    2459            1 : struct bt_conn_pairing_feat {
    2460              :         /** IO Capability, Core Spec. Vol 3, Part H, 3.5.1, Table 3.4 */
    2461            1 :         uint8_t io_capability;
    2462              : 
    2463              :         /** OOB data flag, Core Spec. Vol 3, Part H, 3.5.1, Table 3.5 */
    2464            1 :         uint8_t oob_data_flag;
    2465              : 
    2466              :         /** AuthReq, Core Spec. Vol 3, Part H, 3.5.1, Fig. 3.3 */
    2467            1 :         uint8_t auth_req;
    2468              : 
    2469              :         /** Maximum Encryption Key Size, Core Spec. Vol 3, Part H, 3.5.1 */
    2470            1 :         uint8_t max_enc_key_size;
    2471              : 
    2472              :         /** Initiator Key Distribution/Generation, Core Spec. Vol 3, Part H,
    2473              :          *  3.6.1, Fig. 3.11
    2474              :          */
    2475            1 :         uint8_t init_key_dist;
    2476              : 
    2477              :         /** Responder Key Distribution/Generation, Core Spec. Vol 3, Part H
    2478              :          *  3.6.1, Fig. 3.11
    2479              :          */
    2480            1 :         uint8_t resp_key_dist;
    2481              : };
    2482              : #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
    2483              : 
    2484              : /** Authenticated pairing callback structure */
    2485            1 : struct bt_conn_auth_cb {
    2486              : #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
    2487              :         /** @brief Query to proceed incoming pairing or not.
    2488              :          *
    2489              :          *  On any incoming pairing req/rsp this callback will be called for
    2490              :          *  the application to decide whether to allow for the pairing to
    2491              :          *  continue.
    2492              :          *
    2493              :          *  The pairing info received from the peer is passed to assist
    2494              :          *  making the decision.
    2495              :          *
    2496              :          *  As this callback is synchronous the application should return
    2497              :          *  a response value immediately. Otherwise it may affect the
    2498              :          *  timing during pairing. Hence, this information should not be
    2499              :          *  conveyed to the user to take action.
    2500              :          *
    2501              :          *  The remaining callbacks are not affected by this, but do notice
    2502              :          *  that other callbacks can be called during the pairing. Eg. if
    2503              :          *  pairing_confirm is registered both will be called for Just-Works
    2504              :          *  pairings.
    2505              :          *
    2506              :          *  This callback may be unregistered in which case pairing continues
    2507              :          *  as if the Kconfig flag was not set.
    2508              :          *
    2509              :          *  For BR/EDR Secure Simple Pairing (SSP), this callback is called
    2510              :          *  when receiving the BT_HCI_EVT_IO_CAPA_REQ hci event. The feat is
    2511              :          *  NULL here.
    2512              :          *
    2513              :          *  @param conn Connection where pairing is initiated.
    2514              :          *  @param feat Pairing req/resp info. It is NULL in BR/EDR SSP.
    2515              :          */
    2516              :         enum bt_security_err (*pairing_accept)(struct bt_conn *conn,
    2517              :                               const struct bt_conn_pairing_feat *const feat);
    2518              : #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
    2519              : 
    2520              :         /** @brief Display a passkey to the user.
    2521              :          *
    2522              :          *  When called the application is expected to display the given
    2523              :          *  passkey to the user, with the expectation that the passkey will
    2524              :          *  then be entered on the peer device. The passkey will be in the
    2525              :          *  range of 0 - 999999, and is expected to be padded with zeroes so
    2526              :          *  that six digits are always shown. E.g. the value 37 should be
    2527              :          *  shown as 000037.
    2528              :          *
    2529              :          *  This callback may be set to NULL, which means that the local
    2530              :          *  device lacks the ability do display a passkey. If set
    2531              :          *  to non-NULL the cancel callback must also be provided, since
    2532              :          *  this is the only way the application can find out that it should
    2533              :          *  stop displaying the passkey.
    2534              :          *
    2535              :          *  @param conn Connection where pairing is currently active.
    2536              :          *  @param passkey Passkey to show to the user.
    2537              :          */
    2538            1 :         void (*passkey_display)(struct bt_conn *conn, unsigned int passkey);
    2539              : 
    2540              : #if defined(CONFIG_BT_PASSKEY_KEYPRESS)
    2541              :         /** @brief Receive Passkey Keypress Notification during pairing
    2542              :          *
    2543              :          *  This allows the remote device to use the local device to give users
    2544              :          *  feedback on the progress of entering the passkey over there. This is
    2545              :          *  useful when the remote device itself has no display suitable for
    2546              :          *  showing the progress.
    2547              :          *
    2548              :          *  The handler of this callback is expected to keep track of the number
    2549              :          *  of digits entered and show a password-field-like feedback to the
    2550              :          *  user.
    2551              :          *
    2552              :          *  This callback is only relevant while the local side does Passkey
    2553              :          *  Display.
    2554              :          *
    2555              :          *  The event type is verified to be in range of the enum. No other
    2556              :          *  sanitization has been done. The remote could send a large number of
    2557              :          *  events of any type in any order.
    2558              :          *
    2559              :          *  @param conn The related connection.
    2560              :          *  @param type Type of event. Verified in range of the enum.
    2561              :          */
    2562              :         void (*passkey_display_keypress)(struct bt_conn *conn,
    2563              :                                          enum bt_conn_auth_keypress type);
    2564              : #endif
    2565              : 
    2566              :         /** @brief Request the user to enter a passkey.
    2567              :          *
    2568              :          *  When called the user is expected to enter a passkey. The passkey
    2569              :          *  must be in the range of 0 - 999999, and should be expected to
    2570              :          *  be zero-padded, as that's how the peer device will typically be
    2571              :          *  showing it (e.g. 37 would be shown as 000037).
    2572              :          *
    2573              :          *  Once the user has entered the passkey its value should be given
    2574              :          *  to the stack using the bt_conn_auth_passkey_entry() API.
    2575              :          *
    2576              :          *  This callback may be set to NULL, which means that the local
    2577              :          *  device lacks the ability to enter a passkey. If set to non-NULL
    2578              :          *  the cancel callback must also be provided, since this is the
    2579              :          *  only way the application can find out that it should stop
    2580              :          *  requesting the user to enter a passkey.
    2581              :          *
    2582              :          *  @param conn Connection where pairing is currently active.
    2583              :          */
    2584            1 :         void (*passkey_entry)(struct bt_conn *conn);
    2585              : 
    2586              :         /** @brief Request the user to confirm a passkey.
    2587              :          *
    2588              :          *  When called the user is expected to confirm that the given
    2589              :          *  passkey is also shown on the peer device.. The passkey will
    2590              :          *  be in the range of 0 - 999999, and should be zero-padded to
    2591              :          *  always be six digits (e.g. 37 would be shown as 000037).
    2592              :          *
    2593              :          *  Once the user has confirmed the passkey to match, the
    2594              :          *  bt_conn_auth_passkey_confirm() API should be called. If the
    2595              :          *  user concluded that the passkey doesn't match the
    2596              :          *  bt_conn_auth_cancel() API should be called.
    2597              :          *
    2598              :          *  This callback may be set to NULL, which means that the local
    2599              :          *  device lacks the ability to confirm a passkey. If set to non-NULL
    2600              :          *  the cancel callback must also be provided, since this is the
    2601              :          *  only way the application can find out that it should stop
    2602              :          *  requesting the user to confirm a passkey.
    2603              :          *
    2604              :          *  @param conn Connection where pairing is currently active.
    2605              :          *  @param passkey Passkey to be confirmed.
    2606              :          */
    2607            1 :         void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey);
    2608              : 
    2609              :         /** @brief Request the user to provide Out of Band (OOB) data.
    2610              :          *
    2611              :          *  When called the user is expected to provide OOB data. The required
    2612              :          *  data are indicated by the information structure.
    2613              :          *
    2614              :          *  For LE Secure Connections OOB pairing, the user should provide
    2615              :          *  local OOB data, remote OOB data or both depending on their
    2616              :          *  availability. Their value should be given to the stack using the
    2617              :          *  bt_le_oob_set_sc_data() API.
    2618              :          *
    2619              :          *  This callback must be set to non-NULL in order to support OOB
    2620              :          *  pairing.
    2621              :          *
    2622              :          *  @param conn Connection where pairing is currently active.
    2623              :          *  @param info OOB pairing information.
    2624              :          */
    2625            1 :         void (*oob_data_request)(struct bt_conn *conn,
    2626              :                                  struct bt_conn_oob_info *info);
    2627              : 
    2628              :         /** @brief Cancel the ongoing user request.
    2629              :          *
    2630              :          *  This callback will be called to notify the application that it
    2631              :          *  should cancel any previous user request (passkey display, entry
    2632              :          *  or confirmation).
    2633              :          *
    2634              :          *  This may be set to NULL, but must always be provided whenever the
    2635              :          *  passkey_display, passkey_entry passkey_confirm or pairing_confirm
    2636              :          *  callback has been provided.
    2637              :          *
    2638              :          *  @param conn Connection where pairing is currently active.
    2639              :          */
    2640            1 :         void (*cancel)(struct bt_conn *conn);
    2641              : 
    2642              :         /** @brief Request confirmation for an incoming pairing.
    2643              :          *
    2644              :          *  This callback will be called to confirm an incoming pairing
    2645              :          *  request where none of the other user callbacks is applicable.
    2646              :          *
    2647              :          *  If the user decides to accept the pairing the
    2648              :          *  bt_conn_auth_pairing_confirm() API should be called. If the
    2649              :          *  user decides to reject the pairing the bt_conn_auth_cancel() API
    2650              :          *  should be called.
    2651              :          *
    2652              :          *  This callback may be set to NULL, which means that the local
    2653              :          *  device lacks the ability to confirm a pairing request. If set
    2654              :          *  to non-NULL the cancel callback must also be provided, since
    2655              :          *  this is the only way the application can find out that it should
    2656              :          *  stop requesting the user to confirm a pairing request.
    2657              :          *
    2658              :          *  @param conn Connection where pairing is currently active.
    2659              :          */
    2660            1 :         void (*pairing_confirm)(struct bt_conn *conn);
    2661              : 
    2662              : #if defined(CONFIG_BT_CLASSIC)
    2663              :         /** @brief Request the user to enter a passkey.
    2664              :          *
    2665              :          *  This callback will be called for a BR/EDR (Bluetooth Classic)
    2666              :          *  connection where pairing is being performed. Once called the
    2667              :          *  user is expected to enter a PIN code with a length between
    2668              :          *  1 and 16 digits. If the @a highsec parameter is set to true
    2669              :          *  the PIN code must be 16 digits long.
    2670              :          *
    2671              :          *  Once entered, the PIN code should be given to the stack using
    2672              :          *  the bt_conn_auth_pincode_entry() API.
    2673              :          *
    2674              :          *  This callback may be set to NULL, however in that case pairing
    2675              :          *  over BR/EDR will not be possible. If provided, the cancel
    2676              :          *  callback must be provided as well.
    2677              :          *
    2678              :          *  @param conn Connection where pairing is currently active.
    2679              :          *  @param highsec true if 16 digit PIN is required.
    2680              :          */
    2681            1 :         void (*pincode_entry)(struct bt_conn *conn, bool highsec);
    2682              : #endif
    2683              : };
    2684              : 
    2685              : /** Authenticated pairing information callback structure */
    2686            1 : struct bt_conn_auth_info_cb {
    2687              :         /** @brief notify that pairing procedure was complete.
    2688              :          *
    2689              :          *  This callback notifies the application that the pairing procedure
    2690              :          *  has been completed.
    2691              :          *
    2692              :          *  @param conn Connection object.
    2693              :          *  @param bonded Bond information has been distributed during the
    2694              :          *                pairing procedure.
    2695              :          */
    2696            1 :         void (*pairing_complete)(struct bt_conn *conn, bool bonded);
    2697              : 
    2698              :         /** @brief notify that pairing process has failed.
    2699              :          *
    2700              :          *  @param conn Connection object.
    2701              :          *  @param reason Pairing failed reason
    2702              :          */
    2703            1 :         void (*pairing_failed)(struct bt_conn *conn,
    2704              :                                enum bt_security_err reason);
    2705              : 
    2706              :         /** @brief Notify that bond has been deleted.
    2707              :          *
    2708              :          *  This callback notifies the application that the bond information
    2709              :          *  for the remote peer has been deleted
    2710              :          *
    2711              :          *  @param id   Which local identity had the bond.
    2712              :          *  @param peer Remote address.
    2713              :          */
    2714            1 :         void (*bond_deleted)(uint8_t id, const bt_addr_le_t *peer);
    2715              : 
    2716              : #if defined(CONFIG_BT_CLASSIC)
    2717              :         /** @brief Notify that bond of classic has been deleted.
    2718              :          *
    2719              :          *  This callback notifies the application that the bond information of classic
    2720              :          *  for the remote peer has been deleted
    2721              :          *
    2722              :          *  @param peer Remote address.
    2723              :          */
    2724            1 :         void (*br_bond_deleted)(const bt_addr_t *peer);
    2725              : #endif /* CONFIG_BT_CLASSIC */
    2726              : 
    2727              :         /** Internally used field for list handling */
    2728            1 :         sys_snode_t node;
    2729              : };
    2730              : 
    2731              : /** @brief Register authentication callbacks.
    2732              :  *
    2733              :  *  Register callbacks to handle authenticated pairing. Passing NULL
    2734              :  *  unregisters a previous callbacks structure.
    2735              :  *
    2736              :  *  @param cb Callback struct.
    2737              :  *
    2738              :  *  @return Zero on success or negative error code otherwise
    2739              :  */
    2740            1 : int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb);
    2741              : 
    2742              : /** @brief Overlay authentication callbacks used for a given connection.
    2743              :  *
    2744              :  *  This function can be used only for Bluetooth LE connections.
    2745              :  *  The @kconfig{CONFIG_BT_SMP} must be enabled for this function.
    2746              :  *
    2747              :  *  The authentication callbacks for a given connection cannot be overlaid if
    2748              :  *  security procedures in the SMP module have already started. This function
    2749              :  *  can be called only once per connection.
    2750              :  *
    2751              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    2752              :  *  @param cb   Callback struct.
    2753              :  *
    2754              :  *  @return Zero on success or negative error code otherwise
    2755              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
    2756              :  */
    2757            1 : int bt_conn_auth_cb_overlay(struct bt_conn *conn, const struct bt_conn_auth_cb *cb);
    2758              : 
    2759              : /** @brief Register authentication information callbacks.
    2760              :  *
    2761              :  *  Register callbacks to get authenticated pairing information. Multiple
    2762              :  *  registrations can be done.
    2763              :  *
    2764              :  *  @param cb Callback struct.
    2765              :  *
    2766              :  *  @return Zero on success or negative error code otherwise
    2767              :  */
    2768            1 : int bt_conn_auth_info_cb_register(struct bt_conn_auth_info_cb *cb);
    2769              : 
    2770              : /** @brief Unregister authentication information callbacks.
    2771              :  *
    2772              :  *  Unregister callbacks to stop getting authenticated pairing information.
    2773              :  *
    2774              :  *  @param cb Callback struct.
    2775              :  *
    2776              :  *  @return Zero on success or negative error code otherwise
    2777              :  */
    2778            1 : int bt_conn_auth_info_cb_unregister(struct bt_conn_auth_info_cb *cb);
    2779              : 
    2780              : /** @brief Reply with entered passkey.
    2781              :  *
    2782              :  *  This function should be called only after passkey_entry callback from
    2783              :  *  bt_conn_auth_cb structure was called.
    2784              :  *
    2785              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    2786              :  *  @param passkey Entered passkey.
    2787              :  *
    2788              :  *  @return Zero on success or negative error code otherwise
    2789              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
    2790              :  */
    2791            1 : int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey);
    2792              : 
    2793              : /** @brief Send Passkey Keypress Notification during pairing
    2794              :  *
    2795              :  *  This function may be called only after passkey_entry callback from
    2796              :  *  bt_conn_auth_cb structure was called.
    2797              :  *
    2798              :  *  Requires @kconfig{CONFIG_BT_PASSKEY_KEYPRESS}.
    2799              :  *
    2800              :  *  @param conn @ref BT_CONN_TYPE_LE destination connection for the notification.
    2801              :  *  @param type What keypress event type to send. @see bt_conn_auth_keypress.
    2802              :  *
    2803              :  *  @retval 0 Success
    2804              :  *  @retval -EINVAL Improper use of the API.
    2805              :  *  @retval -ENOMEM Failed to allocate.
    2806              :  *  @retval -ENOBUFS Failed to allocate.
    2807              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection
    2808              :  */
    2809            1 : int bt_conn_auth_keypress_notify(struct bt_conn *conn, enum bt_conn_auth_keypress type);
    2810              : 
    2811              : /** @brief Cancel ongoing authenticated pairing.
    2812              :  *
    2813              :  *  This function allows to cancel ongoing authenticated pairing.
    2814              :  *
    2815              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    2816              :  *
    2817              :  *  @return Zero on success or negative error code otherwise
    2818              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
    2819              :  */
    2820            1 : int bt_conn_auth_cancel(struct bt_conn *conn);
    2821              : 
    2822              : /** @brief Reply if passkey was confirmed to match by user.
    2823              :  *
    2824              :  *  This function should be called only after passkey_confirm callback from
    2825              :  *  bt_conn_auth_cb structure was called.
    2826              :  *
    2827              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    2828              :  *
    2829              :  *  @return Zero on success or negative error code otherwise
    2830              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
    2831              :  */
    2832            1 : int bt_conn_auth_passkey_confirm(struct bt_conn *conn);
    2833              : 
    2834              : /** @brief Reply if incoming pairing was confirmed by user.
    2835              :  *
    2836              :  *  This function should be called only after pairing_confirm callback from
    2837              :  *  bt_conn_auth_cb structure was called if user confirmed incoming pairing.
    2838              :  *
    2839              :  *  @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
    2840              :  *
    2841              :  *  @return Zero on success or negative error code otherwise
    2842              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
    2843              :  */
    2844            1 : int bt_conn_auth_pairing_confirm(struct bt_conn *conn);
    2845              : 
    2846              : /** @brief Reply with entered PIN code.
    2847              :  *
    2848              :  *  This function should be called only after PIN code callback from
    2849              :  *  bt_conn_auth_cb structure was called. It's for legacy 2.0 devices.
    2850              :  *
    2851              :  *  @param conn @ref BT_CONN_TYPE_BR connection object.
    2852              :  *  @param pin Entered PIN code.
    2853              :  *
    2854              :  *  @return Zero on success or negative error code otherwise
    2855              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_BR connection
    2856              :  */
    2857            1 : int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin);
    2858              : 
    2859              : /** Connection parameters for BR/EDR connections */
    2860            1 : struct bt_br_conn_param {
    2861            0 :         bool allow_role_switch;
    2862              : };
    2863              : 
    2864              : /** @brief Initialize BR/EDR connection parameters
    2865              :  *
    2866              :  *  @param role_switch True if role switch is allowed
    2867              :  */
    2868            1 : #define BT_BR_CONN_PARAM_INIT(role_switch) \
    2869              : { \
    2870              :         .allow_role_switch = (role_switch), \
    2871              : }
    2872              : 
    2873              : /** Helper to declare BR/EDR connection parameters inline
    2874              :   *
    2875              :   * @param role_switch True if role switch is allowed
    2876              :   */
    2877            1 : #define BT_BR_CONN_PARAM(role_switch) \
    2878              :         ((struct bt_br_conn_param[]) { \
    2879              :                 BT_BR_CONN_PARAM_INIT(role_switch) \
    2880              :          })
    2881              : 
    2882              : /** Default BR/EDR connection parameters:
    2883              :  *    Role switch allowed
    2884              :  */
    2885            1 : #define BT_BR_CONN_PARAM_DEFAULT BT_BR_CONN_PARAM(true)
    2886              : 
    2887              : 
    2888              : /** @brief Initiate an BR/EDR connection to a remote device.
    2889              :  *
    2890              :  *  Allows initiate new BR/EDR link to remote peer using its address.
    2891              :  *
    2892              :  *  The caller gets a new reference to the connection object which must be
    2893              :  *  released with bt_conn_unref() once done using the object.
    2894              :  *
    2895              :  *  @param peer  Remote address.
    2896              :  *  @param param Initial connection parameters.
    2897              :  *
    2898              :  *  @return Valid connection object on success or NULL otherwise.
    2899              :  */
    2900            1 : struct bt_conn *bt_conn_create_br(const bt_addr_t *peer,
    2901              :                                   const struct bt_br_conn_param *param);
    2902              : 
    2903              : /** @brief Look up an existing BR connection by address.
    2904              :  *
    2905              :  *  Look up an existing BR connection based on the remote address.
    2906              :  *
    2907              :  *  The caller gets a new reference to the connection object which must be
    2908              :  *  released with bt_conn_unref() once done using the object.
    2909              :  *
    2910              :  *  @param peer Remote address.
    2911              :  *
    2912              :  *  @return Connection object or NULL if not found.
    2913              :  */
    2914            1 : struct bt_conn *bt_conn_lookup_addr_br(const bt_addr_t *peer);
    2915              : 
    2916              : /** @brief Get destination (peer) address of a connection.
    2917              :  *
    2918              :  *  @param conn Connection object.
    2919              :  *
    2920              :  *  @return Destination address if @p conn is a valid @ref BT_CONN_TYPE_BR connection
    2921              :  */
    2922            1 : const bt_addr_t *bt_conn_get_dst_br(const struct bt_conn *conn);
    2923              : 
    2924              : /** @brief Change the role of the conn.
    2925              :  *
    2926              :  *  @param conn Connection object.
    2927              :  *  @param role The role that want to switch as, the value is @ref BT_HCI_ROLE_CENTRAL and
    2928              :  *              @ref BT_HCI_ROLE_PERIPHERAL from hci_types.h.
    2929              :  *
    2930              :  *  @return Zero on success or (negative) error code on failure.
    2931              :  *  @return -ENOBUFS HCI command buffer is not available.
    2932              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_BR connection
    2933              :  */
    2934            1 : int bt_conn_br_switch_role(const struct bt_conn *conn, uint8_t role);
    2935              : 
    2936              : /** @brief Enable/disable role switch of the connection by setting the connection's link policy.
    2937              :  *
    2938              :  *  @param conn Connection object.
    2939              :  *  @param enable Value enable/disable role switch of controller.
    2940              :  *
    2941              :  *  @return Zero on success or (negative) error code on failure.
    2942              :  *  @return -ENOBUFS HCI command buffer is not available.
    2943              :  *  @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_BR connection.
    2944              :  */
    2945            1 : int bt_conn_br_set_role_switch_enable(const struct bt_conn *conn, bool enable);
    2946              : 
    2947              : #ifdef __cplusplus
    2948              : }
    2949              : #endif
    2950              : 
    2951              : /**
    2952              :  * @}
    2953              :  */
    2954              : 
    2955              : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_ */
        

Generated by: LCOV version 2.0-1