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's recommended to rely instead on @ref bt_conn_cb.recycled
1881 : * which notifies the application when a connection object has actually been freed.
1882 : *
1883 : * @param conn Connection object.
1884 : * @param reason BT_HCI_ERR_* reason for the disconnection.
1885 : */
1886 1 : void (*disconnected)(struct bt_conn *conn, uint8_t reason);
1887 :
1888 : /** @brief A connection object has been returned to the pool.
1889 : *
1890 : * This callback notifies the application that it might be able to
1891 : * allocate a connection object. No guarantee, first come, first serve.
1892 : *
1893 : * The maximum number of simultaneous connections is configured
1894 : * by @kconfig{CONFIG_BT_MAX_CONN}.
1895 : *
1896 : * This is the event to listen for to start a new connection or connectable advertiser,
1897 : * both when the intention is to start it after the system is completely
1898 : * finished with an earlier connection, and when the application wants to start
1899 : * a connection for any reason but failed and is waiting for the right time to retry.
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_ */
|
