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 Set security level for a connection.
1643 : *
1644 : * This function enable security (encryption) for a connection. If the device
1645 : * has bond information for the peer with sufficiently strong key encryption
1646 : * will be enabled. If the connection is already encrypted with sufficiently
1647 : * strong key this function does nothing.
1648 : *
1649 : * If the device has no bond information for the peer and is not already paired
1650 : * then the pairing procedure will be initiated. Note that @p sec has no effect
1651 : * on the security level selected for the pairing process. The selection is
1652 : * instead controlled by the values of the registered @ref bt_conn_auth_cb. If
1653 : * the device has bond information or is already paired and the keys are too
1654 : * weak then the pairing procedure will be initiated.
1655 : *
1656 : * This function may return an error if the required level of security defined using
1657 : * @p sec is not possible to achieve due to local or remote device limitation
1658 : * (e.g., input output capabilities), or if the maximum number of paired devices
1659 : * has been reached.
1660 : *
1661 : * This function may return an error if the pairing procedure has already been
1662 : * initiated by the local device or the peer device.
1663 : *
1664 : * @note When @kconfig{CONFIG_BT_SMP_SC_ONLY} is enabled then the security
1665 : * level will always be level 4.
1666 : *
1667 : * @note When @kconfig{CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY} is enabled then the
1668 : * security level will always be level 3.
1669 : *
1670 : * @note When @ref BT_SECURITY_FORCE_PAIR within @p sec is enabled then the pairing
1671 : * procedure will always be initiated.
1672 : *
1673 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
1674 : * @param sec Requested minimum security level.
1675 : *
1676 : * @return 0 on success or negative error
1677 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection.
1678 : */
1679 1 : int bt_conn_set_security(struct bt_conn *conn, bt_security_t sec);
1680 :
1681 : /** @brief Get security level for a connection.
1682 : *
1683 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
1684 : *
1685 : * @return Connection security level if @kconfig{CONFIG_BT_SMP} or @kconfig{CONFIG_BT_CLASSIC} is
1686 : * enabled, else @ref BT_SECURITY_L1
1687 : * @return @ref BT_SECURITY_L0 @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR
1688 : * connection.
1689 : */
1690 1 : bt_security_t bt_conn_get_security(const struct bt_conn *conn);
1691 :
1692 : /** @brief Get encryption key size.
1693 : *
1694 : * This function gets encryption key size.
1695 : * If there is no security (encryption) enabled 0 will be returned.
1696 : *
1697 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
1698 : *
1699 : * @return Encryption key size.
1700 : * @return 0 @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection.
1701 : */
1702 1 : uint8_t bt_conn_enc_key_size(const struct bt_conn *conn);
1703 :
1704 0 : enum bt_security_err {
1705 : /** Security procedure successful. */
1706 : BT_SECURITY_ERR_SUCCESS,
1707 :
1708 : /** Authentication failed. */
1709 : BT_SECURITY_ERR_AUTH_FAIL,
1710 :
1711 : /** PIN or encryption key is missing. */
1712 : BT_SECURITY_ERR_PIN_OR_KEY_MISSING,
1713 :
1714 : /** OOB data is not available. */
1715 : BT_SECURITY_ERR_OOB_NOT_AVAILABLE,
1716 :
1717 : /** The requested security level could not be reached. */
1718 : BT_SECURITY_ERR_AUTH_REQUIREMENT,
1719 :
1720 : /** Pairing is not supported */
1721 : BT_SECURITY_ERR_PAIR_NOT_SUPPORTED,
1722 :
1723 : /** Pairing is not allowed. */
1724 : BT_SECURITY_ERR_PAIR_NOT_ALLOWED,
1725 :
1726 : /** Invalid parameters. */
1727 : BT_SECURITY_ERR_INVALID_PARAM,
1728 :
1729 : /** Distributed Key Rejected */
1730 : BT_SECURITY_ERR_KEY_REJECTED,
1731 :
1732 : /** Pairing failed but the exact reason could not be specified. */
1733 : BT_SECURITY_ERR_UNSPECIFIED,
1734 : };
1735 :
1736 0 : enum bt_conn_le_cs_procedure_enable_state {
1737 : BT_CONN_LE_CS_PROCEDURES_DISABLED = BT_HCI_OP_LE_CS_PROCEDURES_DISABLED,
1738 : BT_CONN_LE_CS_PROCEDURES_ENABLED = BT_HCI_OP_LE_CS_PROCEDURES_ENABLED,
1739 : };
1740 :
1741 : /** CS Test Tone Antenna Config Selection.
1742 : *
1743 : * These enum values are indices in the following table, where N_AP is the maximum
1744 : * number of antenna paths (in the range [1, 4]).
1745 : *
1746 : * +--------------+-------------+-------------------+-------------------+--------+
1747 : * | Config Index | Total Paths | Dev A: # Antennas | Dev B: # Antennas | Config |
1748 : * +--------------+-------------+-------------------+-------------------+--------+
1749 : * | 0 | 1 | 1 | 1 | 1:1 |
1750 : * | 1 | 2 | 2 | 1 | N_AP:1 |
1751 : * | 2 | 3 | 3 | 1 | N_AP:1 |
1752 : * | 3 | 4 | 4 | 1 | N_AP:1 |
1753 : * | 4 | 2 | 1 | 2 | 1:N_AP |
1754 : * | 5 | 3 | 1 | 3 | 1:N_AP |
1755 : * | 6 | 4 | 1 | 4 | 1:N_AP |
1756 : * | 7 | 4 | 2 | 2 | 2:2 |
1757 : * +--------------+-------------+-------------------+-------------------+--------+
1758 : *
1759 : * There are therefore four groups of possible antenna configurations:
1760 : *
1761 : * - 1:1 configuration, where both A and B support 1 antenna each
1762 : * - 1:N_AP configuration, where A supports 1 antenna, B supports N_AP antennas, and
1763 : * N_AP is a value in the range [2, 4]
1764 : * - N_AP:1 configuration, where A supports N_AP antennas, B supports 1 antenna, and
1765 : * N_AP is a value in the range [2, 4]
1766 : * - 2:2 configuration, where both A and B support 2 antennas and N_AP = 4
1767 : */
1768 0 : enum bt_conn_le_cs_tone_antenna_config_selection {
1769 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A1_B1 = BT_HCI_OP_LE_CS_ACI_0,
1770 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A2_B1 = BT_HCI_OP_LE_CS_ACI_1,
1771 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A3_B1 = BT_HCI_OP_LE_CS_ACI_2,
1772 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A4_B1 = BT_HCI_OP_LE_CS_ACI_3,
1773 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A1_B2 = BT_HCI_OP_LE_CS_ACI_4,
1774 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A1_B3 = BT_HCI_OP_LE_CS_ACI_5,
1775 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A1_B4 = BT_HCI_OP_LE_CS_ACI_6,
1776 : BT_LE_CS_TONE_ANTENNA_CONFIGURATION_A2_B2 = BT_HCI_OP_LE_CS_ACI_7,
1777 : };
1778 :
1779 0 : struct bt_conn_le_cs_procedure_enable_complete {
1780 : /* The ID associated with the desired configuration (0 to 3) */
1781 0 : uint8_t config_id;
1782 :
1783 : /* State of the CS procedure */
1784 0 : enum bt_conn_le_cs_procedure_enable_state state;
1785 :
1786 : /* Antenna configuration index */
1787 0 : enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
1788 :
1789 : /* Transmit power level used for CS procedures (-127 to 20 dB; 0x7F if unavailable) */
1790 0 : int8_t selected_tx_power;
1791 :
1792 : /* Duration of each CS subevent in microseconds (1250 us to 4 s) */
1793 0 : uint32_t subevent_len;
1794 :
1795 : /* Number of CS subevents anchored off the same ACL connection event (0x01 to 0x20) */
1796 0 : uint8_t subevents_per_event;
1797 :
1798 : /* Time between consecutive CS subevents anchored off the same ACL connection event in
1799 : * units of 0.625 ms
1800 : */
1801 0 : uint16_t subevent_interval;
1802 :
1803 : /* Number of ACL connection events between consecutive CS event anchor points */
1804 0 : uint16_t event_interval;
1805 :
1806 : /* Number of ACL connection events between consecutive CS procedure anchor points */
1807 0 : uint16_t procedure_interval;
1808 :
1809 : /* Number of CS procedures to be scheduled (0 if procedures to continue until disabled) */
1810 0 : uint16_t procedure_count;
1811 :
1812 : /* Maximum duration for each procedure in units of 0.625 ms (0x0001 to 0xFFFF) */
1813 0 : uint16_t max_procedure_len;
1814 : };
1815 :
1816 : /** @brief Connection callback structure.
1817 : *
1818 : * This structure is used for tracking the state of a connection.
1819 : * It is registered with the help of the bt_conn_cb_register() API.
1820 : * It's permissible to register multiple instances of this @ref bt_conn_cb
1821 : * type, in case different modules of an application are interested in
1822 : * tracking the connection state. If a callback is not of interest for
1823 : * an instance, it may be set to NULL and will as a consequence not be
1824 : * used for that instance.
1825 : */
1826 1 : struct bt_conn_cb {
1827 : /** @brief A new connection has been established.
1828 : *
1829 : * This callback notifies the application of a new connection.
1830 : * In case the err parameter is non-zero it means that the
1831 : * connection establishment failed.
1832 : *
1833 : * @note If the connection was established from an advertising set then
1834 : * the advertising set cannot be restarted directly from this
1835 : * callback. Instead use the connected callback of the
1836 : * advertising set.
1837 : *
1838 : * @param conn New connection object.
1839 : * @param err HCI error. Zero for success, non-zero otherwise.
1840 : *
1841 : * @p err can mean either of the following:
1842 : * - @ref BT_HCI_ERR_UNKNOWN_CONN_ID Creating the connection started by
1843 : * @ref bt_conn_le_create was canceled either by the user through
1844 : * @ref bt_conn_disconnect or by the timeout in the host through
1845 : * @ref bt_conn_le_create_param timeout parameter, which defaults to
1846 : * @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT} seconds.
1847 : * - @p BT_HCI_ERR_ADV_TIMEOUT High duty cycle directed connectable
1848 : * advertiser started by @ref bt_le_adv_start failed to be connected
1849 : * within the timeout.
1850 : */
1851 1 : void (*connected)(struct bt_conn *conn, uint8_t err);
1852 :
1853 : /** @brief A connection has been disconnected.
1854 : *
1855 : * This callback notifies the application that a connection
1856 : * has been disconnected.
1857 : *
1858 : * When this callback is called the stack still has one reference to
1859 : * the connection object. If the application in this callback tries to
1860 : * start either a connectable advertiser or create a new connection
1861 : * this might fail because there are no free connection objects
1862 : * available.
1863 : * To avoid this issue, it's recommended to rely instead on @ref bt_conn_cb.recycled
1864 : * which notifies the application when a connection object has actually been freed.
1865 : *
1866 : * @param conn Connection object.
1867 : * @param reason BT_HCI_ERR_* reason for the disconnection.
1868 : */
1869 1 : void (*disconnected)(struct bt_conn *conn, uint8_t reason);
1870 :
1871 : /** @brief A connection object has been returned to the pool.
1872 : *
1873 : * This callback notifies the application that it might be able to
1874 : * allocate a connection object. No guarantee, first come, first serve.
1875 : *
1876 : * The maximum number of simultaneous connections is configured
1877 : * by @kconfig{CONFIG_BT_MAX_CONN}.
1878 : *
1879 : * This is the event to listen for to start a new connection or connectable advertiser,
1880 : * both when the intention is to start it after the system is completely
1881 : * finished with an earlier connection, and when the application wants to start
1882 : * a connection for any reason but failed and is waiting for the right time to retry.
1883 : */
1884 1 : void (*recycled)(void);
1885 :
1886 : /** @brief LE connection parameter update request.
1887 : *
1888 : * This callback notifies the application that a remote device
1889 : * is requesting to update the connection parameters. The
1890 : * application accepts the parameters by returning true, or
1891 : * rejects them by returning false. Before accepting, the
1892 : * application may also adjust the parameters to better suit
1893 : * its needs.
1894 : *
1895 : * It is recommended for an application to have just one of these
1896 : * callbacks for simplicity. However, if an application registers
1897 : * multiple it needs to manage the potentially different
1898 : * requirements for each callback. Each callback gets the
1899 : * parameters as returned by previous callbacks, i.e. they are not
1900 : * necessarily the same ones as the remote originally sent.
1901 : *
1902 : * If the application does not have this callback then the default
1903 : * is to accept the parameters.
1904 : *
1905 : * @param conn Connection object.
1906 : * @param param Proposed connection parameters.
1907 : *
1908 : * @return true to accept the parameters, or false to reject them.
1909 : */
1910 1 : bool (*le_param_req)(struct bt_conn *conn,
1911 : struct bt_le_conn_param *param);
1912 :
1913 : /** @brief The parameters for an LE connection have been updated.
1914 : *
1915 : * This callback notifies the application that the connection
1916 : * parameters for an LE connection have been updated.
1917 : *
1918 : * @param conn Connection object.
1919 : * @param interval Connection interval.
1920 : * @param latency Connection latency.
1921 : * @param timeout Connection supervision timeout.
1922 : */
1923 1 : void (*le_param_updated)(struct bt_conn *conn, uint16_t interval,
1924 : uint16_t latency, uint16_t timeout);
1925 : #if defined(CONFIG_BT_SMP)
1926 : /** @brief Remote Identity Address has been resolved.
1927 : *
1928 : * This callback notifies the application that a remote
1929 : * Identity Address has been resolved
1930 : *
1931 : * @param conn Connection object.
1932 : * @param rpa Resolvable Private Address.
1933 : * @param identity Identity Address.
1934 : */
1935 1 : void (*identity_resolved)(struct bt_conn *conn,
1936 : const bt_addr_le_t *rpa,
1937 : const bt_addr_le_t *identity);
1938 : #endif /* CONFIG_BT_SMP */
1939 : #if defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC)
1940 : /** @brief The security level of a connection has changed.
1941 : *
1942 : * This callback notifies the application that the security of a
1943 : * connection has changed.
1944 : *
1945 : * The security level of the connection can either have been increased
1946 : * or remain unchanged. An increased security level means that the
1947 : * pairing procedure has been performed or the bond information from
1948 : * a previous connection has been applied. If the security level
1949 : * remains unchanged this means that the encryption key has been
1950 : * refreshed for the connection.
1951 : *
1952 : * @param conn Connection object.
1953 : * @param level New security level of the connection.
1954 : * @param err Security error. Zero for success, non-zero otherwise.
1955 : */
1956 1 : void (*security_changed)(struct bt_conn *conn, bt_security_t level,
1957 : enum bt_security_err err);
1958 : #endif /* defined(CONFIG_BT_SMP) || defined(CONFIG_BT_CLASSIC) */
1959 :
1960 : #if defined(CONFIG_BT_REMOTE_INFO)
1961 : /** @brief Remote information procedures has completed.
1962 : *
1963 : * This callback notifies the application that the remote information
1964 : * has been retrieved from the remote peer.
1965 : *
1966 : * @param conn Connection object.
1967 : * @param remote_info Connection information of remote device.
1968 : */
1969 1 : void (*remote_info_available)(struct bt_conn *conn,
1970 : struct bt_conn_remote_info *remote_info);
1971 : #endif /* defined(CONFIG_BT_REMOTE_INFO) */
1972 :
1973 : #if defined(CONFIG_BT_USER_PHY_UPDATE)
1974 : /** @brief The PHY of the connection has changed.
1975 : *
1976 : * This callback notifies the application that the PHY of the
1977 : * connection has changed.
1978 : *
1979 : * @param conn Connection object.
1980 : * @param info Connection LE PHY information.
1981 : */
1982 1 : void (*le_phy_updated)(struct bt_conn *conn,
1983 : struct bt_conn_le_phy_info *param);
1984 : #endif /* defined(CONFIG_BT_USER_PHY_UPDATE) */
1985 :
1986 : #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
1987 : /** @brief The data length parameters of the connection has changed.
1988 : *
1989 : * This callback notifies the application that the maximum Link Layer
1990 : * payload length or transmission time has changed.
1991 : *
1992 : * @param conn Connection object.
1993 : * @param info Connection data length information.
1994 : */
1995 1 : void (*le_data_len_updated)(struct bt_conn *conn,
1996 : struct bt_conn_le_data_len_info *info);
1997 : #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
1998 :
1999 : #if defined(CONFIG_BT_DF_CONNECTION_CTE_RX)
2000 : /** @brief Callback for IQ samples report collected when sampling
2001 : * CTE received by data channel PDU.
2002 : *
2003 : * @param conn The connection object.
2004 : * @param iq_report Report data for collected IQ samples.
2005 : */
2006 : void (*cte_report_cb)(struct bt_conn *conn,
2007 : const struct bt_df_conn_iq_samples_report *iq_report);
2008 : #endif /* CONFIG_BT_DF_CONNECTION_CTE_RX */
2009 :
2010 : #if defined(CONFIG_BT_TRANSMIT_POWER_CONTROL)
2011 : /** @brief LE Read Remote Transmit Power Level procedure has completed or LE
2012 : * Transmit Power Reporting event.
2013 : *
2014 : * This callback notifies the application that either the remote transmit power level
2015 : * has been read from the peer or transmit power level has changed for the local or
2016 : * remote controller when transmit power reporting is enabled for the respective side
2017 : * using @ref bt_conn_le_set_tx_power_report_enable.
2018 : *
2019 : * @param conn Connection object.
2020 : * @param report Transmit power report.
2021 : */
2022 : void (*tx_power_report)(struct bt_conn *conn,
2023 : const struct bt_conn_le_tx_power_report *report);
2024 : #endif /* CONFIG_BT_TRANSMIT_POWER_CONTROL */
2025 :
2026 : #if defined(CONFIG_BT_PATH_LOSS_MONITORING)
2027 : /** @brief LE Path Loss Threshold event.
2028 : *
2029 : * This callback notifies the application that there has been a path loss threshold
2030 : * crossing or reporting the initial path loss threshold zone after using
2031 : * @ref bt_conn_le_set_path_loss_mon_enable.
2032 : *
2033 : * @param conn Connection object.
2034 : * @param report Path loss threshold report.
2035 : */
2036 : void (*path_loss_threshold_report)(struct bt_conn *conn,
2037 : const struct bt_conn_le_path_loss_threshold_report *report);
2038 : #endif /* CONFIG_BT_PATH_LOSS_MONITORING */
2039 :
2040 : #if defined(CONFIG_BT_SUBRATING)
2041 : /** @brief LE Subrate Changed event.
2042 : *
2043 : * This callback notifies the application that the subrating parameters
2044 : * of the connection may have changed.
2045 : * The connection subrating parameters will be unchanged
2046 : * if status is not BT_HCI_ERR_SUCCESS.
2047 : *
2048 : * @param conn Connection object.
2049 : * @param params New subrating parameters.
2050 : */
2051 : void (*subrate_changed)(struct bt_conn *conn,
2052 : const struct bt_conn_le_subrate_changed *params);
2053 : #endif /* CONFIG_BT_SUBRATING */
2054 :
2055 : #if defined(CONFIG_BT_LE_EXTENDED_FEAT_SET)
2056 : /** @brief Read all remote features complete event.
2057 : *
2058 : * This callback notifies the application that a 'read all remote
2059 : * features' procedure of the connection is completed. The other params
2060 : * will not be populated if status is not @ref BT_HCI_ERR_SUCCESS.
2061 : *
2062 : * This callback can be triggered by calling @ref
2063 : * bt_conn_le_read_all_remote_features or by the procedure running
2064 : * autonomously in the controller.
2065 : *
2066 : * @param conn Connection object.
2067 : * @param params Remote features.
2068 : */
2069 : void (*read_all_remote_feat_complete)(
2070 : struct bt_conn *conn,
2071 : const struct bt_conn_le_read_all_remote_feat_complete *params);
2072 : #endif /* CONFIG_BT_LE_EXTENDED_FEAT_SET */
2073 :
2074 : #if defined(CONFIG_BT_FRAME_SPACE_UPDATE)
2075 : /** @brief Frame Space Update Complete event.
2076 : *
2077 : * This callback notifies the application that the frame space of
2078 : * the connection may have changed.
2079 : * The frame space update parameters will be invalid
2080 : * if status is not @ref BT_HCI_ERR_SUCCESS.
2081 : *
2082 : * This callback can be triggered by calling @ref
2083 : * bt_conn_le_frame_space_update, by the procedure running
2084 : * autonomously in the controller or by the peer.
2085 : *
2086 : * @param conn Connection object.
2087 : * @param params New frame space update parameters.
2088 : */
2089 : void (*frame_space_updated)(
2090 : struct bt_conn *conn,
2091 : const struct bt_conn_le_frame_space_updated *params);
2092 : #endif /* CONFIG_BT_FRAME_SPACE_UPDATE */
2093 :
2094 : #if defined(CONFIG_BT_CHANNEL_SOUNDING)
2095 : /** @brief LE CS Read Remote Supported Capabilities Complete event.
2096 : *
2097 : * This callback notifies the application that a Channel Sounding
2098 : * Capabilities Exchange procedure has completed.
2099 : *
2100 : * If status is BT_HCI_ERR_SUCCESS, the remote channel
2101 : * sounding capabilities have been received from the peer.
2102 : *
2103 : * @param conn Connection object.
2104 : * @param status HCI status of complete event.
2105 : * @param remote_cs_capabilities Pointer to CS Capabilities on success or NULL otherwise.
2106 : */
2107 : void (*le_cs_read_remote_capabilities_complete)(struct bt_conn *conn,
2108 : uint8_t status,
2109 : struct bt_conn_le_cs_capabilities *params);
2110 :
2111 : /** @brief LE CS Read Remote FAE Table Complete event.
2112 : *
2113 : * This callback notifies the application that a Channel Sounding
2114 : * Mode-0 FAE Table Request procedure has completed.
2115 : *
2116 : * If status is BT_HCI_ERR_SUCCESS, the remote mode-0
2117 : * FAE Table has been received from the peer.
2118 : *
2119 : * @param conn Connection object.
2120 : * @param status HCI status of complete event.
2121 : * @param params Pointer to FAE Table on success or NULL otherwise.
2122 : */
2123 : void (*le_cs_read_remote_fae_table_complete)(struct bt_conn *conn,
2124 : uint8_t status,
2125 : struct bt_conn_le_cs_fae_table *params);
2126 :
2127 : /** @brief LE CS Config created.
2128 : *
2129 : * This callback notifies the application that a Channel Sounding
2130 : * Configuration procedure has completed.
2131 : *
2132 : * If status is BT_HCI_ERR_SUCCESS, a new CS config is created.
2133 : *
2134 : * @param conn Connection object.
2135 : * @param status HCI status of complete event.
2136 : * @param config Pointer to CS configuration on success or NULL otherwise.
2137 : */
2138 : void (*le_cs_config_complete)(struct bt_conn *conn,
2139 : uint8_t status,
2140 : struct bt_conn_le_cs_config *config);
2141 :
2142 : /** @brief LE CS Config removed.
2143 : *
2144 : * This callback notifies the application that a Channel Sounding
2145 : * Configuration procedure has completed and a CS config is removed
2146 : *
2147 : * @param conn Connection object.
2148 : * @param config_id ID of the CS configuration that was removed.
2149 : */
2150 : void (*le_cs_config_removed)(struct bt_conn *conn, uint8_t config_id);
2151 :
2152 : /** @brief Subevent Results from a CS procedure are available.
2153 : *
2154 : * This callback notifies the user that CS subevent results are
2155 : * available for the given connection object.
2156 : *
2157 : * @param conn Connection objects.
2158 : * @param result Subevent results
2159 : */
2160 : void (*le_cs_subevent_data_available)(struct bt_conn *conn,
2161 : struct bt_conn_le_cs_subevent_result *result);
2162 :
2163 : /** @brief LE CS Security Enabled.
2164 : *
2165 : * This callback notifies the application that a Channel Sounding
2166 : * Security Enable procedure has completed.
2167 : *
2168 : * If status is BT_HCI_ERR_SUCCESS, CS Security is enabled.
2169 : *
2170 : * @param conn Connection object.
2171 : * @param status HCI status of complete event.
2172 : */
2173 : void (*le_cs_security_enable_complete)(struct bt_conn *conn, uint8_t status);
2174 :
2175 : /** @brief LE CS Procedure Enabled.
2176 : *
2177 : * This callback notifies the application that a Channel Sounding
2178 : * Procedure Enable procedure has completed.
2179 : *
2180 : * If status is BT_HCI_ERR_SUCCESS, CS procedure is enabled.
2181 : *
2182 : * @param conn Connection object.
2183 : * @param status HCI status.
2184 : * @param params Pointer to CS Procedure Enable parameters on success or NULL otherwise.
2185 : */
2186 : void (*le_cs_procedure_enable_complete)(
2187 : struct bt_conn *conn, uint8_t status,
2188 : struct bt_conn_le_cs_procedure_enable_complete *params);
2189 :
2190 : #endif
2191 :
2192 : #if defined(CONFIG_BT_CLASSIC)
2193 : /** @brief The role of the connection has changed.
2194 : *
2195 : * This callback notifies the application that the role switch procedure has completed.
2196 : *
2197 : * @param conn Connection object.
2198 : * @param status HCI status of role change event.
2199 : */
2200 1 : void (*role_changed)(struct bt_conn *conn, uint8_t status);
2201 : #endif
2202 :
2203 : #if defined(CONFIG_BT_CONN_DYNAMIC_CALLBACKS)
2204 : /** @internal Internally used field for list handling */
2205 : sys_snode_t _node;
2206 : #endif
2207 : };
2208 :
2209 : /** @brief Register connection callbacks.
2210 : *
2211 : * Register callbacks to monitor the state of connections.
2212 : *
2213 : * @param cb Callback struct. Must point to memory that remains valid.
2214 : *
2215 : * @retval 0 Success.
2216 : * @retval -EEXIST if @p cb was already registered.
2217 : */
2218 1 : int bt_conn_cb_register(struct bt_conn_cb *cb);
2219 :
2220 : /**
2221 : * @brief Unregister connection callbacks.
2222 : *
2223 : * Unregister the state of connections callbacks.
2224 : *
2225 : * @param cb Callback struct point to memory that remains valid.
2226 : *
2227 : * @retval 0 Success
2228 : * @retval -EINVAL If @p cb is NULL
2229 : * @retval -ENOENT if @p cb was not registered
2230 : */
2231 1 : int bt_conn_cb_unregister(struct bt_conn_cb *cb);
2232 :
2233 : /**
2234 : * @brief Register a callback structure for connection events.
2235 : *
2236 : * @param _name Name of callback structure.
2237 : */
2238 1 : #define BT_CONN_CB_DEFINE(_name) \
2239 : static const STRUCT_SECTION_ITERABLE(bt_conn_cb, \
2240 : _CONCAT(bt_conn_cb_, \
2241 : _name))
2242 :
2243 : /** Converts a security error to string.
2244 : *
2245 : * @return The string representation of the security error code.
2246 : * If @kconfig{CONFIG_BT_SECURITY_ERR_TO_STR} is not enabled,
2247 : * this just returns the empty string
2248 : */
2249 : #if defined(CONFIG_BT_SECURITY_ERR_TO_STR)
2250 : const char *bt_security_err_to_str(enum bt_security_err err);
2251 : #else
2252 1 : static inline const char *bt_security_err_to_str(enum bt_security_err err)
2253 : {
2254 : ARG_UNUSED(err);
2255 :
2256 : return "";
2257 : }
2258 : #endif
2259 :
2260 : /** @brief Enable/disable bonding.
2261 : *
2262 : * Set/clear the Bonding flag in the Authentication Requirements of
2263 : * SMP Pairing Request/Response data.
2264 : * The initial value of this flag depends on BT_BONDABLE Kconfig setting.
2265 : * For the vast majority of applications calling this function shouldn't be
2266 : * needed.
2267 : *
2268 : * @param enable Value allowing/disallowing to be bondable.
2269 : */
2270 1 : void bt_set_bondable(bool enable);
2271 :
2272 : /** @brief Get bonding flag.
2273 : *
2274 : * Get current bonding flag.
2275 : * The initial value of this flag depends on @kconfig{CONFIG_BT_BONDABLE} Kconfig
2276 : * setting.
2277 : * The Bonding flag can be updated using bt_set_bondable().
2278 : *
2279 : * @return Current bonding flag.
2280 : */
2281 1 : bool bt_get_bondable(void);
2282 :
2283 : /** @brief Set/clear the bonding flag for a given connection.
2284 : *
2285 : * Set/clear the Bonding flag in the Authentication Requirements of
2286 : * SMP Pairing Request/Response data for a given connection.
2287 : *
2288 : * The bonding flag for a given connection cannot be set/cleared if
2289 : * security procedures in the SMP module have already started.
2290 : * This function can be called only once per connection.
2291 : *
2292 : * If the bonding flag is not set/cleared for a given connection,
2293 : * the value will depend on global configuration which is set using
2294 : * bt_set_bondable.
2295 : * The default value of the global configuration is defined using
2296 : * CONFIG_BT_BONDABLE Kconfig option.
2297 : *
2298 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
2299 : * @param enable Value allowing/disallowing to be bondable.
2300 : *
2301 : * @retval 0 Success
2302 : * @retval -EALREADY Already in the requested state
2303 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
2304 : * @return -EINVAL @p conn is a valid @ref BT_CONN_TYPE_LE but could not get SMP context
2305 : */
2306 1 : int bt_conn_set_bondable(struct bt_conn *conn, bool enable);
2307 :
2308 : /** @brief Allow/disallow remote LE SC OOB data to be used for pairing.
2309 : *
2310 : * Set/clear the OOB data flag for LE SC SMP Pairing Request/Response data.
2311 : *
2312 : * @param enable Value allowing/disallowing remote LE SC OOB data.
2313 : */
2314 1 : void bt_le_oob_set_sc_flag(bool enable);
2315 :
2316 : /** @brief Allow/disallow remote legacy OOB data to be used for pairing.
2317 : *
2318 : * Set/clear the OOB data flag for legacy SMP Pairing Request/Response data.
2319 : *
2320 : * @param enable Value allowing/disallowing remote legacy OOB data.
2321 : */
2322 1 : void bt_le_oob_set_legacy_flag(bool enable);
2323 :
2324 : /** @brief Set OOB Temporary Key to be used for pairing
2325 : *
2326 : * This function allows to set OOB data for the LE legacy pairing procedure.
2327 : * The function should only be called in response to the oob_data_request()
2328 : * callback provided that the legacy method is user pairing.
2329 : *
2330 : * @param conn @ref BT_CONN_TYPE_LE connection object.
2331 : * @param tk Pointer to 16 byte long TK array
2332 : *
2333 : * @retval 0 Success
2334 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
2335 : * @return -EINVAL @p tk is NULL.
2336 : */
2337 1 : int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const uint8_t *tk);
2338 :
2339 : /** @brief Set OOB data during LE Secure Connections (SC) pairing procedure
2340 : *
2341 : * This function allows to set OOB data during the LE SC pairing procedure.
2342 : * The function should only be called in response to the oob_data_request()
2343 : * callback provided that LE SC method is used for pairing.
2344 : *
2345 : * The user should submit OOB data according to the information received in the
2346 : * callback. This may yield three different configurations: with only local OOB
2347 : * data present, with only remote OOB data present or with both local and
2348 : * remote OOB data present.
2349 : *
2350 : * @param conn @ref BT_CONN_TYPE_LE connection object.
2351 : * @param oobd_local Local OOB data or NULL if not present
2352 : * @param oobd_remote Remote OOB data or NULL if not present
2353 : *
2354 : * @return Zero on success or error code otherwise, positive in case of
2355 : * protocol error or negative (POSIX) in case of stack internal error.
2356 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
2357 : */
2358 1 : int bt_le_oob_set_sc_data(struct bt_conn *conn,
2359 : const struct bt_le_oob_sc_data *oobd_local,
2360 : const struct bt_le_oob_sc_data *oobd_remote);
2361 :
2362 : /** @brief Get OOB data used for LE Secure Connections (SC) pairing procedure
2363 : *
2364 : * This function allows to get OOB data during the LE SC pairing procedure that
2365 : * were set by the bt_le_oob_set_sc_data() API.
2366 : *
2367 : * @note The OOB data will only be available as long as the connection object
2368 : * associated with it is valid.
2369 : *
2370 : * @param conn @ref BT_CONN_TYPE_LE connection object.
2371 : * @param oobd_local Local OOB data or NULL if not set
2372 : * @param oobd_remote Remote OOB data or NULL if not set
2373 : *
2374 : * @return Zero on success or error code otherwise, positive in case of
2375 : * protocol error or negative (POSIX) in case of stack internal error.
2376 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection.
2377 : */
2378 1 : int bt_le_oob_get_sc_data(struct bt_conn *conn,
2379 : const struct bt_le_oob_sc_data **oobd_local,
2380 : const struct bt_le_oob_sc_data **oobd_remote);
2381 :
2382 : /**
2383 : * Special passkey value that can be used to disable a previously
2384 : * set fixed passkey.
2385 : */
2386 1 : #define BT_PASSKEY_INVALID 0xffffffff
2387 :
2388 : /** @brief Set a fixed passkey to be used for pairing.
2389 : *
2390 : * This API is only available when the CONFIG_BT_FIXED_PASSKEY
2391 : * configuration option has been enabled.
2392 : *
2393 : * Sets a fixed passkey to be used for pairing. If set, the
2394 : * pairing_confirm() callback will be called for all incoming pairings.
2395 : *
2396 : * @param passkey A valid passkey (0 - 999999) or BT_PASSKEY_INVALID
2397 : * to disable a previously set fixed passkey.
2398 : *
2399 : * @return 0 on success or a negative error code on failure.
2400 : */
2401 1 : int bt_passkey_set(unsigned int passkey);
2402 :
2403 : /** Info Structure for OOB pairing */
2404 1 : struct bt_conn_oob_info {
2405 : /** Type of OOB pairing method */
2406 1 : enum {
2407 : /** LE legacy pairing */
2408 : BT_CONN_OOB_LE_LEGACY,
2409 :
2410 : /** LE SC pairing */
2411 : BT_CONN_OOB_LE_SC,
2412 1 : } type;
2413 :
2414 : union {
2415 : /** LE Secure Connections OOB pairing parameters */
2416 : struct {
2417 : /** OOB data configuration */
2418 : enum {
2419 : /** Local OOB data requested */
2420 : BT_CONN_OOB_LOCAL_ONLY,
2421 :
2422 : /** Remote OOB data requested */
2423 : BT_CONN_OOB_REMOTE_ONLY,
2424 :
2425 : /** Both local and remote OOB data requested */
2426 : BT_CONN_OOB_BOTH_PEERS,
2427 :
2428 : /** No OOB data requested */
2429 : BT_CONN_OOB_NO_DATA,
2430 1 : } oob_config;
2431 1 : } lesc;
2432 0 : };
2433 : };
2434 :
2435 : #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
2436 : /** @brief Pairing request and pairing response info structure.
2437 : *
2438 : * This structure is the same for both smp_pairing_req and smp_pairing_rsp
2439 : * and a subset of the packet data, except for the initial Code octet.
2440 : * It is documented in Core Spec. Vol. 3, Part H, 3.5.1 and 3.5.2.
2441 : */
2442 1 : struct bt_conn_pairing_feat {
2443 : /** IO Capability, Core Spec. Vol 3, Part H, 3.5.1, Table 3.4 */
2444 1 : uint8_t io_capability;
2445 :
2446 : /** OOB data flag, Core Spec. Vol 3, Part H, 3.5.1, Table 3.5 */
2447 1 : uint8_t oob_data_flag;
2448 :
2449 : /** AuthReq, Core Spec. Vol 3, Part H, 3.5.1, Fig. 3.3 */
2450 1 : uint8_t auth_req;
2451 :
2452 : /** Maximum Encryption Key Size, Core Spec. Vol 3, Part H, 3.5.1 */
2453 1 : uint8_t max_enc_key_size;
2454 :
2455 : /** Initiator Key Distribution/Generation, Core Spec. Vol 3, Part H,
2456 : * 3.6.1, Fig. 3.11
2457 : */
2458 1 : uint8_t init_key_dist;
2459 :
2460 : /** Responder Key Distribution/Generation, Core Spec. Vol 3, Part H
2461 : * 3.6.1, Fig. 3.11
2462 : */
2463 1 : uint8_t resp_key_dist;
2464 : };
2465 : #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
2466 :
2467 : /** Authenticated pairing callback structure */
2468 1 : struct bt_conn_auth_cb {
2469 : #if defined(CONFIG_BT_SMP_APP_PAIRING_ACCEPT)
2470 : /** @brief Query to proceed incoming pairing or not.
2471 : *
2472 : * On any incoming pairing req/rsp this callback will be called for
2473 : * the application to decide whether to allow for the pairing to
2474 : * continue.
2475 : *
2476 : * The pairing info received from the peer is passed to assist
2477 : * making the decision.
2478 : *
2479 : * As this callback is synchronous the application should return
2480 : * a response value immediately. Otherwise it may affect the
2481 : * timing during pairing. Hence, this information should not be
2482 : * conveyed to the user to take action.
2483 : *
2484 : * The remaining callbacks are not affected by this, but do notice
2485 : * that other callbacks can be called during the pairing. Eg. if
2486 : * pairing_confirm is registered both will be called for Just-Works
2487 : * pairings.
2488 : *
2489 : * This callback may be unregistered in which case pairing continues
2490 : * as if the Kconfig flag was not set.
2491 : *
2492 : * For BR/EDR Secure Simple Pairing (SSP), this callback is called
2493 : * when receiving the BT_HCI_EVT_IO_CAPA_REQ hci event. The feat is
2494 : * NULL here.
2495 : *
2496 : * @param conn Connection where pairing is initiated.
2497 : * @param feat Pairing req/resp info. It is NULL in BR/EDR SSP.
2498 : */
2499 : enum bt_security_err (*pairing_accept)(struct bt_conn *conn,
2500 : const struct bt_conn_pairing_feat *const feat);
2501 : #endif /* CONFIG_BT_SMP_APP_PAIRING_ACCEPT */
2502 :
2503 : /** @brief Display a passkey to the user.
2504 : *
2505 : * When called the application is expected to display the given
2506 : * passkey to the user, with the expectation that the passkey will
2507 : * then be entered on the peer device. The passkey will be in the
2508 : * range of 0 - 999999, and is expected to be padded with zeroes so
2509 : * that six digits are always shown. E.g. the value 37 should be
2510 : * shown as 000037.
2511 : *
2512 : * This callback may be set to NULL, which means that the local
2513 : * device lacks the ability do display a passkey. If set
2514 : * to non-NULL the cancel callback must also be provided, since
2515 : * this is the only way the application can find out that it should
2516 : * stop displaying the passkey.
2517 : *
2518 : * @param conn Connection where pairing is currently active.
2519 : * @param passkey Passkey to show to the user.
2520 : */
2521 1 : void (*passkey_display)(struct bt_conn *conn, unsigned int passkey);
2522 :
2523 : #if defined(CONFIG_BT_PASSKEY_KEYPRESS)
2524 : /** @brief Receive Passkey Keypress Notification during pairing
2525 : *
2526 : * This allows the remote device to use the local device to give users
2527 : * feedback on the progress of entering the passkey over there. This is
2528 : * useful when the remote device itself has no display suitable for
2529 : * showing the progress.
2530 : *
2531 : * The handler of this callback is expected to keep track of the number
2532 : * of digits entered and show a password-field-like feedback to the
2533 : * user.
2534 : *
2535 : * This callback is only relevant while the local side does Passkey
2536 : * Display.
2537 : *
2538 : * The event type is verified to be in range of the enum. No other
2539 : * sanitization has been done. The remote could send a large number of
2540 : * events of any type in any order.
2541 : *
2542 : * @param conn The related connection.
2543 : * @param type Type of event. Verified in range of the enum.
2544 : */
2545 : void (*passkey_display_keypress)(struct bt_conn *conn,
2546 : enum bt_conn_auth_keypress type);
2547 : #endif
2548 :
2549 : /** @brief Request the user to enter a passkey.
2550 : *
2551 : * When called the user is expected to enter a passkey. The passkey
2552 : * must be in the range of 0 - 999999, and should be expected to
2553 : * be zero-padded, as that's how the peer device will typically be
2554 : * showing it (e.g. 37 would be shown as 000037).
2555 : *
2556 : * Once the user has entered the passkey its value should be given
2557 : * to the stack using the bt_conn_auth_passkey_entry() API.
2558 : *
2559 : * This callback may be set to NULL, which means that the local
2560 : * device lacks the ability to enter a passkey. If set to non-NULL
2561 : * the cancel callback must also be provided, since this is the
2562 : * only way the application can find out that it should stop
2563 : * requesting the user to enter a passkey.
2564 : *
2565 : * @param conn Connection where pairing is currently active.
2566 : */
2567 1 : void (*passkey_entry)(struct bt_conn *conn);
2568 :
2569 : /** @brief Request the user to confirm a passkey.
2570 : *
2571 : * When called the user is expected to confirm that the given
2572 : * passkey is also shown on the peer device.. The passkey will
2573 : * be in the range of 0 - 999999, and should be zero-padded to
2574 : * always be six digits (e.g. 37 would be shown as 000037).
2575 : *
2576 : * Once the user has confirmed the passkey to match, the
2577 : * bt_conn_auth_passkey_confirm() API should be called. If the
2578 : * user concluded that the passkey doesn't match the
2579 : * bt_conn_auth_cancel() API should be called.
2580 : *
2581 : * This callback may be set to NULL, which means that the local
2582 : * device lacks the ability to confirm a passkey. If set to non-NULL
2583 : * the cancel callback must also be provided, since this is the
2584 : * only way the application can find out that it should stop
2585 : * requesting the user to confirm a passkey.
2586 : *
2587 : * @param conn Connection where pairing is currently active.
2588 : * @param passkey Passkey to be confirmed.
2589 : */
2590 1 : void (*passkey_confirm)(struct bt_conn *conn, unsigned int passkey);
2591 :
2592 : /** @brief Request the user to provide Out of Band (OOB) data.
2593 : *
2594 : * When called the user is expected to provide OOB data. The required
2595 : * data are indicated by the information structure.
2596 : *
2597 : * For LE Secure Connections OOB pairing, the user should provide
2598 : * local OOB data, remote OOB data or both depending on their
2599 : * availability. Their value should be given to the stack using the
2600 : * bt_le_oob_set_sc_data() API.
2601 : *
2602 : * This callback must be set to non-NULL in order to support OOB
2603 : * pairing.
2604 : *
2605 : * @param conn Connection where pairing is currently active.
2606 : * @param info OOB pairing information.
2607 : */
2608 1 : void (*oob_data_request)(struct bt_conn *conn,
2609 : struct bt_conn_oob_info *info);
2610 :
2611 : /** @brief Cancel the ongoing user request.
2612 : *
2613 : * This callback will be called to notify the application that it
2614 : * should cancel any previous user request (passkey display, entry
2615 : * or confirmation).
2616 : *
2617 : * This may be set to NULL, but must always be provided whenever the
2618 : * passkey_display, passkey_entry passkey_confirm or pairing_confirm
2619 : * callback has been provided.
2620 : *
2621 : * @param conn Connection where pairing is currently active.
2622 : */
2623 1 : void (*cancel)(struct bt_conn *conn);
2624 :
2625 : /** @brief Request confirmation for an incoming pairing.
2626 : *
2627 : * This callback will be called to confirm an incoming pairing
2628 : * request where none of the other user callbacks is applicable.
2629 : *
2630 : * If the user decides to accept the pairing the
2631 : * bt_conn_auth_pairing_confirm() API should be called. If the
2632 : * user decides to reject the pairing the bt_conn_auth_cancel() API
2633 : * should be called.
2634 : *
2635 : * This callback may be set to NULL, which means that the local
2636 : * device lacks the ability to confirm a pairing request. If set
2637 : * to non-NULL the cancel callback must also be provided, since
2638 : * this is the only way the application can find out that it should
2639 : * stop requesting the user to confirm a pairing request.
2640 : *
2641 : * @param conn Connection where pairing is currently active.
2642 : */
2643 1 : void (*pairing_confirm)(struct bt_conn *conn);
2644 :
2645 : #if defined(CONFIG_BT_CLASSIC)
2646 : /** @brief Request the user to enter a passkey.
2647 : *
2648 : * This callback will be called for a BR/EDR (Bluetooth Classic)
2649 : * connection where pairing is being performed. Once called the
2650 : * user is expected to enter a PIN code with a length between
2651 : * 1 and 16 digits. If the @a highsec parameter is set to true
2652 : * the PIN code must be 16 digits long.
2653 : *
2654 : * Once entered, the PIN code should be given to the stack using
2655 : * the bt_conn_auth_pincode_entry() API.
2656 : *
2657 : * This callback may be set to NULL, however in that case pairing
2658 : * over BR/EDR will not be possible. If provided, the cancel
2659 : * callback must be provided as well.
2660 : *
2661 : * @param conn Connection where pairing is currently active.
2662 : * @param highsec true if 16 digit PIN is required.
2663 : */
2664 1 : void (*pincode_entry)(struct bt_conn *conn, bool highsec);
2665 : #endif
2666 : };
2667 :
2668 : /** Authenticated pairing information callback structure */
2669 1 : struct bt_conn_auth_info_cb {
2670 : /** @brief notify that pairing procedure was complete.
2671 : *
2672 : * This callback notifies the application that the pairing procedure
2673 : * has been completed.
2674 : *
2675 : * @param conn Connection object.
2676 : * @param bonded Bond information has been distributed during the
2677 : * pairing procedure.
2678 : */
2679 1 : void (*pairing_complete)(struct bt_conn *conn, bool bonded);
2680 :
2681 : /** @brief notify that pairing process has failed.
2682 : *
2683 : * @param conn Connection object.
2684 : * @param reason Pairing failed reason
2685 : */
2686 1 : void (*pairing_failed)(struct bt_conn *conn,
2687 : enum bt_security_err reason);
2688 :
2689 : /** @brief Notify that bond has been deleted.
2690 : *
2691 : * This callback notifies the application that the bond information
2692 : * for the remote peer has been deleted
2693 : *
2694 : * @param id Which local identity had the bond.
2695 : * @param peer Remote address.
2696 : */
2697 1 : void (*bond_deleted)(uint8_t id, const bt_addr_le_t *peer);
2698 :
2699 : #if defined(CONFIG_BT_CLASSIC)
2700 : /** @brief Notify that bond of classic has been deleted.
2701 : *
2702 : * This callback notifies the application that the bond information of classic
2703 : * for the remote peer has been deleted
2704 : *
2705 : * @param peer Remote address.
2706 : */
2707 1 : void (*br_bond_deleted)(const bt_addr_t *peer);
2708 : #endif /* CONFIG_BT_CLASSIC */
2709 :
2710 : /** Internally used field for list handling */
2711 1 : sys_snode_t node;
2712 : };
2713 :
2714 : /** @brief Register authentication callbacks.
2715 : *
2716 : * Register callbacks to handle authenticated pairing. Passing NULL
2717 : * unregisters a previous callbacks structure.
2718 : *
2719 : * @param cb Callback struct.
2720 : *
2721 : * @return Zero on success or negative error code otherwise
2722 : */
2723 1 : int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb);
2724 :
2725 : /** @brief Overlay authentication callbacks used for a given connection.
2726 : *
2727 : * This function can be used only for Bluetooth LE connections.
2728 : * The @kconfig{CONFIG_BT_SMP} must be enabled for this function.
2729 : *
2730 : * The authentication callbacks for a given connection cannot be overlaid if
2731 : * security procedures in the SMP module have already started. This function
2732 : * can be called only once per connection.
2733 : *
2734 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
2735 : * @param cb Callback struct.
2736 : *
2737 : * @return Zero on success or negative error code otherwise
2738 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
2739 : */
2740 1 : int bt_conn_auth_cb_overlay(struct bt_conn *conn, const struct bt_conn_auth_cb *cb);
2741 :
2742 : /** @brief Register authentication information callbacks.
2743 : *
2744 : * Register callbacks to get authenticated pairing information. Multiple
2745 : * registrations can be done.
2746 : *
2747 : * @param cb Callback struct.
2748 : *
2749 : * @return Zero on success or negative error code otherwise
2750 : */
2751 1 : int bt_conn_auth_info_cb_register(struct bt_conn_auth_info_cb *cb);
2752 :
2753 : /** @brief Unregister authentication information callbacks.
2754 : *
2755 : * Unregister callbacks to stop getting authenticated pairing information.
2756 : *
2757 : * @param cb Callback struct.
2758 : *
2759 : * @return Zero on success or negative error code otherwise
2760 : */
2761 1 : int bt_conn_auth_info_cb_unregister(struct bt_conn_auth_info_cb *cb);
2762 :
2763 : /** @brief Reply with entered passkey.
2764 : *
2765 : * This function should be called only after passkey_entry callback from
2766 : * bt_conn_auth_cb structure was called.
2767 : *
2768 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
2769 : * @param passkey Entered passkey.
2770 : *
2771 : * @return Zero on success or negative error code otherwise
2772 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
2773 : */
2774 1 : int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey);
2775 :
2776 : /** @brief Send Passkey Keypress Notification during pairing
2777 : *
2778 : * This function may be called only after passkey_entry callback from
2779 : * bt_conn_auth_cb structure was called.
2780 : *
2781 : * Requires @kconfig{CONFIG_BT_PASSKEY_KEYPRESS}.
2782 : *
2783 : * @param conn @ref BT_CONN_TYPE_LE destination connection for the notification.
2784 : * @param type What keypress event type to send. @see bt_conn_auth_keypress.
2785 : *
2786 : * @retval 0 Success
2787 : * @retval -EINVAL Improper use of the API.
2788 : * @retval -ENOMEM Failed to allocate.
2789 : * @retval -ENOBUFS Failed to allocate.
2790 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE connection
2791 : */
2792 1 : int bt_conn_auth_keypress_notify(struct bt_conn *conn, enum bt_conn_auth_keypress type);
2793 :
2794 : /** @brief Cancel ongoing authenticated pairing.
2795 : *
2796 : * This function allows to cancel ongoing authenticated pairing.
2797 : *
2798 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
2799 : *
2800 : * @return Zero on success or negative error code otherwise
2801 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
2802 : */
2803 1 : int bt_conn_auth_cancel(struct bt_conn *conn);
2804 :
2805 : /** @brief Reply if passkey was confirmed to match by user.
2806 : *
2807 : * This function should be called only after passkey_confirm callback from
2808 : * bt_conn_auth_cb structure was called.
2809 : *
2810 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
2811 : *
2812 : * @return Zero on success or negative error code otherwise
2813 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
2814 : */
2815 1 : int bt_conn_auth_passkey_confirm(struct bt_conn *conn);
2816 :
2817 : /** @brief Reply if incoming pairing was confirmed by user.
2818 : *
2819 : * This function should be called only after pairing_confirm callback from
2820 : * bt_conn_auth_cb structure was called if user confirmed incoming pairing.
2821 : *
2822 : * @param conn @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection object.
2823 : *
2824 : * @return Zero on success or negative error code otherwise
2825 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_LE or @ref BT_CONN_TYPE_BR connection
2826 : */
2827 1 : int bt_conn_auth_pairing_confirm(struct bt_conn *conn);
2828 :
2829 : /** @brief Reply with entered PIN code.
2830 : *
2831 : * This function should be called only after PIN code callback from
2832 : * bt_conn_auth_cb structure was called. It's for legacy 2.0 devices.
2833 : *
2834 : * @param conn @ref BT_CONN_TYPE_BR connection object.
2835 : * @param pin Entered PIN code.
2836 : *
2837 : * @return Zero on success or negative error code otherwise
2838 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_BR connection
2839 : */
2840 1 : int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin);
2841 :
2842 : /** Connection parameters for BR/EDR connections */
2843 1 : struct bt_br_conn_param {
2844 0 : bool allow_role_switch;
2845 : };
2846 :
2847 : /** @brief Initialize BR/EDR connection parameters
2848 : *
2849 : * @param role_switch True if role switch is allowed
2850 : */
2851 1 : #define BT_BR_CONN_PARAM_INIT(role_switch) \
2852 : { \
2853 : .allow_role_switch = (role_switch), \
2854 : }
2855 :
2856 : /** Helper to declare BR/EDR connection parameters inline
2857 : *
2858 : * @param role_switch True if role switch is allowed
2859 : */
2860 1 : #define BT_BR_CONN_PARAM(role_switch) \
2861 : ((struct bt_br_conn_param[]) { \
2862 : BT_BR_CONN_PARAM_INIT(role_switch) \
2863 : })
2864 :
2865 : /** Default BR/EDR connection parameters:
2866 : * Role switch allowed
2867 : */
2868 1 : #define BT_BR_CONN_PARAM_DEFAULT BT_BR_CONN_PARAM(true)
2869 :
2870 :
2871 : /** @brief Initiate an BR/EDR connection to a remote device.
2872 : *
2873 : * Allows initiate new BR/EDR link to remote peer using its address.
2874 : *
2875 : * The caller gets a new reference to the connection object which must be
2876 : * released with bt_conn_unref() once done using the object.
2877 : *
2878 : * @param peer Remote address.
2879 : * @param param Initial connection parameters.
2880 : *
2881 : * @return Valid connection object on success or NULL otherwise.
2882 : */
2883 1 : struct bt_conn *bt_conn_create_br(const bt_addr_t *peer,
2884 : const struct bt_br_conn_param *param);
2885 :
2886 : /** @brief Look up an existing BR connection by address.
2887 : *
2888 : * Look up an existing BR connection based on the remote address.
2889 : *
2890 : * The caller gets a new reference to the connection object which must be
2891 : * released with bt_conn_unref() once done using the object.
2892 : *
2893 : * @param peer Remote address.
2894 : *
2895 : * @return Connection object or NULL if not found.
2896 : */
2897 1 : struct bt_conn *bt_conn_lookup_addr_br(const bt_addr_t *peer);
2898 :
2899 : /** @brief Get destination (peer) address of a connection.
2900 : *
2901 : * @param conn Connection object.
2902 : *
2903 : * @return Destination address if @p conn is a valid @ref BT_CONN_TYPE_BR connection
2904 : */
2905 1 : const bt_addr_t *bt_conn_get_dst_br(const struct bt_conn *conn);
2906 :
2907 : /** @brief Change the role of the conn.
2908 : *
2909 : * @param conn Connection object.
2910 : * @param role The role that want to switch as, the value is @ref BT_HCI_ROLE_CENTRAL and
2911 : * @ref BT_HCI_ROLE_PERIPHERAL from hci_types.h.
2912 : *
2913 : * @return Zero on success or (negative) error code on failure.
2914 : * @return -ENOBUFS HCI command buffer is not available.
2915 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_BR connection
2916 : */
2917 1 : int bt_conn_br_switch_role(const struct bt_conn *conn, uint8_t role);
2918 :
2919 : /** @brief Enable/disable role switch of the connection by setting the connection's link policy.
2920 : *
2921 : * @param conn Connection object.
2922 : * @param enable Value enable/disable role switch of controller.
2923 : *
2924 : * @return Zero on success or (negative) error code on failure.
2925 : * @return -ENOBUFS HCI command buffer is not available.
2926 : * @return -EINVAL @p conn is not a valid @ref BT_CONN_TYPE_BR connection.
2927 : */
2928 1 : int bt_conn_br_set_role_switch_enable(const struct bt_conn *conn, bool enable);
2929 :
2930 : #ifdef __cplusplus
2931 : }
2932 : #endif
2933 :
2934 : /**
2935 : * @}
2936 : */
2937 :
2938 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_CONN_H_ */
|
