Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Header for Bluetooth BAP.
4 : *
5 : * Copyright (c) 2020 Bose Corporation
6 : * Copyright (c) 2021-2025 Nordic Semiconductor ASA
7 : *
8 : * SPDX-License-Identifier: Apache-2.0
9 : */
10 :
11 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_
12 : #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_
13 :
14 : /**
15 : * @brief Bluetooth Basic Audio Profile (BAP)
16 : * @defgroup bt_bap Bluetooth Basic Audio Profile
17 : *
18 : * @since 3.0
19 : * @version 0.8.0
20 : *
21 : * @ingroup bluetooth
22 : * @{
23 : *
24 : * The Basic Audio Profile (BAP) allows for both unicast and broadcast Audio Stream control.
25 : */
26 :
27 : #include <stdbool.h>
28 : #include <stddef.h>
29 : #include <stdint.h>
30 :
31 : #include <zephyr/autoconf.h>
32 : #include <zephyr/bluetooth/audio/audio.h>
33 : #include <zephyr/bluetooth/addr.h>
34 : #include <zephyr/bluetooth/bluetooth.h>
35 : #include <zephyr/bluetooth/conn.h>
36 : #include <zephyr/bluetooth/gap.h>
37 : #include <zephyr/bluetooth/iso.h>
38 : #include <zephyr/bluetooth/uuid.h>
39 : #include <zephyr/net_buf.h>
40 : #include <zephyr/sys/slist.h>
41 : #include <zephyr/sys/util_macro.h>
42 :
43 : #ifdef __cplusplus
44 : extern "C" {
45 : #endif
46 :
47 : /** Maximum number of subgroups supported in the BAP Scan Delegator API */
48 1 : #define BT_BAP_BASS_MAX_SUBGROUPS \
49 : COND_CODE_1(CONFIG_BT_AUDIO, (CONFIG_BT_BAP_BASS_MAX_SUBGROUPS), (0))
50 :
51 : /** Maximum size of BASE excluding service data header */
52 1 : #define BT_BASE_MAX_SIZE (UINT8_MAX - 1 /* type */ - BT_UUID_SIZE_16)
53 :
54 : /** An invalid Broadcast ID */
55 1 : #define BT_BAP_INVALID_BROADCAST_ID 0xFFFFFFFFU
56 :
57 : /** Value that represents an unset presentation delay value */
58 1 : #define BT_BAP_PD_UNSET 0xFFFFFFFFU
59 :
60 : /**
61 : * @brief Recommended connectable advertising parameters
62 : *
63 : * If connection has not been established after 30 seconds, the device should switch to
64 : * @ref BT_BAP_ADV_PARAM_CONN_REDUCED
65 : *
66 : * Defined by Table 8.1 in BAP 1.0.2
67 : */
68 1 : #define BT_BAP_ADV_PARAM_CONN_QUICK \
69 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN | BT_LE_ADV_OPT_EXT_ADV, BT_GAP_MS_TO_ADV_INTERVAL(20), \
70 : BT_GAP_MS_TO_ADV_INTERVAL(30), NULL)
71 :
72 : /**
73 : * @brief Reduced connectable advertising parameters
74 : *
75 : * Defined by Table 8.1 in BAP 1.0.2
76 : */
77 1 : #define BT_BAP_ADV_PARAM_CONN_REDUCED \
78 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONN | BT_LE_ADV_OPT_EXT_ADV, \
79 : BT_GAP_MS_TO_ADV_INTERVAL(150), BT_GAP_MS_TO_ADV_INTERVAL(150), NULL)
80 :
81 : /**
82 : * @brief Recommended connection parameters for initial connection request for 7.5 ms SDU interval
83 : *
84 : * Once service discovery has completed and a stream is setup, it is recommended to switch to
85 : * @ref BT_BAP_CONN_PARAM_RELAXED
86 : *
87 : * Defined by Table 8.3 in BAP 1.0.2
88 : */
89 1 : #define BT_BAP_CONN_PARAM_SHORT_7_5 \
90 : BT_LE_CONN_PARAM(BT_GAP_US_TO_CONN_INTERVAL(7500), BT_GAP_MS_TO_CONN_INTERVAL(30), 0, \
91 : BT_GAP_MS_TO_CONN_TIMEOUT(4000))
92 :
93 : /**
94 : * @brief Recommended connection parameters for initial connection request for 10 ms SDU interval
95 : *
96 : * Once service discovery has completed and a stream is setup, it is recommended to switch to
97 : * @ref BT_BAP_CONN_PARAM_RELAXED
98 : *
99 : * Defined by Table 8.3 in BAP 1.0.2
100 : */
101 1 : #define BT_BAP_CONN_PARAM_SHORT_10 \
102 : BT_LE_CONN_PARAM(BT_GAP_MS_TO_CONN_INTERVAL(10), BT_GAP_MS_TO_CONN_INTERVAL(30), 0, \
103 : BT_GAP_MS_TO_CONN_TIMEOUT(4000))
104 :
105 : /**
106 : * @brief Recommended connection parameters for coexistence of ACL and ISO
107 : *
108 : * Defined by Table 8.3 in BAP 1.0.2
109 : */
110 1 : #define BT_BAP_CONN_PARAM_RELAXED \
111 : BT_LE_CONN_PARAM(BT_GAP_MS_TO_CONN_INTERVAL(50), BT_GAP_MS_TO_CONN_INTERVAL(70), 0, \
112 : BT_GAP_MS_TO_CONN_TIMEOUT(4000))
113 :
114 : /**
115 : * @brief Fast advertising parameters for broadcast audio
116 : *
117 : * This is suitable for both 7.5 ms and 10 ms SDU intervals, but prioritizes lower time to
118 : * synchronize over coexistence with ISO and power consumption.
119 : */
120 1 : #define BT_BAP_ADV_PARAM_BROADCAST_FAST \
121 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV, BT_GAP_MS_TO_ADV_INTERVAL(60), \
122 : BT_GAP_MS_TO_ADV_INTERVAL(60), NULL)
123 :
124 : /**
125 : * @brief Slow advertising parameters for broadcast audio
126 : *
127 : * This is suitable for both 7.5 ms and 10 ms SDU intervals, but prioritizes coexistence with ISO
128 : * and power consumption over lower time to synchronize.
129 : */
130 1 : #define BT_BAP_ADV_PARAM_BROADCAST_SLOW \
131 : BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV, BT_GAP_MS_TO_ADV_INTERVAL(150), \
132 : BT_GAP_MS_TO_ADV_INTERVAL(150), NULL)
133 :
134 : /**
135 : * @brief Fast advertising parameters for broadcast audio
136 : *
137 : * This is suitable for both 7.5 ms and 10 ms SDU intervals, but prioritizes lower time to
138 : * synchronize over coexistence with ISO and power consumption.
139 : */
140 1 : #define BT_BAP_PER_ADV_PARAM_BROADCAST_FAST \
141 : BT_LE_PER_ADV_PARAM(BT_GAP_MS_TO_PER_ADV_INTERVAL(60), BT_GAP_MS_TO_PER_ADV_INTERVAL(60), \
142 : BT_LE_PER_ADV_OPT_NONE)
143 :
144 : /**
145 : * @brief Slow advertising parameters for broadcast audio
146 : *
147 : * This is suitable for both 7.5 ms and 10 ms SDU intervals, but prioritizes coexistence with ISO
148 : * and power consumption over lower time to synchronize.
149 : */
150 1 : #define BT_BAP_PER_ADV_PARAM_BROADCAST_SLOW \
151 : BT_LE_PER_ADV_PARAM(BT_GAP_MS_TO_PER_ADV_INTERVAL(150), \
152 : BT_GAP_MS_TO_PER_ADV_INTERVAL(150), BT_LE_PER_ADV_OPT_NONE)
153 :
154 : /**
155 : * @brief Check if a BAP BASS BIS_Sync bitfield is valid
156 : *
157 : * Valid options are either a bitmask of valid BIS indices, including none (0x00000000)
158 : * or @ref BT_BAP_BIS_SYNC_NO_PREF (0xFFFFFFFF).
159 : *
160 : * @param _bis_bitfield BIS_Sync bitfield (uint32)
161 : */
162 1 : #define BT_BAP_BASS_VALID_BIT_BITFIELD(_bis_bitfield) \
163 : ((_bis_bitfield) == 0U || (_bis_bitfield) == BT_BAP_BIS_SYNC_NO_PREF || \
164 : BT_ISO_VALID_BIS_BITFIELD(_bis_bitfield))
165 :
166 : /**
167 : * @brief Helper to declare elements of bt_bap_qos_cfg
168 : *
169 : * @param _interval SDU interval (usec)
170 : * @param _framing Framing
171 : * @param _phy Target PHY
172 : * @param _sdu Maximum SDU Size
173 : * @param _rtn Retransmission number
174 : * @param _latency Maximum Transport Latency (msec)
175 : * @param _pd Presentation Delay (usec)
176 : */
177 1 : #define BT_BAP_QOS_CFG(_interval, _framing, _phy, _sdu, _rtn, _latency, _pd) \
178 : ((struct bt_bap_qos_cfg){ \
179 : .interval = _interval, \
180 : .framing = _framing, \
181 : .phy = _phy, \
182 : .sdu = _sdu, \
183 : .rtn = _rtn, \
184 : IF_ENABLED(UTIL_OR(IS_ENABLED(CONFIG_BT_BAP_BROADCAST_SOURCE), \
185 : IS_ENABLED(CONFIG_BT_BAP_UNICAST)), \
186 : (.latency = _latency,)) \
187 : .pd = _pd, \
188 : })
189 :
190 : /** @brief QoS Framing */
191 1 : enum bt_bap_qos_cfg_framing {
192 : /** Packets may be framed or unframed */
193 : BT_BAP_QOS_CFG_FRAMING_UNFRAMED = 0x00,
194 : /** Packets are always framed */
195 : BT_BAP_QOS_CFG_FRAMING_FRAMED = 0x01,
196 : };
197 :
198 : /** @brief QoS Preferred PHY */
199 1 : enum {
200 : /** LE 1M PHY */
201 : BT_BAP_QOS_CFG_1M = BIT(0),
202 : /** LE 2M PHY */
203 : BT_BAP_QOS_CFG_2M = BIT(1),
204 : /** LE Coded PHY */
205 : BT_BAP_QOS_CFG_CODED = BIT(2),
206 : };
207 :
208 : /**
209 : * @brief Helper to declare Input Unframed bt_bap_qos_cfg
210 : *
211 : * @param _interval SDU interval (usec)
212 : * @param _sdu Maximum SDU Size
213 : * @param _rtn Retransmission number
214 : * @param _latency Maximum Transport Latency (msec)
215 : * @param _pd Presentation Delay (usec)
216 : */
217 1 : #define BT_BAP_QOS_CFG_UNFRAMED(_interval, _sdu, _rtn, _latency, _pd) \
218 : BT_BAP_QOS_CFG(_interval, BT_BAP_QOS_CFG_FRAMING_UNFRAMED, BT_BAP_QOS_CFG_2M, _sdu, _rtn, \
219 : _latency, _pd)
220 :
221 : /**
222 : * @brief Helper to declare Input Framed bt_bap_qos_cfg
223 : *
224 : * @param _interval SDU interval (usec)
225 : * @param _sdu Maximum SDU Size
226 : * @param _rtn Retransmission number
227 : * @param _latency Maximum Transport Latency (msec)
228 : * @param _pd Presentation Delay (usec)
229 : */
230 1 : #define BT_BAP_QOS_CFG_FRAMED(_interval, _sdu, _rtn, _latency, _pd) \
231 : BT_BAP_QOS_CFG(_interval, BT_BAP_QOS_CFG_FRAMING_FRAMED, BT_BAP_QOS_CFG_2M, _sdu, _rtn, \
232 : _latency, _pd)
233 :
234 : /** @brief QoS configuration structure. */
235 1 : struct bt_bap_qos_cfg {
236 : /**
237 : * @brief Presentation Delay in microseconds
238 : *
239 : * This value can be changed up and until bt_bap_stream_qos() has been called.
240 : * Once a stream has been QoS configured, modifying this field does not modify the value.
241 : * It is however possible to modify this field and call bt_bap_stream_qos() again to update
242 : * the value, assuming that the stream is in the correct state.
243 : *
244 : * Value range 0 to @ref BT_AUDIO_PD_MAX.
245 : */
246 1 : uint32_t pd;
247 :
248 : /**
249 : * @brief Connected Isochronous Group (CIG) parameters
250 : *
251 : * The fields in this struct affect the value sent to the controller via HCI
252 : * when creating the CIG. Once the group has been created with
253 : * bt_bap_unicast_group_create(), modifying these fields will not affect the group.
254 : */
255 : struct {
256 : /** QoS Framing */
257 1 : enum bt_bap_qos_cfg_framing framing;
258 :
259 : /**
260 : * @brief PHY
261 : *
262 : * Allowed values are @ref BT_BAP_QOS_CFG_1M, @ref BT_BAP_QOS_CFG_2M and
263 : * @ref BT_BAP_QOS_CFG_CODED.
264 : */
265 1 : uint8_t phy;
266 :
267 : /**
268 : * @brief Retransmission Number
269 : *
270 : * This a recommendation to the controller, and the actual retransmission number
271 : * may be different than this.
272 : */
273 1 : uint8_t rtn;
274 :
275 : /**
276 : * @brief Maximum SDU size
277 : *
278 : * Value range @ref BT_ISO_MIN_SDU to @ref BT_ISO_MAX_SDU.
279 : */
280 1 : uint16_t sdu;
281 :
282 : #if defined(CONFIG_BT_BAP_BROADCAST_SOURCE) || defined(CONFIG_BT_BAP_UNICAST) || \
283 : defined(__DOXYGEN__)
284 : /**
285 : * @brief Maximum Transport Latency
286 : *
287 : * Not used for the @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} role.
288 : */
289 1 : uint16_t latency;
290 : #endif /* CONFIG_BT_BAP_BROADCAST_SOURCE || CONFIG_BT_BAP_UNICAST */
291 :
292 : /**
293 : * @brief SDU Interval
294 : *
295 : * Value range @ref BT_ISO_SDU_INTERVAL_MIN to @ref BT_ISO_SDU_INTERVAL_MAX
296 : */
297 1 : uint32_t interval;
298 :
299 : #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
300 : /**
301 : * @brief Maximum PDU size
302 : *
303 : * Maximum size, in octets, of the payload from link layer to link layer.
304 : *
305 : * Value range @ref BT_ISO_CONNECTED_PDU_MIN to @ref BT_ISO_PDU_MAX for
306 : * connected ISO.
307 : *
308 : * Value range @ref BT_ISO_BROADCAST_PDU_MIN to @ref BT_ISO_PDU_MAX for
309 : * broadcast ISO.
310 : */
311 1 : uint16_t max_pdu;
312 :
313 : /**
314 : * @brief Burst number
315 : *
316 : * Value range @ref BT_ISO_BN_MIN to @ref BT_ISO_BN_MAX.
317 : */
318 1 : uint8_t burst_number;
319 :
320 : /**
321 : * @brief Number of subevents
322 : *
323 : * Maximum number of subevents in each CIS or BIS event.
324 : *
325 : * Value range @ref BT_ISO_NSE_MIN to @ref BT_ISO_NSE_MAX.
326 : */
327 1 : uint8_t num_subevents;
328 : #endif /* CONFIG_BT_ISO_TEST_PARAMS */
329 1 : };
330 : };
331 :
332 : /**
333 : * @brief Helper to declare elements of @ref bt_bap_qos_cfg_pref
334 : *
335 : * @param _unframed_supported Unframed PDUs supported
336 : * @param _phy Preferred Target PHY
337 : * @param _rtn Preferred Retransmission number
338 : * @param _latency Preferred Maximum Transport Latency (msec)
339 : * @param _pd_min Minimum Presentation Delay (usec)
340 : * @param _pd_max Maximum Presentation Delay (usec)
341 : * @param _pref_pd_min Preferred Minimum Presentation Delay (usec)
342 : * @param _pref_pd_max Preferred Maximum Presentation Delay (usec)
343 : */
344 : #define BT_BAP_QOS_CFG_PREF(_unframed_supported, _phy, _rtn, _latency, _pd_min, _pd_max, \
345 1 : _pref_pd_min, _pref_pd_max) \
346 : { \
347 : .unframed_supported = _unframed_supported, .phy = _phy, .rtn = _rtn, \
348 : .latency = _latency, .pd_min = _pd_min, .pd_max = _pd_max, \
349 : .pref_pd_min = _pref_pd_min, .pref_pd_max = _pref_pd_max, \
350 : }
351 :
352 : /** @brief Audio Stream Quality of Service Preference structure. */
353 1 : struct bt_bap_qos_cfg_pref {
354 : /**
355 : * @brief Unframed PDUs supported
356 : *
357 : * Unlike the other fields, this is not a preference but whether
358 : * the codec supports unframed ISOAL PDUs.
359 : */
360 1 : bool unframed_supported;
361 :
362 : /**
363 : * @brief Preferred PHY bitfield
364 : *
365 : * Bitfield consisting of one or more of @ref BT_GAP_LE_PHY_1M, @ref BT_GAP_LE_PHY_2M and
366 : * @ref BT_GAP_LE_PHY_CODED.
367 : */
368 1 : uint8_t phy;
369 :
370 : /**
371 : * @brief Preferred Retransmission Number
372 : *
373 : * @ref BT_AUDIO_RTN_PREF_NONE indicates no preference.
374 : */
375 1 : uint8_t rtn;
376 :
377 : /**
378 : * Preferred Transport Latency
379 : *
380 : * Value range @ref BT_ISO_LATENCY_MIN to @ref BT_ISO_LATENCY_MAX
381 : */
382 1 : uint16_t latency;
383 :
384 : /**
385 : * @brief Minimum Presentation Delay in microseconds
386 : *
387 : * Unlike the other fields, this is not a preference but a minimum requirement.
388 : *
389 : * Value range 0 to @ref BT_AUDIO_PD_MAX
390 : */
391 1 : uint32_t pd_min;
392 :
393 : /**
394 : * @brief Maximum Presentation Delay in microseconds
395 : *
396 : * Unlike the other fields, this is not a preference but a maximum requirement.
397 : *
398 : * Value range @ref bt_bap_qos_cfg_pref.pd_min to @ref BT_AUDIO_PD_MAX
399 : */
400 1 : uint32_t pd_max;
401 :
402 : /**
403 : * @brief Preferred minimum Presentation Delay in microseconds
404 : *
405 : * Value range @ref bt_bap_qos_cfg_pref.pd_min to @ref bt_bap_qos_cfg_pref.pd_max, or
406 : * @ref BT_AUDIO_PD_PREF_NONE to indicate no preference.
407 : */
408 1 : uint32_t pref_pd_min;
409 :
410 : /**
411 : * @brief Preferred maximum Presentation Delay in microseconds
412 : *
413 : * Value range @ref bt_bap_qos_cfg_pref.pd_min to @ref bt_bap_qos_cfg_pref.pd_max,
414 : * and higher than or equal to @ref bt_bap_qos_cfg_pref.pref_pd_min, or
415 : * @ref BT_AUDIO_PD_PREF_NONE to indicate no preference.
416 : */
417 1 : uint32_t pref_pd_max;
418 : };
419 :
420 : /** Periodic advertising state reported by the Scan Delegator */
421 1 : enum bt_bap_pa_state {
422 : /** The periodic advertising has not been synchronized */
423 : BT_BAP_PA_STATE_NOT_SYNCED = 0x00,
424 :
425 : /** Waiting for SyncInfo from Broadcast Assistant */
426 : BT_BAP_PA_STATE_INFO_REQ = 0x01,
427 :
428 : /** Synchronized to periodic advertising */
429 : BT_BAP_PA_STATE_SYNCED = 0x02,
430 :
431 : /** Failed to synchronized to periodic advertising */
432 : BT_BAP_PA_STATE_FAILED = 0x03,
433 :
434 : /** No periodic advertising sync transfer receiver from Broadcast Assistant */
435 : BT_BAP_PA_STATE_NO_PAST = 0x04,
436 : };
437 :
438 : /** Broadcast Isochronous Group encryption state reported by the Scan Delegator */
439 1 : enum bt_bap_big_enc_state {
440 : /** The Broadcast Isochronous Group not encrypted */
441 : BT_BAP_BIG_ENC_STATE_NO_ENC = 0x00,
442 :
443 : /** The Broadcast Isochronous Group broadcast code requested */
444 : BT_BAP_BIG_ENC_STATE_BCODE_REQ = 0x01,
445 :
446 : /** The Broadcast Isochronous Group decrypted */
447 : BT_BAP_BIG_ENC_STATE_DEC = 0x02,
448 :
449 : /** The Broadcast Isochronous Group bad broadcast code */
450 : BT_BAP_BIG_ENC_STATE_BAD_CODE = 0x03,
451 : };
452 :
453 : /** Broadcast Audio Scan Service (BASS) specific ATT error codes */
454 1 : enum bt_bap_bass_att_err {
455 : /** Opcode not supported */
456 : BT_BAP_BASS_ERR_OPCODE_NOT_SUPPORTED = 0x80,
457 :
458 : /** Invalid source ID supplied */
459 : BT_BAP_BASS_ERR_INVALID_SRC_ID = 0x81,
460 : };
461 :
462 : /** Value indicating that the periodic advertising interval is unknown */
463 1 : #define BT_BAP_PA_INTERVAL_UNKNOWN 0xFFFF
464 :
465 : /**
466 : * @brief Broadcast Assistant no BIS sync preference
467 : *
468 : * Value indicating that the Broadcast Assistant has no preference to which BIS
469 : * the Scan Delegator syncs to
470 : */
471 1 : #define BT_BAP_BIS_SYNC_NO_PREF 0xFFFFFFFF
472 : /** BIS sync value indicating that the BIG sync has failed for any reason */
473 1 : #define BT_BAP_BIS_SYNC_FAILED 0xFFFFFFFF
474 :
475 : /** Endpoint states */
476 1 : enum bt_bap_ep_state {
477 : /** Audio Stream Endpoint Idle state */
478 : BT_BAP_EP_STATE_IDLE = 0x00,
479 :
480 : /** Audio Stream Endpoint Codec Configured state */
481 : BT_BAP_EP_STATE_CODEC_CONFIGURED = 0x01,
482 :
483 : /** Audio Stream Endpoint QoS Configured state */
484 : BT_BAP_EP_STATE_QOS_CONFIGURED = 0x02,
485 :
486 : /** Audio Stream Endpoint Enabling state */
487 : BT_BAP_EP_STATE_ENABLING = 0x03,
488 :
489 : /** Audio Stream Endpoint Streaming state */
490 : BT_BAP_EP_STATE_STREAMING = 0x04,
491 :
492 : /** Audio Stream Endpoint Disabling state */
493 : BT_BAP_EP_STATE_DISABLING = 0x05,
494 :
495 : /** Audio Stream Endpoint Streaming state */
496 : BT_BAP_EP_STATE_RELEASING = 0x06,
497 : };
498 :
499 : /**
500 : * @brief Response Status Code
501 : *
502 : * These are sent by the server to the client when a stream operation is
503 : * requested.
504 : */
505 1 : enum bt_bap_ascs_rsp_code {
506 : /** Server completed operation successfully */
507 : BT_BAP_ASCS_RSP_CODE_SUCCESS = 0x00,
508 : /** Server did not support operation by client */
509 : BT_BAP_ASCS_RSP_CODE_NOT_SUPPORTED = 0x01,
510 : /** Server rejected due to invalid operation length */
511 : BT_BAP_ASCS_RSP_CODE_INVALID_LENGTH = 0x02,
512 : /** Invalid ASE ID */
513 : BT_BAP_ASCS_RSP_CODE_INVALID_ASE = 0x03,
514 : /** Invalid ASE state */
515 : BT_BAP_ASCS_RSP_CODE_INVALID_ASE_STATE = 0x04,
516 : /** Invalid operation for direction */
517 : BT_BAP_ASCS_RSP_CODE_INVALID_DIR = 0x05,
518 : /** Capabilities not supported by server */
519 : BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED = 0x06,
520 : /** Configuration parameters not supported by server */
521 : BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED = 0x07,
522 : /** Configuration parameters rejected by server */
523 : BT_BAP_ASCS_RSP_CODE_CONF_REJECTED = 0x08,
524 : /** Invalid Configuration parameters */
525 : BT_BAP_ASCS_RSP_CODE_CONF_INVALID = 0x09,
526 : /** Unsupported metadata */
527 : BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED = 0x0a,
528 : /** Metadata rejected by server */
529 : BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED = 0x0b,
530 : /** Invalid metadata */
531 : BT_BAP_ASCS_RSP_CODE_METADATA_INVALID = 0x0c,
532 : /** Server has insufficient resources */
533 : BT_BAP_ASCS_RSP_CODE_NO_MEM = 0x0d,
534 : /** Unspecified error */
535 : BT_BAP_ASCS_RSP_CODE_UNSPECIFIED = 0x0e,
536 : };
537 :
538 : /**
539 : * @brief Response Reasons
540 : *
541 : * These are used if the @ref bt_bap_ascs_rsp_code value is
542 : * @ref BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED, @ref BT_BAP_ASCS_RSP_CODE_CONF_REJECTED or
543 : * @ref BT_BAP_ASCS_RSP_CODE_CONF_INVALID.
544 : */
545 1 : enum bt_bap_ascs_reason {
546 : /** No reason */
547 : BT_BAP_ASCS_REASON_NONE = 0x00,
548 : /** Codec ID */
549 : BT_BAP_ASCS_REASON_CODEC = 0x01,
550 : /** Codec configuration */
551 : BT_BAP_ASCS_REASON_CODEC_DATA = 0x02,
552 : /** SDU interval */
553 : BT_BAP_ASCS_REASON_INTERVAL = 0x03,
554 : /** Framing */
555 : BT_BAP_ASCS_REASON_FRAMING = 0x04,
556 : /** PHY */
557 : BT_BAP_ASCS_REASON_PHY = 0x05,
558 : /** Maximum SDU size*/
559 : BT_BAP_ASCS_REASON_SDU = 0x06,
560 : /** RTN */
561 : BT_BAP_ASCS_REASON_RTN = 0x07,
562 : /** Max transport latency */
563 : BT_BAP_ASCS_REASON_LATENCY = 0x08,
564 : /** Presendation delay */
565 : BT_BAP_ASCS_REASON_PD = 0x09,
566 : /** Invalid CIS mapping */
567 : BT_BAP_ASCS_REASON_CIS = 0x0a,
568 : };
569 :
570 : /** @brief Structure storing values of fields of ASE Control Point notification. */
571 1 : struct bt_bap_ascs_rsp {
572 : /**
573 : * @brief Value of the Response Code field.
574 : *
575 : * The following response codes are accepted:
576 : * - @ref BT_BAP_ASCS_RSP_CODE_SUCCESS
577 : * - @ref BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED
578 : * - @ref BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED
579 : * - @ref BT_BAP_ASCS_RSP_CODE_CONF_REJECTED
580 : * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED
581 : * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED
582 : * - @ref BT_BAP_ASCS_RSP_CODE_NO_MEM
583 : * - @ref BT_BAP_ASCS_RSP_CODE_UNSPECIFIED
584 : */
585 1 : enum bt_bap_ascs_rsp_code code;
586 :
587 : /**
588 : * @brief Value of the Reason field.
589 : *
590 : * The meaning of this value depend on the Response Code field.
591 : */
592 : union {
593 : /**
594 : * @brief Response reason
595 : *
596 : * If the Response Code is one of the following:
597 : * - @ref BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED
598 : * - @ref BT_BAP_ASCS_RSP_CODE_CONF_REJECTED
599 : * all values from @ref bt_bap_ascs_reason can be used.
600 : *
601 : * If the Response Code is one of the following:
602 : * - @ref BT_BAP_ASCS_RSP_CODE_SUCCESS
603 : * - @ref BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED
604 : * - @ref BT_BAP_ASCS_RSP_CODE_NO_MEM
605 : * - @ref BT_BAP_ASCS_RSP_CODE_UNSPECIFIED
606 : * only value @ref BT_BAP_ASCS_REASON_NONE shall be used.
607 : */
608 1 : enum bt_bap_ascs_reason reason;
609 :
610 : /**
611 : * @brief Response metadata type
612 : *
613 : * If the Response Code is one of the following:
614 : * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED
615 : * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED
616 : * the value of the Metadata Type shall be used.
617 : */
618 1 : enum bt_audio_metadata_type metadata_type;
619 1 : };
620 : };
621 :
622 : /**
623 : * @brief Macro used to initialise the object storing values of ASE Control Point notification.
624 : *
625 : * @param c Response Code field
626 : * @param r Reason field - @ref bt_bap_ascs_reason or @ref bt_audio_metadata_type (see notes in
627 : * @ref bt_bap_ascs_rsp).
628 : */
629 1 : #define BT_BAP_ASCS_RSP(c, r) (struct bt_bap_ascs_rsp) { .code = c, .reason = r }
630 :
631 : /** @brief Abstract Audio Broadcast Source structure. */
632 : struct bt_bap_broadcast_source;
633 :
634 : /** @brief Abstract Audio Broadcast Sink structure. */
635 : struct bt_bap_broadcast_sink;
636 :
637 : /** @brief Abstract Audio Unicast Group structure. */
638 : struct bt_bap_unicast_group;
639 :
640 : /** @brief Abstract Audio Endpoint structure. */
641 : struct bt_bap_ep;
642 :
643 : /** Struct to hold subgroup specific information for the receive state */
644 1 : struct bt_bap_bass_subgroup {
645 : /** BIS synced bitfield */
646 1 : uint32_t bis_sync;
647 :
648 : /** Length of the metadata */
649 1 : uint8_t metadata_len;
650 :
651 : #if defined(CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE) || defined(__DOXYGEN__)
652 : /** The metadata */
653 1 : uint8_t metadata[CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE];
654 : #endif /* CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE */
655 : };
656 :
657 : /** Represents the Broadcast Audio Scan Service receive state */
658 1 : struct bt_bap_scan_delegator_recv_state {
659 : /** The source ID */
660 1 : uint8_t src_id;
661 :
662 : /** The Bluetooth address */
663 1 : bt_addr_le_t addr;
664 :
665 : /** The advertising set ID*/
666 1 : uint8_t adv_sid;
667 :
668 : /** The periodic adverting sync state */
669 1 : enum bt_bap_pa_state pa_sync_state;
670 :
671 : /** The broadcast isochronous group encryption state */
672 1 : enum bt_bap_big_enc_state encrypt_state;
673 :
674 : /** The 24-bit broadcast ID */
675 1 : uint32_t broadcast_id;
676 :
677 : /**
678 : * @brief The bad broadcast code
679 : *
680 : * Only valid if encrypt_state is @ref BT_BAP_BIG_ENC_STATE_BCODE_REQ
681 : */
682 1 : uint8_t bad_code[BT_ISO_BROADCAST_CODE_SIZE];
683 :
684 : /** Number of subgroups */
685 1 : uint8_t num_subgroups;
686 :
687 : /** Subgroup specific information
688 : *
689 : * If the @ref bt_bap_bass_subgroup.bis_sync value is @ref BT_BAP_BIS_SYNC_FAILED then it
690 : * indicates that the BIG sync failed.
691 : */
692 1 : struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS];
693 : };
694 :
695 : /**
696 : * @brief Struct to hold the Basic Audio Profile Scan Delegator callbacks
697 : *
698 : * These can be registered for usage with bt_bap_scan_delegator_register().
699 : */
700 1 : struct bt_bap_scan_delegator_cb {
701 : /**
702 : * @brief Receive state updated
703 : *
704 : * @param conn Pointer to the connection to a remote device if
705 : * the change was caused by it, otherwise NULL.
706 : * @param recv_state Pointer to the receive state that was updated.
707 : *
708 : * @return 0 in case of success or negative value in case of error.
709 : */
710 1 : void (*recv_state_updated)(struct bt_conn *conn,
711 : const struct bt_bap_scan_delegator_recv_state *recv_state);
712 :
713 : /**
714 : * @brief Periodic advertising sync request
715 : *
716 : * Request from peer device to synchronize with the periodic advertiser
717 : * denoted by the @p recv_state. To notify the Broadcast Assistant about
718 : * any pending sync
719 : *
720 : * @param conn Pointer to the connection requesting the
721 : * periodic advertising sync.
722 : * @param recv_state Pointer to the receive state that is being
723 : * requested for periodic advertising sync.
724 : * @param past_avail True if periodic advertising sync transfer is available.
725 : * @param pa_interval The periodic advertising interval.
726 : *
727 : * @return 0 in case of accept, or other value to reject.
728 : */
729 1 : int (*pa_sync_req)(struct bt_conn *conn,
730 : const struct bt_bap_scan_delegator_recv_state *recv_state,
731 : bool past_avail, uint16_t pa_interval);
732 :
733 : /**
734 : * @brief Periodic advertising sync termination request
735 : *
736 : * Request from peer device to terminate the periodic advertiser sync
737 : * denoted by the @p recv_state.
738 : *
739 : * @param conn Pointer to the connection requesting the periodic
740 : * advertising sync termination.
741 : * @param recv_state Pointer to the receive state that is being
742 : * requested for periodic advertising sync.
743 : *
744 : * @return 0 in case of success or negative value in case of error.
745 : */
746 1 : int (*pa_sync_term_req)(struct bt_conn *conn,
747 : const struct bt_bap_scan_delegator_recv_state *recv_state);
748 :
749 : /**
750 : * @brief Broadcast code received
751 : *
752 : * Broadcast code received from a broadcast assistant
753 : *
754 : * @param conn Pointer to the connection providing the
755 : * broadcast code.
756 : * @param recv_state Pointer to the receive state the broadcast code
757 : * is being provided for.
758 : * @param broadcast_code The 16-octet broadcast code
759 : */
760 1 : void (*broadcast_code)(struct bt_conn *conn,
761 : const struct bt_bap_scan_delegator_recv_state *recv_state,
762 : const uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]);
763 : /**
764 : * @brief Broadcast Isochronous Stream synchronize request
765 : *
766 : * Request from Broadcast Assistant device to modify the Broadcast
767 : * Isochronous Stream states. The request shall be fulfilled with
768 : * accordance to the @p bis_sync_req within reasonable time. The
769 : * Broadcast Assistant may also request fewer, or none, indexes to
770 : * be synchronized.
771 : *
772 : * @param[in] conn Pointer to the connection of the
773 : * Broadcast Assistant requesting the sync.
774 : * @param[in] recv_state Pointer to the receive state that is being
775 : * requested for the sync.
776 : * @param[in] bis_sync_req Array of bitfields of which BIS indexes
777 : * that is requested to sync for each subgroup
778 : * by the Broadcast Assistant. A value of 0
779 : * indicates a request to terminate the BIG
780 : * sync.
781 : *
782 : * @return 0 in case of accept, or other value to reject.
783 : */
784 1 : int (*bis_sync_req)(struct bt_conn *conn,
785 : const struct bt_bap_scan_delegator_recv_state *recv_state,
786 : const uint32_t bis_sync_req[BT_BAP_BASS_MAX_SUBGROUPS]);
787 : /**
788 : * @brief Broadcast Assistant scanning state callback
789 : *
790 : * Callback triggered when a Broadcast Assistant notifies the Scan Delegator about the
791 : * assistants scanning state.
792 : *
793 : * @param conn Pointer to the connection that initiated the scan.
794 : * @param is_scanning true if scanning started, false if scanning stopped.
795 : */
796 1 : void (*scanning_state)(struct bt_conn *conn, bool is_scanning);
797 : /**
798 : * @brief Add Source operation callback
799 : *
800 : * These callbacks notify the application when a request comes
801 : * in to add a source. The application can return 0 to
802 : * accept or any other value to reject the request.
803 : *
804 : * @param conn Pointer to the connection that initiated the request,
805 : * or NULL if locally triggered.
806 : * @param recv_state Pointer to the requested receive state to be added.
807 : *
808 : * @return 0 in case of accept, or other value to reject.
809 : */
810 1 : int (*add_source)(struct bt_conn *conn,
811 : const struct bt_bap_scan_delegator_recv_state *recv_state);
812 :
813 : /**
814 : * @brief Modify Source operation callback
815 : *
816 : * These callbacks notify the application when a request comes
817 : * in to modify a source. The application can return 0 to
818 : * accept or any other value to reject the request.
819 : *
820 : * @param conn Pointer to the connection that initiated the request,
821 : * or NULL if locally triggered.
822 : * @param recv_state Pointer to the requested receive state to be modified.
823 : *
824 : * @return 0 in case of accept, or other value to reject.
825 : */
826 1 : int (*modify_source)(struct bt_conn *conn,
827 : const struct bt_bap_scan_delegator_recv_state *recv_state);
828 :
829 : /**
830 : * @brief Remove Source operation callback
831 : *
832 : * These callbacks notify the application when a request comes
833 : * in to remove a source. The application can return 0 to
834 : * accept or any other value to reject the request.
835 : *
836 : * @param conn Pointer to the connection that initiated the request,
837 : * or NULL if locally triggered.
838 : * @param src_id The Source ID that is requested to be removed.
839 : *
840 : * @return 0 in case of accept, or other value to reject.
841 : */
842 1 : int (*remove_source)(struct bt_conn *conn, uint8_t src_id);
843 : };
844 :
845 : /** Structure holding information of audio stream endpoint */
846 1 : struct bt_bap_ep_info {
847 : /** The ID of the endpoint */
848 1 : uint8_t id;
849 :
850 : /** The state of the endpoint */
851 1 : enum bt_bap_ep_state state;
852 :
853 : /** Capabilities type */
854 1 : enum bt_audio_dir dir;
855 :
856 : /** The isochronous channel associated with the endpoint. */
857 1 : struct bt_iso_chan *iso_chan;
858 :
859 : /** @brief True if the stream associated with the endpoint is able to send data */
860 1 : bool can_send;
861 :
862 : /** @brief True if the stream associated with the endpoint is able to receive data */
863 1 : bool can_recv;
864 :
865 : /** Pointer to paired endpoint if the endpoint is part of a bidirectional CIS,
866 : * otherwise NULL
867 : */
868 1 : struct bt_bap_ep *paired_ep;
869 :
870 : /** Pointer to the preferred QoS settings associated with the endpoint */
871 1 : const struct bt_bap_qos_cfg_pref *qos_pref;
872 : };
873 :
874 : /**
875 : * @brief Return structure holding information of audio stream endpoint
876 : *
877 : * @param ep The audio stream endpoint object.
878 : * @param info The structure object to be filled with the info.
879 : *
880 : * @retval 0 in case of success
881 : * @retval -EINVAL if @p ep or @p info are NULL
882 : */
883 1 : int bt_bap_ep_get_info(const struct bt_bap_ep *ep, struct bt_bap_ep_info *info);
884 :
885 : /**
886 : * @brief Basic Audio Profile stream structure.
887 : *
888 : * Streams represents a stream configuration of a Remote Endpoint and a Local Capability.
889 : *
890 : * @note Streams are unidirectional but can be paired with other streams to use a bidirectional
891 : * connected isochronous stream.
892 : */
893 1 : struct bt_bap_stream {
894 : /** Connection reference */
895 1 : struct bt_conn *conn;
896 :
897 : /** Endpoint reference */
898 1 : struct bt_bap_ep *ep;
899 :
900 : /** Codec Configuration */
901 1 : struct bt_audio_codec_cfg *codec_cfg;
902 :
903 : /** QoS Configuration */
904 1 : struct bt_bap_qos_cfg *qos;
905 :
906 : /** Audio stream operations */
907 1 : struct bt_bap_stream_ops *ops;
908 :
909 : /** Stream user data */
910 1 : void *user_data;
911 :
912 : /** ISO channel reference
913 : *
914 : * This will become valid once the stream is added to a group (bt_bap_unicast_group,
915 : * bt_bap_broadcast_source or bt_bap_broadcast_sink).
916 : */
917 1 : struct bt_iso_chan *iso;
918 :
919 : /** Unicast or Broadcast group - Used internally */
920 1 : void *group;
921 :
922 : #if defined(CONFIG_BT_BAP_DEBUG_STREAM_SEQ_NUM) || defined(__DOXYGEN__)
923 : /** Previously sent sequence number */
924 : uint16_t _prev_seq_num;
925 : #endif /* CONFIG_BT_BAP_DEBUG_STREAM_SEQ_NUM */
926 :
927 : /** @cond INTERNAL_HIDDEN */
928 : /** Internally used list node */
929 : sys_snode_t _node;
930 : /** @endcond */
931 : };
932 :
933 : /** @brief Stream operation. */
934 1 : struct bt_bap_stream_ops {
935 : #if defined(CONFIG_BT_BAP_UNICAST) || defined(__DOXYGEN__)
936 : /**
937 : * @brief Stream configured callback
938 : *
939 : * Configured callback is called whenever an Audio Stream has been configured.
940 : *
941 : * @param stream Stream object that has been configured.
942 : * @param pref Remote QoS preferences.
943 : */
944 1 : void (*configured)(struct bt_bap_stream *stream, const struct bt_bap_qos_cfg_pref *pref);
945 :
946 : /**
947 : * @brief Stream QoS set callback
948 : *
949 : * QoS set callback is called whenever an Audio Stream Quality of Service has been set or
950 : * updated.
951 : *
952 : * @param stream Stream object that had its QoS updated.
953 : */
954 1 : void (*qos_set)(struct bt_bap_stream *stream);
955 :
956 : /**
957 : * @brief Stream enabled callback
958 : *
959 : * Enabled callback is called whenever an Audio Stream has been enabled.
960 : *
961 : * @param stream Stream object that has been enabled.
962 : */
963 1 : void (*enabled)(struct bt_bap_stream *stream);
964 :
965 : /**
966 : * @brief Stream metadata updated callback
967 : *
968 : * Metadata Updated callback is called whenever an Audio Stream's metadata has been
969 : * updated.
970 : *
971 : * @param stream Stream object that had its metadata updated.
972 : */
973 1 : void (*metadata_updated)(struct bt_bap_stream *stream);
974 :
975 : /**
976 : * @brief Stream disabled callback
977 : *
978 : * Disabled callback is called whenever an Audio Stream has been disabled.
979 : *
980 : * @param stream Stream object that has been disabled.
981 : */
982 1 : void (*disabled)(struct bt_bap_stream *stream);
983 :
984 : /**
985 : * @brief Stream released callback
986 : *
987 : * Released callback is called whenever a Audio Stream has been released and can be
988 : * deallocated.
989 : *
990 : * @param stream Stream object that has been released.
991 : */
992 1 : void (*released)(struct bt_bap_stream *stream);
993 : #endif /* CONFIG_BT_BAP_UNICAST */
994 :
995 : /**
996 : * @brief Stream started callback
997 : *
998 : * Started callback is called whenever an Audio Stream has been started
999 : * and will be usable for streaming.
1000 : *
1001 : * @param stream Stream object that has been started.
1002 : */
1003 1 : void (*started)(struct bt_bap_stream *stream);
1004 :
1005 : /**
1006 : * @brief Stream stopped callback
1007 : *
1008 : * Stopped callback is called whenever an Audio Stream has been stopped.
1009 : *
1010 : * @param stream Stream object that has been stopped.
1011 : * @param reason BT_HCI_ERR_* reason for the disconnection.
1012 : */
1013 1 : void (*stopped)(struct bt_bap_stream *stream, uint8_t reason);
1014 :
1015 : #if defined(CONFIG_BT_AUDIO_RX) || defined(__DOXYGEN__)
1016 : /**
1017 : * @brief Stream audio HCI receive callback.
1018 : *
1019 : * This callback is only used if the ISO data path is HCI.
1020 : *
1021 : * @param stream Stream object.
1022 : * @param info Pointer to the metadata for the buffer. The lifetime of the pointer is
1023 : * linked to the lifetime of the net_buf. Metadata such as sequence number and
1024 : * timestamp can be provided by the bluetooth controller.
1025 : * @param buf Buffer containing incoming audio data.
1026 : */
1027 1 : void (*recv)(struct bt_bap_stream *stream, const struct bt_iso_recv_info *info,
1028 : struct net_buf *buf);
1029 : #endif /* CONFIG_BT_AUDIO_RX */
1030 :
1031 : #if defined(CONFIG_BT_AUDIO_TX) || defined(__DOXYGEN__)
1032 : /**
1033 : * @brief Stream audio HCI sent callback
1034 : *
1035 : * This callback will be called once the controller marks the SDU
1036 : * as completed. When the controller does so is implementation
1037 : * dependent. It could be after the SDU is enqueued for transmission,
1038 : * or after it is sent on air or flushed.
1039 : *
1040 : * This callback is only used if the ISO data path is HCI.
1041 : *
1042 : * @param stream Stream object.
1043 : */
1044 1 : void (*sent)(struct bt_bap_stream *stream);
1045 : #endif /* CONFIG_BT_AUDIO_TX */
1046 :
1047 : /**
1048 : * @brief Isochronous channel connected callback
1049 : *
1050 : * If this callback is provided it will be called whenever the isochronous channel for the
1051 : * stream has been connected. This does not mean that the stream is ready to be used, which
1052 : * is indicated by the @ref bt_bap_stream_ops.started callback.
1053 : *
1054 : * If the stream shares an isochronous channel with another stream, then this callback may
1055 : * still be called, without the stream going into the started state.
1056 : *
1057 : * @param stream Stream object.
1058 : */
1059 1 : void (*connected)(struct bt_bap_stream *stream);
1060 :
1061 : /**
1062 : * @brief Isochronous channel disconnected callback
1063 : *
1064 : * If this callback is provided it will be called whenever the isochronous channel is
1065 : * disconnected, including when a connection gets rejected.
1066 : *
1067 : * If the stream shares an isochronous channel with another stream, then this callback may
1068 : * not be called, even if the stream is leaving the streaming state.
1069 : *
1070 : * @param stream Stream object.
1071 : * @param reason BT_HCI_ERR_* reason for the disconnection.
1072 : */
1073 1 : void (*disconnected)(struct bt_bap_stream *stream, uint8_t reason);
1074 : };
1075 :
1076 : /** Structure for registering Unicast Server */
1077 1 : struct bt_bap_unicast_server_register_param {
1078 : /**
1079 : * @brief Sink Count to register.
1080 : *
1081 : * Should be in range 0 to @kconfig{CONFIG_BT_ASCS_MAX_ASE_SNK_COUNT}
1082 : */
1083 1 : uint8_t snk_cnt;
1084 :
1085 : /** @brief Source Count to register.
1086 : *
1087 : * Should be in range 0 to @kconfig{CONFIG_BT_ASCS_MAX_ASE_SRC_COUNT}
1088 : */
1089 1 : uint8_t src_cnt;
1090 : };
1091 :
1092 : /**
1093 : * @brief Register Audio callbacks for a stream.
1094 : *
1095 : * Register Audio callbacks for a stream.
1096 : *
1097 : * @param stream Stream object.
1098 : * @param ops Stream operations structure.
1099 : */
1100 1 : void bt_bap_stream_cb_register(struct bt_bap_stream *stream, struct bt_bap_stream_ops *ops);
1101 :
1102 : /**
1103 : * @brief Configure Audio Stream
1104 : *
1105 : * This procedure is used by a client to configure a new stream using the
1106 : * remote endpoint, local capability and codec configuration.
1107 : *
1108 : * @param conn Connection object
1109 : * @param stream Stream object being configured
1110 : * @param ep Remote Audio Endpoint being configured
1111 : * @param codec_cfg Codec configuration
1112 : *
1113 : * @return Allocated Audio Stream object or NULL in case of error.
1114 : */
1115 1 : int bt_bap_stream_config(struct bt_conn *conn, struct bt_bap_stream *stream, struct bt_bap_ep *ep,
1116 : struct bt_audio_codec_cfg *codec_cfg);
1117 :
1118 : /**
1119 : * @brief Reconfigure Audio Stream
1120 : *
1121 : * This procedure is used by a unicast client or unicast server to reconfigure
1122 : * a stream to use a different local codec configuration.
1123 : *
1124 : * This can only be done for unicast streams.
1125 : *
1126 : * @param stream Stream object being reconfigured
1127 : * @param codec_cfg Codec configuration
1128 : *
1129 : * @return 0 in case of success or negative value in case of error.
1130 : */
1131 1 : int bt_bap_stream_reconfig(struct bt_bap_stream *stream, struct bt_audio_codec_cfg *codec_cfg);
1132 :
1133 : /**
1134 : * @brief Configure Audio Stream QoS
1135 : *
1136 : * This procedure is used by a client to configure the Quality of Service of streams in a unicast
1137 : * group. All streams in the group for the specified @p conn will have the Quality of Service
1138 : * configured. This shall only be used to configure unicast streams.
1139 : *
1140 : * @param conn Connection object
1141 : * @param group Unicast group object
1142 : *
1143 : * @return 0 in case of success or negative value in case of error.
1144 : */
1145 1 : int bt_bap_stream_qos(struct bt_conn *conn, struct bt_bap_unicast_group *group);
1146 :
1147 : /**
1148 : * @brief Enable Audio Stream
1149 : *
1150 : * This procedure is used by a client to enable a stream.
1151 : *
1152 : * This shall only be called for unicast streams, as broadcast streams will always be enabled once
1153 : * created.
1154 : *
1155 : * @param stream Stream object
1156 : * @param meta Metadata
1157 : * @param meta_len Metadata length
1158 : *
1159 : * @return 0 in case of success or negative value in case of error.
1160 : */
1161 1 : int bt_bap_stream_enable(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len);
1162 :
1163 : /**
1164 : * @brief Change Audio Stream Metadata
1165 : *
1166 : * This procedure is used by a unicast client or unicast server to change the metadata of a stream.
1167 : *
1168 : * @param stream Stream object
1169 : * @param meta Metadata
1170 : * @param meta_len Metadata length
1171 : *
1172 : * @return 0 in case of success or negative value in case of error.
1173 : */
1174 1 : int bt_bap_stream_metadata(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len);
1175 :
1176 : /**
1177 : * @brief Disable Audio Stream
1178 : *
1179 : * This procedure is used by a unicast client or unicast server to disable a stream.
1180 : *
1181 : * This shall only be called for unicast streams, as broadcast streams will
1182 : * always be enabled once created.
1183 : *
1184 : * @param stream Stream object
1185 : *
1186 : * @return 0 in case of success or negative value in case of error.
1187 : */
1188 1 : int bt_bap_stream_disable(struct bt_bap_stream *stream);
1189 :
1190 : /**
1191 : * @brief Connect unicast audio stream
1192 : *
1193 : * This procedure is used by a unicast client to connect the connected isochronous stream (CIS)
1194 : * associated with the audio stream. If two audio streams share a CIS, then this only needs to be
1195 : * done once for those streams. This can only be done for streams in the QoS configured or enabled
1196 : * states.
1197 : *
1198 : * The bt_bap_stream_ops.connected() callback will be called on the streams once this has finished.
1199 : *
1200 : * This shall only be called for unicast streams, and only as the unicast client
1201 : * (@kconfig{CONFIG_BT_BAP_UNICAST_CLIENT}).
1202 : *
1203 : * @param stream Stream object
1204 : *
1205 : * @retval 0 in case of success
1206 : * @retval -EINVAL if the stream, endpoint, ISO channel or connection is NULL
1207 : * @retval -EBADMSG if the stream or ISO channel is in an invalid state for connection
1208 : * @retval -EOPNOTSUPP if the role of the stream is not @ref BT_HCI_ROLE_CENTRAL
1209 : * @retval -EALREADY if the ISO channel is already connecting or connected
1210 : * @retval -EBUSY if another ISO channel is connecting
1211 : * @retval -ENOEXEC if otherwise rejected by the ISO layer
1212 : */
1213 1 : int bt_bap_stream_connect(struct bt_bap_stream *stream);
1214 :
1215 : /**
1216 : * @brief Start Audio Stream
1217 : *
1218 : * This procedure is used by a unicast client or unicast server to make a stream start streaming.
1219 : *
1220 : * For the unicast client, this will send the receiver start ready command to the unicast server for
1221 : * @ref BT_AUDIO_DIR_SOURCE ASEs. The CIS is required to be connected first by
1222 : * bt_bap_stream_connect() before the command can be sent.
1223 : *
1224 : * For the unicast server, this will execute the receiver start ready command on the unicast server
1225 : * for @ref BT_AUDIO_DIR_SINK ASEs. If the CIS is not connected yet, the stream will go into the
1226 : * streaming state as soon as the CIS is connected.
1227 : *
1228 : * This shall only be called for unicast streams.
1229 : *
1230 : * Broadcast sinks will always be started once synchronized, and broadcast
1231 : * source streams shall be started with bt_bap_broadcast_source_start().
1232 : *
1233 : * @param stream Stream object
1234 : *
1235 : * @return 0 in case of success or negative value in case of error.
1236 : */
1237 1 : int bt_bap_stream_start(struct bt_bap_stream *stream);
1238 :
1239 : /**
1240 : * @brief Stop Audio Stream
1241 : *
1242 : * This procedure is used by a client to make a stream stop streaming.
1243 : *
1244 : * This shall only be called for unicast streams.
1245 : * Broadcast sinks cannot be stopped.
1246 : * Broadcast sources shall be stopped with bt_bap_broadcast_source_stop().
1247 : *
1248 : * @param stream Stream object
1249 : *
1250 : * @retval 0 Success
1251 : * @retval -EINVAL The @p stream does not have an endpoint or a connection, of the stream's
1252 : * connection's role is not @p BT_HCI_ROLE_CENTRAL
1253 : * @retval -EBADMSG The state of the @p stream endpoint is not @ref BT_BAP_EP_STATE_DISABLING
1254 : * @retval -EALREADY The CIS state of the @p is not in a connected state, and thus is already
1255 : * stopping
1256 : * @retval -EBUSY The @p stream is busy with another operation
1257 : * @retval -ENOTCONN The @p stream ACL connection is not connected
1258 : * @retval -ENOMEM No memory to send request
1259 : * @retval -ENOEXEC The request was rejected by GATT
1260 : * @return 0 in case of success or negative value in case of error.
1261 : */
1262 1 : int bt_bap_stream_stop(struct bt_bap_stream *stream);
1263 :
1264 : /**
1265 : * @brief Release Audio Stream
1266 : *
1267 : * This procedure is used by a unicast client or unicast server to release a unicast stream.
1268 : *
1269 : * Broadcast sink streams cannot be released, but can be deleted by bt_bap_broadcast_sink_delete().
1270 : * Broadcast source streams cannot be released, but can be deleted by
1271 : * bt_bap_broadcast_source_delete().
1272 : *
1273 : * @param stream Stream object
1274 : *
1275 : * @return 0 in case of success or negative value in case of error.
1276 : */
1277 1 : int bt_bap_stream_release(struct bt_bap_stream *stream);
1278 :
1279 : /**
1280 : * @brief Send data to Audio stream without timestamp
1281 : *
1282 : * Send data from buffer to the stream.
1283 : *
1284 : * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}.
1285 : *
1286 : * @param stream Stream object.
1287 : * @param buf Buffer containing data to be sent.
1288 : * @param seq_num Packet Sequence number. This value shall be incremented for each call to this
1289 : * function and at least once per SDU interval for a specific channel.
1290 : *
1291 : * @return Bytes sent in case of success or negative value in case of error.
1292 : */
1293 1 : int bt_bap_stream_send(struct bt_bap_stream *stream, struct net_buf *buf, uint16_t seq_num);
1294 :
1295 : /**
1296 : * @brief Send data to Audio stream with timestamp
1297 : *
1298 : * Send data from buffer to the stream.
1299 : *
1300 : * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}.
1301 : *
1302 : * @param stream Stream object.
1303 : * @param buf Buffer containing data to be sent.
1304 : * @param seq_num Packet Sequence number. This value shall be incremented for each call to this
1305 : * function and at least once per SDU interval for a specific channel.
1306 : * @param ts Timestamp of the SDU in microseconds (us). This value can be used to transmit
1307 : * multiple SDUs in the same SDU interval in a CIG or BIG.
1308 : *
1309 : * @return Bytes sent in case of success or negative value in case of error.
1310 : */
1311 1 : int bt_bap_stream_send_ts(struct bt_bap_stream *stream, struct net_buf *buf, uint16_t seq_num,
1312 : uint32_t ts);
1313 :
1314 : /**
1315 : * @brief Get ISO transmission timing info for a Basic Audio Profile stream
1316 : *
1317 : * Reads timing information for transmitted ISO packet on an ISO channel.
1318 : * The HCI_LE_Read_ISO_TX_Sync HCI command is used to retrieve this information from the controller.
1319 : *
1320 : * @note An SDU must have already been successfully transmitted on the ISO channel
1321 : * for this function to return successfully.
1322 : * Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}.
1323 : *
1324 : * @param[in] stream Stream object.
1325 : * @param[out] info Transmit info object.
1326 : *
1327 : * @retval 0 on success
1328 : * @retval -EINVAL if the stream is invalid, if the stream is not configured for sending or if it is
1329 : * not connected with a isochronous stream
1330 : * @retval Any return value from bt_iso_chan_get_tx_sync()
1331 : */
1332 1 : int bt_bap_stream_get_tx_sync(struct bt_bap_stream *stream, struct bt_iso_tx_info *info);
1333 :
1334 : /**
1335 : * @defgroup bt_bap_unicast_server BAP Unicast Server APIs
1336 : * @ingroup bt_bap
1337 : * @{
1338 : */
1339 :
1340 : /** Unicast Server callback structure */
1341 1 : struct bt_bap_unicast_server_cb {
1342 : /**
1343 : * @brief Endpoint config request callback
1344 : *
1345 : * Config callback is called whenever an endpoint is requested to be
1346 : * configured
1347 : *
1348 : * @param[in] conn Connection object.
1349 : * @param[in] ep Local Audio Endpoint being configured.
1350 : * @param[in] dir Direction of the endpoint.
1351 : * @param[in] codec_cfg Codec configuration.
1352 : * @param[out] stream Pointer to stream that will be configured for the endpoint.
1353 : * @param[out] pref Pointer to a QoS preference object that shall be populated with
1354 : * values. Invalid values will reject the codec configuration request.
1355 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1356 : * value is non-zero.
1357 : *
1358 : * @return 0 in case of success or negative value in case of error.
1359 : */
1360 1 : int (*config)(struct bt_conn *conn, const struct bt_bap_ep *ep, enum bt_audio_dir dir,
1361 : const struct bt_audio_codec_cfg *codec_cfg, struct bt_bap_stream **stream,
1362 : struct bt_bap_qos_cfg_pref *const pref, struct bt_bap_ascs_rsp *rsp);
1363 :
1364 : /**
1365 : * @brief Stream reconfig request callback
1366 : *
1367 : * Reconfig callback is called whenever an Audio Stream needs to be
1368 : * reconfigured with different codec configuration.
1369 : *
1370 : * @param[in] stream Stream object being reconfigured.
1371 : * @param[in] dir Direction of the endpoint.
1372 : * @param[in] codec_cfg Codec configuration.
1373 : * @param[out] pref Pointer to a QoS preference object that shall be populated with
1374 : * values. Invalid values will reject the codec configuration request.
1375 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1376 : * value is non-zero.
1377 : *
1378 : * @return 0 in case of success or negative value in case of error.
1379 : */
1380 1 : int (*reconfig)(struct bt_bap_stream *stream, enum bt_audio_dir dir,
1381 : const struct bt_audio_codec_cfg *codec_cfg,
1382 : struct bt_bap_qos_cfg_pref *const pref, struct bt_bap_ascs_rsp *rsp);
1383 :
1384 : /**
1385 : * @brief Stream QoS request callback
1386 : *
1387 : * QoS callback is called whenever an Audio Stream Quality of
1388 : * Service needs to be configured.
1389 : *
1390 : * @param[in] stream Stream object being reconfigured.
1391 : * @param[in] qos Quality of Service configuration.
1392 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1393 : * value is non-zero.
1394 : *
1395 : * @return 0 in case of success or negative value in case of error.
1396 : */
1397 1 : int (*qos)(struct bt_bap_stream *stream, const struct bt_bap_qos_cfg *qos,
1398 : struct bt_bap_ascs_rsp *rsp);
1399 :
1400 : /**
1401 : * @brief Stream Enable request callback
1402 : *
1403 : * Enable callback is called whenever an Audio Stream is requested to be enabled to stream.
1404 : *
1405 : * @param[in] stream Stream object being enabled.
1406 : * @param[in] meta Metadata entries.
1407 : * @param[in] meta_len Length of metadata.
1408 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1409 : * value is non-zero.
1410 : *
1411 : * @return 0 in case of success or negative value in case of error.
1412 : */
1413 1 : int (*enable)(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len,
1414 : struct bt_bap_ascs_rsp *rsp);
1415 :
1416 : /**
1417 : * @brief Stream Start request callback
1418 : *
1419 : * Start callback is called whenever an Audio Stream is requested to start streaming.
1420 : *
1421 : * @param[in] stream Stream object.
1422 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1423 : * value is non-zero.
1424 : *
1425 : * @return 0 in case of success or negative value in case of error.
1426 : */
1427 1 : int (*start)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp);
1428 :
1429 : /**
1430 : * @brief Stream Metadata update request callback
1431 : *
1432 : * Metadata callback is called whenever an Audio Stream is requested to update its metadata.
1433 : *
1434 : * @param[in] stream Stream object.
1435 : * @param[in] meta Metadata entries.
1436 : * @param[in] meta_len Length of metadata.
1437 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1438 : * value is non-zero.
1439 : *
1440 : * @return 0 in case of success or negative value in case of error.
1441 : */
1442 1 : int (*metadata)(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len,
1443 : struct bt_bap_ascs_rsp *rsp);
1444 :
1445 : /**
1446 : * @brief Stream Disable request callback
1447 : *
1448 : * Disable callback is called whenever an Audio Stream is requested to disable the stream.
1449 : *
1450 : * @param[in] stream Stream object being disabled.
1451 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1452 : * value is non-zero.
1453 : *
1454 : * @return 0 in case of success or negative value in case of error.
1455 : */
1456 1 : int (*disable)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp);
1457 :
1458 : /**
1459 : * @brief Stream Stop callback
1460 : *
1461 : * Stop callback is called whenever an Audio Stream is requested to stop streaming.
1462 : *
1463 : * @param[in] stream Stream object.
1464 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1465 : * value is non-zero.
1466 : *
1467 : * @return 0 in case of success or negative value in case of error.
1468 : */
1469 1 : int (*stop)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp);
1470 :
1471 : /**
1472 : * @brief Stream release callback
1473 : *
1474 : * Release callback is called whenever a new Audio Stream needs to be released and thus
1475 : * deallocated.
1476 : *
1477 : * @param[in] stream Stream object.
1478 : * @param[out] rsp Object for the ASE operation response. Only used if the return
1479 : * value is non-zero.
1480 : *
1481 : * @return 0 in case of success or negative value in case of error.
1482 : */
1483 1 : int (*release)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp);
1484 : };
1485 :
1486 : /**
1487 : * @brief Register the Unicast Server.
1488 : *
1489 : * Register the Unicast Server. Only a single Unicast Server can be registered at any one time.
1490 : * This will register ASCS in the GATT database.
1491 : *
1492 : * @param param Registration parameters for ascs.
1493 : *
1494 : * @return 0 in case of success, negative error code otherwise.
1495 : */
1496 1 : int bt_bap_unicast_server_register(const struct bt_bap_unicast_server_register_param *param);
1497 :
1498 : /**
1499 : * @brief Unregister the Unicast Server.
1500 : *
1501 : * Unregister the Unicast Server.
1502 : * This will unregister ASCS in the GATT database.
1503 : * Before calling this function, any callbacks registered through
1504 : * bt_bap_unicast_server_register_cb() needs to be unregistered with
1505 : * bt_bap_unicast_server_unregister_cb().
1506 : *
1507 : * Calling this function will issue an release operation on any ASE
1508 : * in a non-idle state.
1509 : *
1510 : * @return 0 in case of success, negative error code otherwise.
1511 : */
1512 1 : int bt_bap_unicast_server_unregister(void);
1513 :
1514 : /**
1515 : * @brief Register unicast server callbacks.
1516 : *
1517 : * Only one callback structure can be registered, and attempting to
1518 : * registering more than one will result in an error.
1519 : * Prior to calling this function the Unicast Server needs to be
1520 : * registered with bt_bap_unicast_server_register().
1521 : *
1522 : * @param cb Unicast server callback structure.
1523 : *
1524 : * @return 0 in case of success or negative value in case of error.
1525 : */
1526 1 : int bt_bap_unicast_server_register_cb(const struct bt_bap_unicast_server_cb *cb);
1527 :
1528 : /**
1529 : * @brief Unregister unicast server callbacks.
1530 : *
1531 : * May only unregister a callback structure that has previously been
1532 : * registered by bt_bap_unicast_server_register_cb().
1533 : *
1534 : * Calling this function will issue an release operation on any ASE
1535 : * in a non-idle state.
1536 : *
1537 : * @param cb Unicast server callback structure.
1538 : *
1539 : * @return 0 in case of success or negative value in case of error.
1540 : */
1541 1 : int bt_bap_unicast_server_unregister_cb(const struct bt_bap_unicast_server_cb *cb);
1542 :
1543 : /**
1544 : * @typedef bt_bap_ep_func_t
1545 : * @brief The callback function called for each endpoint.
1546 : *
1547 : * @param ep The structure object with endpoint info.
1548 : * @param user_data Data to pass to the function.
1549 : */
1550 1 : typedef void (*bt_bap_ep_func_t)(struct bt_bap_ep *ep, void *user_data);
1551 :
1552 : /**
1553 : * @brief Iterate through all endpoints of the given connection.
1554 : *
1555 : * @param conn Connection object
1556 : * @param func Function to call for each endpoint.
1557 : * @param user_data Data to pass to the callback function.
1558 : */
1559 1 : void bt_bap_unicast_server_foreach_ep(struct bt_conn *conn, bt_bap_ep_func_t func, void *user_data);
1560 :
1561 : /**
1562 : * @brief Initialize and configure a new ASE.
1563 : *
1564 : * @param conn Connection object
1565 : * @param stream Configured stream object to be attached to the ASE
1566 : * @param codec_cfg Codec configuration
1567 : * @param qos_pref Audio Stream Quality of Service Preference
1568 : *
1569 : * @return 0 in case of success or negative value in case of error.
1570 : */
1571 1 : int bt_bap_unicast_server_config_ase(struct bt_conn *conn, struct bt_bap_stream *stream,
1572 : struct bt_audio_codec_cfg *codec_cfg,
1573 : const struct bt_bap_qos_cfg_pref *qos_pref);
1574 :
1575 : /** @} */ /* End of group bt_bap_unicast_server */
1576 :
1577 : /**
1578 : * @defgroup bt_bap_unicast_client BAP Unicast Client APIs
1579 : * @ingroup bt_bap
1580 : * @{
1581 : */
1582 :
1583 : /** Parameter struct for each stream in the unicast group */
1584 1 : struct bt_bap_unicast_group_stream_param {
1585 : /** Pointer to a stream object. */
1586 1 : struct bt_bap_stream *stream;
1587 :
1588 : /** The QoS settings for the stream object. */
1589 1 : struct bt_bap_qos_cfg *qos;
1590 : };
1591 :
1592 : /**
1593 : * @brief Parameter struct for the unicast group functions
1594 : *
1595 : * Parameter struct for the bt_bap_unicast_group_create() and
1596 : * bt_bap_unicast_group_add_streams() functions.
1597 : */
1598 1 : struct bt_bap_unicast_group_stream_pair_param {
1599 : /** Pointer to a receiving stream parameters. */
1600 1 : struct bt_bap_unicast_group_stream_param *rx_param;
1601 :
1602 : /** Pointer to a transmitting stream parameters. */
1603 1 : struct bt_bap_unicast_group_stream_param *tx_param;
1604 : };
1605 :
1606 : /** Parameters for the creating unicast groups with bt_bap_unicast_group_create() */
1607 1 : struct bt_bap_unicast_group_param {
1608 : /** The number of parameters in @p params */
1609 1 : size_t params_count;
1610 :
1611 : /** Array of stream parameters */
1612 1 : struct bt_bap_unicast_group_stream_pair_param *params;
1613 :
1614 : /**
1615 : * @brief Unicast Group packing mode.
1616 : *
1617 : * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED.
1618 : *
1619 : * @note This is a recommendation to the controller, which the controller may ignore.
1620 : */
1621 1 : uint8_t packing;
1622 :
1623 : #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
1624 : /**
1625 : * @brief Central to Peripheral flush timeout
1626 : *
1627 : * The flush timeout in multiples of ISO_Interval for each payload sent
1628 : * from the Central to Peripheral.
1629 : *
1630 : * Value range from @ref BT_ISO_FT_MIN to @ref BT_ISO_FT_MAX
1631 : */
1632 1 : uint8_t c_to_p_ft;
1633 :
1634 : /**
1635 : * @brief Peripheral to Central flush timeout
1636 : *
1637 : * The flush timeout in multiples of ISO_Interval for each payload sent
1638 : * from the Peripheral to Central.
1639 : *
1640 : * Value range from @ref BT_ISO_FT_MIN to @ref BT_ISO_FT_MAX.
1641 : */
1642 1 : uint8_t p_to_c_ft;
1643 :
1644 : /**
1645 : * @brief ISO interval
1646 : *
1647 : * Time between consecutive CIS anchor points.
1648 : *
1649 : * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX.
1650 : */
1651 1 : uint16_t iso_interval;
1652 : #endif /* CONFIG_BT_ISO_TEST_PARAMS */
1653 : };
1654 :
1655 : /**
1656 : * @brief Create unicast group.
1657 : *
1658 : * Create a new audio unicast group with one or more audio streams as a unicast client.
1659 : * All streams shall share the same framing.
1660 : * All streams in the same direction shall share the same interval and latency (see
1661 : * @ref bt_bap_qos_cfg).
1662 : *
1663 : * @param[in] param The unicast group create parameters.
1664 : * @param[out] unicast_group Pointer to the unicast group created.
1665 : *
1666 : * @return Zero on success or (negative) error code otherwise.
1667 : */
1668 1 : int bt_bap_unicast_group_create(struct bt_bap_unicast_group_param *param,
1669 : struct bt_bap_unicast_group **unicast_group);
1670 :
1671 : /**
1672 : * @brief Reconfigure unicast group.
1673 : *
1674 : * Reconfigure a unicast group with one or more audio streams as a unicast client.
1675 : * All streams shall share the same framing.
1676 : * All streams in the same direction shall share the same interval and latency (see
1677 : * @ref bt_bap_qos_cfg).
1678 : * All streams in @p param shall already belong to @p unicast_group.
1679 : * Use bt_bap_unicast_group_add_streams() to add additional streams.
1680 : *
1681 : * @param unicast_group Pointer to the unicast group created.
1682 : * @param param The unicast group reconfigure parameters.
1683 : *
1684 : * @return Zero on success or (negative) error code otherwise.
1685 : */
1686 1 : int bt_bap_unicast_group_reconfig(struct bt_bap_unicast_group *unicast_group,
1687 : const struct bt_bap_unicast_group_param *param);
1688 :
1689 : /**
1690 : * @brief Add streams to a unicast group as a unicast client
1691 : *
1692 : * This function can be used to add additional streams to a bt_bap_unicast_group.
1693 : *
1694 : * This can be called at any time before any of the streams in the group has been started
1695 : * (see bt_bap_stream_ops.started()).
1696 : * This can also be called after the streams have been stopped (see bt_bap_stream_ops.stopped()).
1697 : *
1698 : * Once a stream has been added to a unicast group, it cannot be removed. To remove a stream from a
1699 : * group, the group must be deleted with bt_bap_unicast_group_delete(), but this will require all
1700 : * streams in the group to be released first.
1701 : *
1702 : * @param unicast_group Pointer to the unicast group
1703 : * @param params Array of stream parameters with streams being added to the group.
1704 : * @param num_param Number of parameters in @p params.
1705 : *
1706 : * @return 0 in case of success or negative value in case of error.
1707 : */
1708 1 : int bt_bap_unicast_group_add_streams(struct bt_bap_unicast_group *unicast_group,
1709 : struct bt_bap_unicast_group_stream_pair_param params[],
1710 : size_t num_param);
1711 :
1712 : /**
1713 : * @brief Delete audio unicast group.
1714 : *
1715 : * Delete a audio unicast group as a client. All streams in the group shall
1716 : * be in the idle or configured state.
1717 : *
1718 : * @param unicast_group Pointer to the unicast group to delete
1719 : *
1720 : * @return Zero on success or (negative) error code otherwise.
1721 : */
1722 1 : int bt_bap_unicast_group_delete(struct bt_bap_unicast_group *unicast_group);
1723 :
1724 : /** Callback function for bt_bap_unicast_group_foreach_stream()
1725 : *
1726 : * @param stream The audio stream
1727 : * @param user_data User data
1728 : *
1729 : * @retval true Stop iterating.
1730 : * @retval false Continue iterating.
1731 : */
1732 1 : typedef bool (*bt_bap_unicast_group_foreach_stream_func_t)(struct bt_bap_stream *stream,
1733 : void *user_data);
1734 :
1735 : /**
1736 : * @brief Iterate through all streams in a unicast group
1737 : *
1738 : * @param unicast_group The unicast group
1739 : * @param func The callback function
1740 : * @param user_data User specified data that sent to the callback function
1741 : *
1742 : * @retval 0 Success (even if no streams exists in the group).
1743 : * @retval -ECANCELED Iteration was stopped by the callback function before complete.
1744 : * @retval -EINVAL @p unicast_group or @p func were NULL.
1745 : */
1746 1 : int bt_bap_unicast_group_foreach_stream(struct bt_bap_unicast_group *unicast_group,
1747 : bt_bap_unicast_group_foreach_stream_func_t func,
1748 : void *user_data);
1749 :
1750 : /** Structure holding information of audio stream endpoint */
1751 1 : struct bt_bap_unicast_group_info {
1752 : /** Presentation delay for sink ASEs
1753 : *
1754 : * Will be @ref BT_BAP_PD_UNSET if no sink ASEs have been QoS configured
1755 : */
1756 1 : uint32_t sink_pd;
1757 :
1758 : /** Presentation delay for source ASEs
1759 : *
1760 : * Will be @ref BT_BAP_PD_UNSET if no source ASEs have been QoS configured
1761 : */
1762 1 : uint32_t source_pd;
1763 : };
1764 :
1765 : /**
1766 : * @brief Return structure holding information of unicast group
1767 : *
1768 : * @param unicast_group The unicast group object.
1769 : * @param info The structure object to be filled with the info.
1770 : *
1771 : * @retval 0 Success
1772 : * @retval -EINVAL @p unicast_group or @p info are NULL
1773 : */
1774 1 : int bt_bap_unicast_group_get_info(const struct bt_bap_unicast_group *unicast_group,
1775 : struct bt_bap_unicast_group_info *info);
1776 :
1777 : /** Unicast Client callback structure */
1778 1 : struct bt_bap_unicast_client_cb {
1779 : /**
1780 : * @brief Remote Unicast Server Audio Locations
1781 : *
1782 : * This callback is called whenever the audio locations is read from
1783 : * the server or otherwise notified to the client.
1784 : *
1785 : * @param conn Connection to the remote unicast server.
1786 : * @param dir Direction of the location.
1787 : * @param loc The location bitfield value.
1788 : *
1789 : * @return 0 in case of success or negative value in case of error.
1790 : */
1791 1 : void (*location)(struct bt_conn *conn, enum bt_audio_dir dir, enum bt_audio_location loc);
1792 :
1793 : /**
1794 : * @brief Remote Unicast Server Available Contexts
1795 : *
1796 : * This callback is called whenever the available contexts are read
1797 : * from the server or otherwise notified to the client.
1798 : *
1799 : * @param conn Connection to the remote unicast server.
1800 : * @param snk_ctx The sink context bitfield value.
1801 : * @param src_ctx The source context bitfield value.
1802 : *
1803 : * @return 0 in case of success or negative value in case of error.
1804 : */
1805 1 : void (*available_contexts)(struct bt_conn *conn, enum bt_audio_context snk_ctx,
1806 : enum bt_audio_context src_ctx);
1807 :
1808 : /**
1809 : * @brief Callback function for bt_bap_stream_config() and bt_bap_stream_reconfig().
1810 : *
1811 : * Called when the codec configure operation is completed on the server.
1812 : *
1813 : * @param stream Stream the operation was performed on.
1814 : * @param rsp_code Response code.
1815 : * @param reason Reason code.
1816 : */
1817 1 : void (*config)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code,
1818 : enum bt_bap_ascs_reason reason);
1819 :
1820 : /**
1821 : * @brief Callback function for bt_bap_stream_qos().
1822 : *
1823 : * Called when the QoS configure operation is completed on the server.
1824 : * This will be called for each stream in the group that was being QoS
1825 : * configured.
1826 : *
1827 : * @param stream Stream the operation was performed on. May be NULL if there is no stream
1828 : * associated with the ASE ID sent by the server.
1829 : * @param rsp_code Response code.
1830 : * @param reason Reason code.
1831 : */
1832 1 : void (*qos)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code,
1833 : enum bt_bap_ascs_reason reason);
1834 :
1835 : /**
1836 : * @brief Callback function for bt_bap_stream_enable().
1837 : *
1838 : * Called when the enable operation is completed on the server.
1839 : *
1840 : * @param stream Stream the operation was performed on. May be NULL if there is no stream
1841 : * associated with the ASE ID sent by the server.
1842 : * @param rsp_code Response code.
1843 : * @param reason Reason code.
1844 : */
1845 1 : void (*enable)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code,
1846 : enum bt_bap_ascs_reason reason);
1847 :
1848 : /**
1849 : * @brief Callback function for bt_bap_stream_start().
1850 : *
1851 : * Called when the start operation is completed on the server. This will
1852 : * only be called if the stream supplied to bt_bap_stream_start() is
1853 : * for a @ref BT_AUDIO_DIR_SOURCE endpoint.
1854 : *
1855 : * @param stream Stream the operation was performed on. May be NULL if there is no stream
1856 : * associated with the ASE ID sent by the server.
1857 : * @param rsp_code Response code.
1858 : * @param reason Reason code.
1859 : */
1860 1 : void (*start)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code,
1861 : enum bt_bap_ascs_reason reason);
1862 :
1863 : /**
1864 : * @brief Callback function for bt_bap_stream_stop().
1865 : *
1866 : * Called when the stop operation is completed on the server. This will
1867 : * only be called if the stream supplied to bt_bap_stream_stop() is
1868 : * for a @ref BT_AUDIO_DIR_SOURCE endpoint.
1869 : *
1870 : * @param stream Stream the operation was performed on. May be NULL if there is no stream
1871 : * associated with the ASE ID sent by the server.
1872 : * @param rsp_code Response code.
1873 : * @param reason Reason code.
1874 : */
1875 1 : void (*stop)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code,
1876 : enum bt_bap_ascs_reason reason);
1877 :
1878 : /**
1879 : * @brief Callback function for bt_bap_stream_disable().
1880 : *
1881 : * Called when the disable operation is completed on the server.
1882 : *
1883 : * @param stream Stream the operation was performed on. May be NULL if there is no stream
1884 : * associated with the ASE ID sent by the server.
1885 : * @param rsp_code Response code.
1886 : * @param reason Reason code.
1887 : */
1888 1 : void (*disable)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code,
1889 : enum bt_bap_ascs_reason reason);
1890 :
1891 : /**
1892 : * @brief Callback function for bt_bap_stream_metadata().
1893 : *
1894 : * Called when the metadata operation is completed on the server.
1895 : *
1896 : * @param stream Stream the operation was performed on. May be NULL if there is no stream
1897 : * associated with the ASE ID sent by the server.
1898 : * @param rsp_code Response code.
1899 : * @param reason Reason code.
1900 : */
1901 1 : void (*metadata)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code,
1902 : enum bt_bap_ascs_reason reason);
1903 :
1904 : /**
1905 : * @brief Callback function for bt_bap_stream_release().
1906 : *
1907 : * Called when the release operation is completed on the server.
1908 : *
1909 : * @param stream Stream the operation was performed on. May be NULL if there is no stream
1910 : * associated with the ASE ID sent by the server.
1911 : * @param rsp_code Response code.
1912 : * @param reason Reason code.
1913 : */
1914 1 : void (*release)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code,
1915 : enum bt_bap_ascs_reason reason);
1916 :
1917 : /**
1918 : * @brief Remote Published Audio Capability (PAC) record discovered
1919 : *
1920 : * Called when a PAC record has been discovered as part of the discovery procedure.
1921 : *
1922 : * The @p codec is only valid while in the callback, so the values must be stored by the
1923 : * receiver if future use is wanted.
1924 : *
1925 : * @param conn Connection to the remote unicast server.
1926 : * @param dir The type of remote endpoints and capabilities discovered.
1927 : * @param codec_cap Remote capabilities.
1928 : *
1929 : * If discovery procedure has complete both @p codec and @p ep are set to NULL.
1930 : */
1931 1 : void (*pac_record)(struct bt_conn *conn, enum bt_audio_dir dir,
1932 : const struct bt_audio_codec_cap *codec_cap);
1933 :
1934 : /**
1935 : * @brief Remote Audio Stream Endpoint (ASE) discovered
1936 : *
1937 : * Called when an ASE has been discovered as part of the discovery procedure.
1938 : *
1939 : * @param conn Connection to the remote unicast server.
1940 : * @param dir The type of remote endpoints and capabilities discovered.
1941 : * @param ep Remote endpoint.
1942 : *
1943 : * If discovery procedure has complete both @p codec and @p ep are set to NULL.
1944 : */
1945 1 : void (*endpoint)(struct bt_conn *conn, enum bt_audio_dir dir, struct bt_bap_ep *ep);
1946 :
1947 : /**
1948 : * @brief BAP discovery callback function.
1949 : *
1950 : * If discovery procedure has completed @p ep is set to NULL and @p err is 0.
1951 : *
1952 : * @param conn Connection to the remote unicast server.
1953 : * @param err Error value. 0 on success, GATT error on positive value or errno on
1954 : * negative value.
1955 : * @param dir The type of remote endpoints and capabilities discovered.
1956 : *
1957 : * If discovery procedure has complete both @p codec and @p ep are set to NULL.
1958 : */
1959 1 : void (*discover)(struct bt_conn *conn, int err, enum bt_audio_dir dir);
1960 :
1961 : /** @cond INTERNAL_HIDDEN */
1962 : /** Internally used field for list handling */
1963 : sys_snode_t _node;
1964 : /** @endcond */
1965 : };
1966 :
1967 : /**
1968 : * @brief Register unicast client callbacks.
1969 : *
1970 : * Only one callback structure can be registered, and attempting to
1971 : * registering more than one will result in an error.
1972 : *
1973 : * @param cb Unicast client callback structure.
1974 : *
1975 : * @retval 0 Success
1976 : * @retval -EINVAL @p cb is NULL.
1977 : * @retval -EEXIST @p cb is already registered.
1978 : */
1979 1 : int bt_bap_unicast_client_register_cb(struct bt_bap_unicast_client_cb *cb);
1980 :
1981 : /**
1982 : * @brief Discover remote capabilities and endpoints
1983 : *
1984 : * This procedure is used by a client to discover remote capabilities and
1985 : * endpoints and notifies via params callback.
1986 : *
1987 : * @param conn Connection object
1988 : * @param dir The type of remote endpoints and capabilities to discover.
1989 : */
1990 1 : int bt_bap_unicast_client_discover(struct bt_conn *conn, enum bt_audio_dir dir);
1991 :
1992 : /** @} */ /* End of group bt_bap_unicast_client */
1993 : /**
1994 : * @brief BAP Broadcast APIs
1995 : * @defgroup bt_bap_broadcast BAP Broadcast APIs
1996 : * @ingroup bt_bap
1997 : * @{
1998 : */
1999 :
2000 : /** @brief Abstract Broadcast Audio Source Endpoint (BASE) subgroup structure. */
2001 : struct bt_bap_base_subgroup;
2002 : /** @brief Abstract Broadcast Audio Source Endpoint (BASE) structure. */
2003 : struct bt_bap_base;
2004 :
2005 : /** Codec ID structure for a Broadcast Audio Source Endpoint (BASE) */
2006 1 : struct bt_bap_base_codec_id {
2007 : /** Codec ID */
2008 1 : uint8_t id;
2009 : /** Codec Company ID */
2010 1 : uint16_t cid;
2011 : /** Codec Company Vendor ID */
2012 1 : uint16_t vid;
2013 : };
2014 :
2015 : /** BIS structure for each BIS in a Broadcast Audio Source Endpoint (BASE) subgroup */
2016 1 : struct bt_bap_base_subgroup_bis {
2017 : /** Unique index of the BIS */
2018 1 : uint8_t index;
2019 : /** Codec Specific Data length. */
2020 1 : uint8_t data_len;
2021 : /** Codec Specific Data */
2022 1 : uint8_t *data;
2023 : };
2024 :
2025 : /**
2026 : * @brief Generate a pointer to a BASE from periodic advertising data
2027 : *
2028 : * @param ad The periodic advertising data
2029 : *
2030 : * @retval NULL if the data does not contain a BASE
2031 : * @retval Pointer to a bt_bap_base structure
2032 : */
2033 1 : const struct bt_bap_base *bt_bap_base_get_base_from_ad(const struct bt_data *ad);
2034 :
2035 : /**
2036 : * @brief Get the size of a BASE
2037 : *
2038 : * @param base The BASE pointer
2039 : *
2040 : * @retval -EINVAL if arguments are invalid
2041 : * @retval The size of the BASE
2042 : */
2043 1 : int bt_bap_base_get_size(const struct bt_bap_base *base);
2044 :
2045 : /**
2046 : * @brief Get the presentation delay value of a BASE
2047 : *
2048 : * @param base The BASE pointer
2049 : *
2050 : * @retval -EINVAL if arguments are invalid
2051 : * @retval The 24-bit presentation delay value
2052 : */
2053 1 : int bt_bap_base_get_pres_delay(const struct bt_bap_base *base);
2054 :
2055 : /**
2056 : * @brief Get the subgroup count of a BASE
2057 : *
2058 : * @param base The BASE pointer
2059 : *
2060 : * @retval -EINVAL if arguments are invalid
2061 : * @retval The 8-bit subgroup count value
2062 : */
2063 1 : int bt_bap_base_get_subgroup_count(const struct bt_bap_base *base);
2064 :
2065 : /**
2066 : * @brief Get all BIS indexes of a BASE
2067 : *
2068 : * @param[in] base The BASE pointer
2069 : * @param[out] bis_indexes 32-bit BIS index bitfield that will be populated
2070 : *
2071 : * @retval -EINVAL if arguments are invalid
2072 : * @retval 0 on success
2073 : */
2074 1 : int bt_bap_base_get_bis_indexes(const struct bt_bap_base *base, uint32_t *bis_indexes);
2075 :
2076 : /**
2077 : * @brief Iterate on all subgroups in the BASE
2078 : *
2079 : * @param base The BASE pointer
2080 : * @param func Callback function. Return true to continue iterating, or false to stop.
2081 : * @param user_data Userdata supplied to @p func
2082 : *
2083 : * @retval -EINVAL if arguments are invalid
2084 : * @retval -ECANCELED if iterating over the subgroups stopped prematurely by @p func
2085 : * @retval 0 if all subgroups were iterated
2086 : */
2087 1 : int bt_bap_base_foreach_subgroup(const struct bt_bap_base *base,
2088 : bool (*func)(const struct bt_bap_base_subgroup *subgroup,
2089 : void *user_data),
2090 : void *user_data);
2091 :
2092 : /**
2093 : * @brief Get the codec ID of a subgroup
2094 : *
2095 : * @param[in] subgroup The subgroup pointer
2096 : * @param[out] codec_id Pointer to the struct where the results are placed
2097 : *
2098 : * @retval -EINVAL if arguments are invalid
2099 : * @retval 0 on success
2100 : */
2101 1 : int bt_bap_base_get_subgroup_codec_id(const struct bt_bap_base_subgroup *subgroup,
2102 : struct bt_bap_base_codec_id *codec_id);
2103 :
2104 : /**
2105 : * @brief Get the codec configuration data of a subgroup
2106 : *
2107 : * @param[in] subgroup The subgroup pointer
2108 : * @param[out] data Pointer that will point to the resulting codec configuration data
2109 : *
2110 : * @retval -EINVAL if arguments are invalid
2111 : * @retval 0 on success
2112 : */
2113 1 : int bt_bap_base_get_subgroup_codec_data(const struct bt_bap_base_subgroup *subgroup,
2114 : uint8_t **data);
2115 :
2116 : /**
2117 : * @brief Get the codec metadata of a subgroup
2118 : *
2119 : * @param[in] subgroup The subgroup pointer
2120 : * @param[out] meta Pointer that will point to the resulting codec metadata
2121 : *
2122 : * @retval -EINVAL if arguments are invalid
2123 : * @retval 0 on success
2124 : */
2125 1 : int bt_bap_base_get_subgroup_codec_meta(const struct bt_bap_base_subgroup *subgroup,
2126 : uint8_t **meta);
2127 :
2128 : /**
2129 : * @brief Store subgroup codec data in a @ref bt_audio_codec_cfg
2130 : *
2131 : * @param[in] subgroup The subgroup pointer
2132 : * @param[out] codec_cfg Pointer to the struct where the results are placed
2133 : *
2134 : * @retval -EINVAL if arguments are invalid
2135 : * @retval -ENOMEM if the @p codec_cfg cannot store the @p subgroup codec data
2136 : * @retval 0 on success
2137 : */
2138 1 : int bt_bap_base_subgroup_codec_to_codec_cfg(const struct bt_bap_base_subgroup *subgroup,
2139 : struct bt_audio_codec_cfg *codec_cfg);
2140 :
2141 : /**
2142 : * @brief Get the BIS count of a subgroup
2143 : *
2144 : * @param subgroup The subgroup pointer
2145 : *
2146 : * @retval -EINVAL if arguments are invalid
2147 : * @retval The 8-bit BIS count value
2148 : */
2149 1 : int bt_bap_base_get_subgroup_bis_count(const struct bt_bap_base_subgroup *subgroup);
2150 :
2151 : /**
2152 : * @brief Get all BIS indexes of a subgroup
2153 : *
2154 : * @param[in] subgroup The subgroup pointer
2155 : * @param[out] bis_indexes 32-bit BIS index bitfield that will be populated
2156 : *
2157 : * @retval -EINVAL if arguments are invalid
2158 : * @retval 0 on success
2159 : */
2160 1 : int bt_bap_base_subgroup_get_bis_indexes(const struct bt_bap_base_subgroup *subgroup,
2161 : uint32_t *bis_indexes);
2162 :
2163 : /**
2164 : * @brief Iterate on all BIS in the subgroup
2165 : *
2166 : * @param subgroup The subgroup pointer
2167 : * @param func Callback function. Return true to continue iterating, or false to stop.
2168 : * @param user_data Userdata supplied to @p func
2169 : *
2170 : * @retval -EINVAL if arguments are invalid
2171 : * @retval -ECANCELED if iterating over the subgroups stopped prematurely by @p func
2172 : * @retval 0 if all BIS were iterated
2173 : */
2174 1 : int bt_bap_base_subgroup_foreach_bis(const struct bt_bap_base_subgroup *subgroup,
2175 : bool (*func)(const struct bt_bap_base_subgroup_bis *bis,
2176 : void *user_data),
2177 : void *user_data);
2178 :
2179 : /**
2180 : * @brief Store BIS codec configuration data in a @ref bt_audio_codec_cfg
2181 : *
2182 : * This only sets the @ref bt_audio_codec_cfg data and @ref bt_audio_codec_cfg data_len, but is
2183 : * useful to use the BIS codec configuration data with the bt_audio_codec_cfg_* functions.
2184 : *
2185 : * @param[in] bis The BIS pointer
2186 : * @param[out] codec_cfg Pointer to the struct where the results are placed
2187 : *
2188 : * @retval -EINVAL if arguments are invalid
2189 : * @retval -ENOMEM if the @p codec_cfg cannot store the @p subgroup codec data
2190 : * @retval 0 on success
2191 : */
2192 1 : int bt_bap_base_subgroup_bis_codec_to_codec_cfg(const struct bt_bap_base_subgroup_bis *bis,
2193 : struct bt_audio_codec_cfg *codec_cfg);
2194 :
2195 : /** @} */ /* End of group bt_bap_broadcast */
2196 :
2197 : /**
2198 : * @brief BAP Broadcast Source APIs
2199 : * @defgroup bt_bap_broadcast_source BAP Broadcast Source APIs
2200 : * @ingroup bt_bap_broadcast
2201 : * @{
2202 : */
2203 :
2204 : /**
2205 : * @brief Struct to hold the Broadcast Source callbacks
2206 : *
2207 : * These can be registered for usage with bt_bap_broadcast_source_register_cb().
2208 : */
2209 1 : struct bt_bap_broadcast_source_cb {
2210 : /**
2211 : * @brief The Broadcast Source has started and all of the streams are ready for audio data
2212 : *
2213 : * @param source The started Broadcast Source
2214 : */
2215 1 : void (*started)(struct bt_bap_broadcast_source *source);
2216 :
2217 : /**
2218 : * @brief The Broadcast Source has stopped and none of the streams are ready for audio data
2219 : *
2220 : * @param source The stopped Broadcast Source
2221 : * @param reason The reason why the Broadcast Source stopped (see the BT_HCI_ERR_* values)
2222 : */
2223 1 : void (*stopped)(struct bt_bap_broadcast_source *source, uint8_t reason);
2224 :
2225 : /** @cond INTERNAL_HIDDEN */
2226 : /** Internally used field for list handling */
2227 : sys_snode_t _node;
2228 : /** @endcond */
2229 : };
2230 :
2231 : /**
2232 : * @brief Registers callbacks for Broadcast Sources
2233 : *
2234 : * @param cb Pointer to the callback structure.
2235 : *
2236 : * @retval 0 on success
2237 : * @retval -EINVAL if @p cb is NULL
2238 : * @retval -EEXIST if @p cb is already registered
2239 : */
2240 1 : int bt_bap_broadcast_source_register_cb(struct bt_bap_broadcast_source_cb *cb);
2241 :
2242 : /**
2243 : * @brief Unregisters callbacks for Broadcast Sources
2244 : *
2245 : * @param cb Pointer to the callback structure.
2246 : *
2247 : * @retval 0 on success
2248 : * @retval -EINVAL if @p cb is NULL
2249 : * @retval -ENOENT if @p cb is not registered
2250 : */
2251 1 : int bt_bap_broadcast_source_unregister_cb(struct bt_bap_broadcast_source_cb *cb);
2252 :
2253 : /** Broadcast Source stream parameters */
2254 1 : struct bt_bap_broadcast_source_stream_param {
2255 : /** Audio stream */
2256 1 : struct bt_bap_stream *stream;
2257 :
2258 : #if CONFIG_BT_AUDIO_CODEC_CFG_MAX_DATA_SIZE > 0 || defined(__DOXYGEN__)
2259 : /**
2260 : * @brief The number of elements in the @p data array.
2261 : *
2262 : * The BIS specific data may be omitted and this set to 0.
2263 : */
2264 1 : size_t data_len;
2265 :
2266 : /** BIS Codec Specific Configuration */
2267 1 : uint8_t *data;
2268 : #endif /* CONFIG_BT_AUDIO_CODEC_CFG_MAX_DATA_SIZE > 0 */
2269 : };
2270 :
2271 : /** Broadcast Source subgroup parameters*/
2272 1 : struct bt_bap_broadcast_source_subgroup_param {
2273 : /** The number of parameters in @p stream_params */
2274 1 : size_t params_count;
2275 :
2276 : /** Array of stream parameters */
2277 1 : struct bt_bap_broadcast_source_stream_param *params;
2278 :
2279 : /** Subgroup Codec configuration. */
2280 1 : struct bt_audio_codec_cfg *codec_cfg;
2281 : };
2282 :
2283 : /** Broadcast Source create parameters */
2284 1 : struct bt_bap_broadcast_source_param {
2285 : /** The number of parameters in @p subgroup_params */
2286 1 : size_t params_count;
2287 :
2288 : /** Array of stream parameters */
2289 1 : struct bt_bap_broadcast_source_subgroup_param *params;
2290 :
2291 : /** Quality of Service configuration. */
2292 1 : struct bt_bap_qos_cfg *qos;
2293 :
2294 : /**
2295 : * @brief Broadcast Source packing mode.
2296 : *
2297 : * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED.
2298 : *
2299 : * @note This is a recommendation to the controller, which the controller may ignore.
2300 : */
2301 1 : uint8_t packing;
2302 :
2303 : /** Whether or not to encrypt the streams. */
2304 1 : bool encryption;
2305 :
2306 : /**
2307 : * @brief Broadcast code
2308 : *
2309 : * If the value is a string or a the value is less than 16 octets,
2310 : * the remaining octets shall be 0.
2311 : *
2312 : * Example:
2313 : * The string "Broadcast Code" shall be
2314 : * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
2315 : */
2316 1 : uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE];
2317 :
2318 : #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
2319 : /**
2320 : * @brief Immediate Repetition Count
2321 : *
2322 : * The number of times the scheduled payloads are transmitted in a given event.
2323 : *
2324 : * Value range from @ref BT_ISO_IRC_MIN to @ref BT_ISO_IRC_MAX.
2325 : */
2326 1 : uint8_t irc;
2327 :
2328 : /**
2329 : * @brief Pre-transmission offset
2330 : *
2331 : * Offset used for pre-transmissions.
2332 : *
2333 : * Value range from @ref BT_ISO_PTO_MIN to @ref BT_ISO_PTO_MAX.
2334 : */
2335 1 : uint8_t pto;
2336 :
2337 : /**
2338 : * @brief ISO interval
2339 : *
2340 : * Time between consecutive BIS anchor points.
2341 : *
2342 : * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX.
2343 : */
2344 1 : uint16_t iso_interval;
2345 : #endif /* CONFIG_BT_ISO_TEST_PARAMS */
2346 : };
2347 :
2348 : /**
2349 : * @brief Create audio broadcast source.
2350 : *
2351 : * Create a new audio broadcast source with one or more audio streams.
2352 : *
2353 : * The broadcast source will be visible for scanners once this has been called,
2354 : * and the device will advertise audio announcements.
2355 : *
2356 : * No audio data can be sent until bt_bap_broadcast_source_start() has been called and no audio
2357 : * information (BIGInfo) will be visible to scanners (see @ref bt_le_per_adv_sync_cb).
2358 : *
2359 : * @param[in] param Pointer to parameters used to create the broadcast source.
2360 : * @param[out] source Pointer to the broadcast source created
2361 : *
2362 : * @return Zero on success or (negative) error code otherwise.
2363 : */
2364 1 : int bt_bap_broadcast_source_create(struct bt_bap_broadcast_source_param *param,
2365 : struct bt_bap_broadcast_source **source);
2366 :
2367 : /**
2368 : * @brief Reconfigure audio broadcast source.
2369 : *
2370 : * Reconfigure an audio broadcast source with a new codec and codec quality of
2371 : * service parameters. This can only be done when the source is stopped.
2372 : *
2373 : * Since this may modify the Broadcast Audio Source Endpoint (BASE),
2374 : * bt_bap_broadcast_source_get_base() should be called after this to get the new BASE information.
2375 : *
2376 : * If the @p param.params_count is smaller than the number of subgroups that have been created in
2377 : * the Broadcast Source, only the first @p param.params_count subgroups are updated. If a stream
2378 : * exist in a subgroup not part of @p param, then that stream is left as is (i.e. it is not removed;
2379 : * the only way to remove a stream from a Broadcast Source is to recreate the Broadcast Source).
2380 : *
2381 : * @param source Pointer to the broadcast source
2382 : * @param param Pointer to parameters used to reconfigure the broadcast source.
2383 : *
2384 : * @return Zero on success or (negative) error code otherwise.
2385 : */
2386 1 : int bt_bap_broadcast_source_reconfig(struct bt_bap_broadcast_source *source,
2387 : struct bt_bap_broadcast_source_param *param);
2388 :
2389 : /**
2390 : * @brief Modify the metadata of an audio broadcast source.
2391 : *
2392 : * Modify the metadata an audio broadcast source. This can only be done when the source is started.
2393 : * To update the metadata in the stopped state, use bt_bap_broadcast_source_reconfig().
2394 : *
2395 : * @param source Pointer to the broadcast source.
2396 : * @param meta Metadata.
2397 : * @param meta_len Length of metadata.
2398 : *
2399 : * @return Zero on success or (negative) error code otherwise.
2400 : */
2401 1 : int bt_bap_broadcast_source_update_metadata(struct bt_bap_broadcast_source *source,
2402 : const uint8_t meta[], size_t meta_len);
2403 :
2404 : /**
2405 : * @brief Start audio broadcast source.
2406 : *
2407 : * Start an audio broadcast source with one or more audio streams.
2408 : * The broadcast source will start advertising BIGInfo, and audio data can be streamed.
2409 : *
2410 : * @param source Pointer to the broadcast source
2411 : * @param adv Pointer to an extended advertising set with periodic advertising configured.
2412 : *
2413 : * @return Zero on success or (negative) error code otherwise.
2414 : */
2415 1 : int bt_bap_broadcast_source_start(struct bt_bap_broadcast_source *source,
2416 : struct bt_le_ext_adv *adv);
2417 :
2418 : /**
2419 : * @brief Stop audio broadcast source.
2420 : *
2421 : * Stop an audio broadcast source.
2422 : * The broadcast source will stop advertising BIGInfo, and audio data can no longer be streamed.
2423 : *
2424 : * @param source Pointer to the broadcast source
2425 : *
2426 : * @return Zero on success or (negative) error code otherwise.
2427 : */
2428 1 : int bt_bap_broadcast_source_stop(struct bt_bap_broadcast_source *source);
2429 :
2430 : /**
2431 : * @brief Delete audio broadcast source.
2432 : *
2433 : * Delete an audio broadcast source.
2434 : * The broadcast source will stop advertising entirely, and the source can no longer be used.
2435 : *
2436 : * @param source Pointer to the broadcast source
2437 : *
2438 : * @return Zero on success or (negative) error code otherwise.
2439 : */
2440 1 : int bt_bap_broadcast_source_delete(struct bt_bap_broadcast_source *source);
2441 :
2442 : /**
2443 : * @brief Get the Broadcast Audio Stream Endpoint of a broadcast source
2444 : *
2445 : * This will encode the BASE of a broadcast source into a buffer, that can be used for
2446 : * advertisement. The encoded BASE will thus be encoded as little-endian. The BASE shall be put into
2447 : * the periodic advertising data (see bt_le_per_adv_set_data()).
2448 : *
2449 : * See table 3.15 in the Basic Audio Profile v1.0.1 for the structure.
2450 : *
2451 : * @param source Pointer to the broadcast source.
2452 : * @param base_buf Pointer to a buffer where the BASE will be inserted.
2453 : *
2454 : * @return Zero on success or (negative) error code otherwise.
2455 : */
2456 1 : int bt_bap_broadcast_source_get_base(struct bt_bap_broadcast_source *source,
2457 : struct net_buf_simple *base_buf);
2458 :
2459 : /**
2460 : * @brief Callback function for bt_bap_broadcast_source_foreach_stream()
2461 : *
2462 : * @param stream The audio stream
2463 : * @param user_data User data
2464 : *
2465 : * @retval true Stop iterating.
2466 : * @retval false Continue iterating.
2467 : */
2468 1 : typedef bool (*bt_bap_broadcast_source_foreach_stream_func_t)(struct bt_bap_stream *stream,
2469 : void *user_data);
2470 :
2471 : /**
2472 : * @brief Iterate through all streams in a broadcast source
2473 : *
2474 : * @param source The broadcast source
2475 : * @param func The callback function
2476 : * @param user_data User specified data that is sent to the callback function
2477 : *
2478 : * @retval 0 Success (even if no streams exists in the broadcast source).
2479 : * @retval -ECANCELED The @p func returned true.
2480 : * @retval -EINVAL @p source or @p func were NULL.
2481 : */
2482 1 : int bt_bap_broadcast_source_foreach_stream(struct bt_bap_broadcast_source *source,
2483 : bt_bap_broadcast_source_foreach_stream_func_t func,
2484 : void *user_data);
2485 : /** @} */ /* End of bt_bap_broadcast_source */
2486 :
2487 : /**
2488 : * @brief BAP Broadcast Sink APIs
2489 : * @defgroup bt_bap_broadcast_sink BAP Broadcast Sink APIs
2490 : * @ingroup bt_bap_broadcast
2491 : * @{
2492 : */
2493 :
2494 : /** Broadcast Audio Sink callback structure */
2495 1 : struct bt_bap_broadcast_sink_cb {
2496 : /**
2497 : * @brief Broadcast Audio Source Endpoint (BASE) received
2498 : *
2499 : * Callback for when we receive a BASE from a broadcaster after
2500 : * syncing to the broadcaster's periodic advertising.
2501 : *
2502 : * @param sink Pointer to the sink structure.
2503 : * @param base Broadcast Audio Source Endpoint (BASE).
2504 : * @param base_size Size of the @p base
2505 : */
2506 1 : void (*base_recv)(struct bt_bap_broadcast_sink *sink, const struct bt_bap_base *base,
2507 : size_t base_size);
2508 :
2509 : /**
2510 : * @brief Broadcast sink is syncable
2511 : *
2512 : * Called whenever a broadcast sink is not synchronized to audio, but the audio is
2513 : * synchronizable. This is inferred when a BIGInfo report is received.
2514 : *
2515 : * Once this callback has been called, it is possible to call
2516 : * bt_bap_broadcast_sink_sync() to synchronize to the audio stream(s).
2517 : *
2518 : * @param sink Pointer to the sink structure.
2519 : * @param biginfo The BIGInfo report.
2520 : */
2521 1 : void (*syncable)(struct bt_bap_broadcast_sink *sink, const struct bt_iso_biginfo *biginfo);
2522 :
2523 : /**
2524 : * @brief The Broadcast Sink has started and audio data may be received from all of the
2525 : * streams
2526 : *
2527 : * @param sink The started Broadcast Sink
2528 : */
2529 1 : void (*started)(struct bt_bap_broadcast_sink *sink);
2530 :
2531 : /**
2532 : * @brief The Broadcast Sink has stopped and none of the streams will receive audio data
2533 : *
2534 : * @param sink The stopped Broadcast Sink
2535 : * @param reason The reason why the Broadcast Sink stopped (see the BT_HCI_ERR_* values)
2536 : */
2537 1 : void (*stopped)(struct bt_bap_broadcast_sink *sink, uint8_t reason);
2538 :
2539 : /** @cond INTERNAL_HIDDEN */
2540 : /** Internally used list node */
2541 : sys_snode_t _node;
2542 : /** @endcond */
2543 : };
2544 :
2545 : /**
2546 : * @brief Register Broadcast sink callbacks
2547 : *
2548 : * It is possible to register multiple struct of callbacks, but a single struct can only be
2549 : * registered once.
2550 : * Registering the same callback multiple times is undefined behavior and may break the stack.
2551 :
2552 : * @param cb Broadcast sink callback structure.
2553 : *
2554 : * @retval 0 on success
2555 : * @retval -EINVAL if @p cb is NULL
2556 : * @retval -EALREADY if @p cb was already registered
2557 : */
2558 1 : int bt_bap_broadcast_sink_register_cb(struct bt_bap_broadcast_sink_cb *cb);
2559 :
2560 : /**
2561 : * @brief Create a Broadcast Sink from a periodic advertising sync
2562 : *
2563 : * This should only be done after verifying that the periodic advertising sync
2564 : * is from a Broadcast Source.
2565 : *
2566 : * The created Broadcast Sink will need to be supplied to
2567 : * bt_bap_broadcast_sink_sync() in order to synchronize to the broadcast audio.
2568 : *
2569 : * bt_bap_broadcast_sink_cb.pa_synced() will be called with the Broadcast
2570 : * Sink object created if this is successful.
2571 : *
2572 : * @param pa_sync Pointer to the periodic advertising sync object.
2573 : * @param broadcast_id 24-bit broadcast ID.
2574 : * @param[out] sink Pointer to the Broadcast Sink created.
2575 : *
2576 : * @return 0 in case of success or errno value in case of error.
2577 : */
2578 1 : int bt_bap_broadcast_sink_create(struct bt_le_per_adv_sync *pa_sync, uint32_t broadcast_id,
2579 : struct bt_bap_broadcast_sink **sink);
2580 :
2581 : /**
2582 : * @brief Sync to a broadcaster's audio
2583 : *
2584 : * @param sink Pointer to the sink object from the base_recv callback.
2585 : * @param indexes_bitfield Bitfield of the BIS index to sync to. To sync to e.g. BIS index 1 and
2586 : * 2, this should have the value of BIT(1) | BIT(2).
2587 : * @param streams Stream object pointers to be used for the receiver. If multiple BIS
2588 : * indexes shall be synchronized, multiple streams shall be provided.
2589 : * @param broadcast_code The 16-octet broadcast code. Shall be supplied if the broadcast is
2590 : * encrypted (see @ref bt_bap_broadcast_sink_cb.syncable).
2591 : * If the value is a string or a the value is less
2592 : * than 16 octets, the remaining octets shall be 0.
2593 : *
2594 : * Example:
2595 : * The string "Broadcast Code" shall be
2596 : * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
2597 : *
2598 : * @return 0 in case of success or negative value in case of error.
2599 : */
2600 1 : int bt_bap_broadcast_sink_sync(struct bt_bap_broadcast_sink *sink, uint32_t indexes_bitfield,
2601 : struct bt_bap_stream *streams[],
2602 : const uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]);
2603 :
2604 : /**
2605 : * @brief Stop audio broadcast sink.
2606 : *
2607 : * Stop an audio broadcast sink.
2608 : * The broadcast sink will stop receiving BIGInfo, and audio data can no longer be streamed.
2609 : *
2610 : * @param sink Pointer to the broadcast sink
2611 : *
2612 : * @return Zero on success or (negative) error code otherwise.
2613 : */
2614 1 : int bt_bap_broadcast_sink_stop(struct bt_bap_broadcast_sink *sink);
2615 :
2616 : /**
2617 : * @brief Release a broadcast sink
2618 : *
2619 : * Once a broadcast sink has been allocated after the pa_synced callback, it can be deleted using
2620 : * this function. If the sink has synchronized to any broadcast audio streams, these must first be
2621 : * stopped using bt_bap_stream_stop.
2622 : *
2623 : * @param sink Pointer to the sink object to delete.
2624 : *
2625 : * @return 0 in case of success or negative value in case of error.
2626 : */
2627 1 : int bt_bap_broadcast_sink_delete(struct bt_bap_broadcast_sink *sink);
2628 :
2629 : /** @} */ /* End of group bt_bap_broadcast_sink */
2630 :
2631 : /**
2632 : * @brief Register the Basic Audio Profile Scan Delegator and BASS.
2633 : *
2634 : * Register the scan deligator and Broadcast Audio Scan Service (BASS)
2635 : * dynamically at runtime.
2636 : *
2637 : * Only one set of callbacks can be registered at any one time, and calling this function multiple
2638 : * times will override any previously registered callbacks.
2639 : *
2640 : * @param cb Pointer to the callback struct
2641 : *
2642 : * @return 0 in case of success or negative value in case of error.
2643 : */
2644 1 : int bt_bap_scan_delegator_register(struct bt_bap_scan_delegator_cb *cb);
2645 :
2646 : /**
2647 : * @brief unregister the Basic Audio Profile Scan Delegator and BASS.
2648 : *
2649 : * Unregister the scan deligator and Broadcast Audio Scan Service (BASS)
2650 : * dynamically at runtime.
2651 : *
2652 : * @return 0 in case of success or negative value in case of error.
2653 : */
2654 1 : int bt_bap_scan_delegator_unregister(void);
2655 :
2656 : /**
2657 : * @brief Set the periodic advertising sync state to syncing
2658 : *
2659 : * Set the periodic advertising sync state for a receive state to syncing,
2660 : * notifying Broadcast Assistants.
2661 : *
2662 : * @param src_id The source id used to identify the receive state.
2663 : * @param pa_state The Periodic Advertising sync state to set.
2664 : * BT_BAP_PA_STATE_NOT_SYNCED and BT_BAP_PA_STATE_SYNCED is
2665 : * not necessary to provide, as they are handled internally.
2666 : *
2667 : * @return int Error value. 0 on success, errno on fail.
2668 : */
2669 1 : int bt_bap_scan_delegator_set_pa_state(uint8_t src_id,
2670 : enum bt_bap_pa_state pa_state);
2671 :
2672 : /**
2673 : * @brief Set the sync state of a receive state in the server
2674 : *
2675 : * @param src_id The source id used to identify the receive state.
2676 : * @param bis_synced Array of bitfields to set the BIS sync state for each
2677 : * subgroup.
2678 : * @return int Error value. 0 on success, ERRNO on fail.
2679 : */
2680 1 : int bt_bap_scan_delegator_set_bis_sync_state(uint8_t src_id,
2681 : uint32_t bis_synced[BT_BAP_BASS_MAX_SUBGROUPS]);
2682 :
2683 : /** Parameters for bt_bap_scan_delegator_add_src() */
2684 1 : struct bt_bap_scan_delegator_add_src_param {
2685 : /** Periodic Advertiser Address */
2686 1 : bt_addr_le_t addr;
2687 :
2688 : /** Advertiser SID */
2689 1 : uint8_t sid;
2690 :
2691 : /** The broadcast isochronous group encryption state */
2692 1 : enum bt_bap_big_enc_state encrypt_state;
2693 :
2694 : /** The 24-bit broadcast ID */
2695 1 : uint32_t broadcast_id;
2696 :
2697 : /** Number of subgroups */
2698 1 : uint8_t num_subgroups;
2699 :
2700 : /** Subgroup specific information */
2701 1 : struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS];
2702 : };
2703 :
2704 : /**
2705 : * @brief Add a receive state source locally
2706 : *
2707 : * This will notify any connected clients about the new source. This allows them
2708 : * to modify and even remove it.
2709 : *
2710 : * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink
2711 : * sources are autonomously added.
2712 : *
2713 : * @param param The parameters for adding the new source
2714 : *
2715 : * @return int errno on failure, or source ID on success.
2716 : */
2717 1 : int bt_bap_scan_delegator_add_src(const struct bt_bap_scan_delegator_add_src_param *param);
2718 :
2719 : /** Parameters for bt_bap_scan_delegator_mod_src() */
2720 1 : struct bt_bap_scan_delegator_mod_src_param {
2721 : /** The periodic adverting sync */
2722 1 : uint8_t src_id;
2723 :
2724 : /** The broadcast isochronous group encryption state */
2725 1 : enum bt_bap_big_enc_state encrypt_state;
2726 :
2727 : /** The 24-bit broadcast ID */
2728 1 : uint32_t broadcast_id;
2729 :
2730 : /** Number of subgroups */
2731 1 : uint8_t num_subgroups;
2732 :
2733 : /**
2734 : * @brief Subgroup specific information
2735 : *
2736 : * If a subgroup's metadata_len is set to 0, the existing metadata
2737 : * for the subgroup will remain unchanged
2738 : */
2739 1 : struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS];
2740 : };
2741 :
2742 : /**
2743 : * @brief Add a receive state source locally
2744 : *
2745 : * This will notify any connected clients about the new source. This allows them
2746 : * to modify and even remove it.
2747 : *
2748 : * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink
2749 : * sources are autonomously modified.
2750 : *
2751 : * @param param The parameters for adding the new source
2752 : *
2753 : * @return int errno on failure, or source ID on success.
2754 : */
2755 1 : int bt_bap_scan_delegator_mod_src(const struct bt_bap_scan_delegator_mod_src_param *param);
2756 :
2757 : /**
2758 : * @brief Remove a receive state source
2759 : *
2760 : * This will remove the receive state. If the receive state periodic advertising
2761 : * is synced, bt_bap_scan_delegator_cb.pa_sync_term_req() will be called.
2762 : *
2763 : * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink
2764 : * sources are autonomously removed.
2765 : *
2766 : * @param src_id The source ID to remove
2767 : *
2768 : * @return int Error value. 0 on success, errno on fail.
2769 : */
2770 1 : int bt_bap_scan_delegator_rem_src(uint8_t src_id);
2771 :
2772 : /** Callback function for Scan Delegator receive state search functions
2773 : *
2774 : * @param recv_state The receive state.
2775 : * @param user_data User data.
2776 : *
2777 : * @retval true to stop iterating. If this is used in the context of
2778 : * bt_bap_scan_delegator_find_state(), the recv_state will be returned by
2779 : * bt_bap_scan_delegator_find_state()
2780 : * @retval false to continue iterating
2781 : */
2782 1 : typedef bool (*bt_bap_scan_delegator_state_func_t)(
2783 : const struct bt_bap_scan_delegator_recv_state *recv_state, void *user_data);
2784 :
2785 : /**
2786 : * @brief Iterate through all existing receive states
2787 : *
2788 : * @param func The callback function
2789 : * @param user_data User specified data that sent to the callback function
2790 : */
2791 1 : void bt_bap_scan_delegator_foreach_state(bt_bap_scan_delegator_state_func_t func,
2792 : void *user_data);
2793 :
2794 : /**
2795 : * @brief Find and return a receive state based on a compare function
2796 : *
2797 : * @param func The compare callback function
2798 : * @param user_data User specified data that sent to the callback function
2799 : *
2800 : * @return The first receive state where the @p func returned true, or NULL
2801 : */
2802 1 : const struct bt_bap_scan_delegator_recv_state *bt_bap_scan_delegator_find_state(
2803 : bt_bap_scan_delegator_state_func_t func, void *user_data);
2804 :
2805 : /******************************** CLIENT API ********************************/
2806 :
2807 : /**
2808 : * @brief Callback function for writes.
2809 : *
2810 : * @param conn The connection to the peer device.
2811 : * @param err Error value. 0 on success, GATT error on fail.
2812 : */
2813 1 : typedef void (*bt_bap_broadcast_assistant_write_cb)(struct bt_conn *conn,
2814 : int err);
2815 :
2816 : /**
2817 : * @brief Struct to hold the Basic Audio Profile Broadcast Assistant callbacks
2818 : *
2819 : * These can be registered for usage with bt_bap_broadcast_assistant_register_cb().
2820 : */
2821 1 : struct bt_bap_broadcast_assistant_cb {
2822 : /**
2823 : * @brief Callback function for bt_bap_broadcast_assistant_discover.
2824 : *
2825 : * @param conn The connection that was used to discover
2826 : * Broadcast Audio Scan Service.
2827 : * @param err Error value. 0 on success,
2828 : * GATT error or ERRNO on fail.
2829 : * @param recv_state_count Number of receive states on the server.
2830 : */
2831 1 : void (*discover)(struct bt_conn *conn, int err,
2832 : uint8_t recv_state_count);
2833 :
2834 : /**
2835 : * @brief Callback function for Broadcast Audio Scan Service client scan results
2836 : *
2837 : * Called when the scanner finds an advertiser that advertises the
2838 : * BT_UUID_BROADCAST_AUDIO UUID.
2839 : *
2840 : * @param info Advertiser information.
2841 : * @param broadcast_id 24-bit broadcast ID.
2842 : */
2843 1 : void (*scan)(const struct bt_le_scan_recv_info *info,
2844 : uint32_t broadcast_id);
2845 :
2846 : /**
2847 : * @brief Callback function for when a receive state is read or updated
2848 : *
2849 : * Called whenever a receive state is read or updated.
2850 : *
2851 : * @param conn The connection to the Broadcast Audio Scan Service server.
2852 : * @param err Error value. 0 on success, GATT error on fail.
2853 : * @param state The receive state or NULL if the receive state is empty.
2854 : */
2855 1 : void (*recv_state)(struct bt_conn *conn, int err,
2856 : const struct bt_bap_scan_delegator_recv_state *state);
2857 :
2858 : /**
2859 : * @brief Callback function for when a receive state is removed.
2860 : *
2861 : * @param conn The connection to the Broadcast Audio Scan Service server.
2862 : * @param src_id The receive state.
2863 : */
2864 1 : void (*recv_state_removed)(struct bt_conn *conn, uint8_t src_id);
2865 :
2866 : /**
2867 : * @brief Callback function for bt_bap_broadcast_assistant_scan_start().
2868 : *
2869 : * @param conn The connection to the peer device.
2870 : * @param err Error value. 0 on success, GATT error on fail.
2871 : */
2872 1 : void (*scan_start)(struct bt_conn *conn, int err);
2873 :
2874 : /**
2875 : * @brief Callback function for bt_bap_broadcast_assistant_scan_stop().
2876 : *
2877 : * @param conn The connection to the peer device.
2878 : * @param err Error value. 0 on success, GATT error on fail.
2879 : */
2880 1 : void (*scan_stop)(struct bt_conn *conn, int err);
2881 :
2882 : /**
2883 : * @brief Callback function for bt_bap_broadcast_assistant_add_src().
2884 : *
2885 : * @param conn The connection to the peer device.
2886 : * @param err Error value. 0 on success, GATT error on fail.
2887 : */
2888 1 : void (*add_src)(struct bt_conn *conn, int err);
2889 :
2890 : /**
2891 : * @brief Callback function for bt_bap_broadcast_assistant_mod_src().
2892 : *
2893 : * @param conn The connection to the peer device.
2894 : * @param err Error value. 0 on success, GATT error on fail.
2895 : */
2896 1 : void (*mod_src)(struct bt_conn *conn, int err);
2897 :
2898 : /**
2899 : * @brief Callback function for bt_bap_broadcast_assistant_set_broadcast_code().
2900 : *
2901 : * @param conn The connection to the peer device.
2902 : * @param err Error value. 0 on success, GATT error on fail.
2903 : */
2904 1 : void (*broadcast_code)(struct bt_conn *conn, int err);
2905 :
2906 : /**
2907 : * @brief Callback function for bt_bap_broadcast_assistant_rem_src().
2908 : *
2909 : * @param conn The connection to the peer device.
2910 : * @param err Error value. 0 on success, GATT error on fail.
2911 : */
2912 1 : void (*rem_src)(struct bt_conn *conn, int err);
2913 :
2914 : /** @cond INTERNAL_HIDDEN */
2915 : /** Internally used list node */
2916 : sys_snode_t _node;
2917 : /** @endcond */
2918 : };
2919 :
2920 : /**
2921 : * @brief Discover Broadcast Audio Scan Service on the server.
2922 : *
2923 : * Warning: Only one connection can be active at any time; discovering for a
2924 : * new connection, will delete all previous data.
2925 : *
2926 : * @param conn The connection
2927 : *
2928 : * @retval 0 Success
2929 : * @retval -EINVAL @p conn is NULL
2930 : * @retval -EBUSY Another operation is already in progress for this @p conn
2931 : * @retval -ENOTCONN @p conn is not connected
2932 : * @retval -ENOMEM Could not allocated memory for the request
2933 : * @retval -ENOEXEC Unexpected GATT error
2934 : */
2935 1 : int bt_bap_broadcast_assistant_discover(struct bt_conn *conn);
2936 :
2937 : /**
2938 : * @brief Scan start for BISes for a remote server.
2939 : *
2940 : * This will let the Broadcast Audio Scan Service server know that this device
2941 : * is actively scanning for broadcast sources.
2942 : * The function can optionally also start scanning, if the caller does not want
2943 : * to start scanning itself.
2944 : *
2945 : * Scan results, if @p start_scan is true, is sent to the
2946 : * bt_bap_broadcast_assistant_scan_cb callback.
2947 : *
2948 : * @param conn Connection to the Broadcast Audio Scan Service server.
2949 : * Used to let the server know that we are scanning.
2950 : * @param start_scan Start scanning if true. If false, the application should
2951 : * enable scan itself.
2952 :
2953 : * @retval 0 Success
2954 : * @retval -EINVAL @p conn is NULL of if @p conn has not done discovery
2955 : * @retval -EBUSY Another operation is already in progress for this @p conn
2956 : * @retval -EAGAIN Bluetooth has not been enabled.
2957 : * @retval -ENOTCONN @p conn is not connected
2958 : * @retval -ENOMEM Could not allocated memory for the request
2959 : * @retval -ENOEXEC Unexpected scan or GATT error
2960 : */
2961 1 : int bt_bap_broadcast_assistant_scan_start(struct bt_conn *conn,
2962 : bool start_scan);
2963 :
2964 : /**
2965 : * @brief Stop remote scanning for BISes for a server.
2966 : *
2967 : * @param conn Connection to the server.
2968 :
2969 : * @retval 0 Success
2970 : * @retval -EINVAL @p conn is NULL of if @p conn has not done discovery
2971 : * @retval -EBUSY Another operation is already in progress for this @p conn
2972 : * @retval -EAGAIN Bluetooth has not been enabled.
2973 : * @retval -ENOTCONN @p conn is not connected
2974 : * @retval -ENOMEM Could not allocated memory for the request
2975 : * @retval -ENOEXEC Unexpected scan or GATT error
2976 : */
2977 1 : int bt_bap_broadcast_assistant_scan_stop(struct bt_conn *conn);
2978 :
2979 : /**
2980 : * @brief Registers the callbacks used by Broadcast Audio Scan Service client.
2981 : *
2982 : * @param cb The callback structure.
2983 : *
2984 : * @retval 0 on success
2985 : * @retval -EINVAL if @p cb is NULL
2986 : * @retval -EALREADY if @p cb was already registered
2987 : */
2988 1 : int bt_bap_broadcast_assistant_register_cb(struct bt_bap_broadcast_assistant_cb *cb);
2989 :
2990 : /**
2991 : * @brief Unregisters the callbacks used by the Broadcast Audio Scan Service client.
2992 : *
2993 : * @param cb The callback structure.
2994 : *
2995 : * @retval 0 on success
2996 : * @retval -EINVAL if @p cb is NULL
2997 : * @retval -EALREADY if @p cb was not registered
2998 : */
2999 1 : int bt_bap_broadcast_assistant_unregister_cb(struct bt_bap_broadcast_assistant_cb *cb);
3000 :
3001 :
3002 : /** Parameters for adding a source to a Broadcast Audio Scan Service server */
3003 1 : struct bt_bap_broadcast_assistant_add_src_param {
3004 : /** Address of the advertiser. */
3005 1 : bt_addr_le_t addr;
3006 :
3007 : /** SID of the advertising set. */
3008 1 : uint8_t adv_sid;
3009 :
3010 : /** Whether to sync to periodic advertisements. */
3011 1 : bool pa_sync;
3012 :
3013 : /** 24-bit broadcast ID */
3014 1 : uint32_t broadcast_id;
3015 :
3016 : /**
3017 : * @brief Periodic advertising interval in milliseconds.
3018 : *
3019 : * BT_BAP_PA_INTERVAL_UNKNOWN if unknown.
3020 : */
3021 1 : uint16_t pa_interval;
3022 :
3023 : /** Number of subgroups */
3024 1 : uint8_t num_subgroups;
3025 :
3026 : /** Pointer to array of subgroups
3027 : *
3028 : * The @ref bt_bap_bass_subgroup.bis_sync value can be set to BT_BAP_BIS_SYNC_NO_PREF to
3029 : * let the broadcast sink decide which BIS to synchronize to.
3030 : */
3031 1 : struct bt_bap_bass_subgroup *subgroups;
3032 : };
3033 :
3034 : /**
3035 : * @brief Add a source on the server.
3036 : *
3037 : * @param conn Connection to the server.
3038 : * @param param Parameter struct.
3039 : *
3040 : * @retval 0 Success
3041 : * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or if @p param is invalid
3042 : * @retval -EBUSY Another operation is already in progress for this @p conn
3043 : * @retval -ENOTCONN @p conn is not connected
3044 : * @retval -ENOMEM Could not allocated memory for the request
3045 : * @retval -ENOEXEC Unexpected scan or GATT error
3046 : */
3047 1 : int bt_bap_broadcast_assistant_add_src(
3048 : struct bt_conn *conn, const struct bt_bap_broadcast_assistant_add_src_param *param);
3049 :
3050 : /** Parameters for modifying a source */
3051 1 : struct bt_bap_broadcast_assistant_mod_src_param {
3052 : /** Source ID of the receive state. */
3053 1 : uint8_t src_id;
3054 :
3055 : /** Whether to sync to periodic advertisements. */
3056 1 : bool pa_sync;
3057 :
3058 : /**
3059 : * @brief Periodic advertising interval.
3060 : *
3061 : * BT_BAP_PA_INTERVAL_UNKNOWN if unknown.
3062 : */
3063 1 : uint16_t pa_interval;
3064 :
3065 : /** Number of subgroups */
3066 1 : uint8_t num_subgroups;
3067 :
3068 : /** Pointer to array of subgroups */
3069 1 : struct bt_bap_bass_subgroup *subgroups;
3070 : };
3071 :
3072 : /**
3073 : * @brief Modify a source on the server.
3074 : *
3075 : * @param conn Connection to the server.
3076 : * @param param Parameter struct.
3077 : *
3078 : * @retval 0 Success
3079 : * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or if @p param is invalid
3080 : * @retval -EBUSY Another operation is already in progress for this @p conn
3081 : * @retval -ENOTCONN @p conn is not connected
3082 : * @retval -ENOMEM Could not allocated memory for the request
3083 : * @retval -ENOEXEC Unexpected scan or GATT error
3084 : */
3085 1 : int bt_bap_broadcast_assistant_mod_src(
3086 : struct bt_conn *conn, const struct bt_bap_broadcast_assistant_mod_src_param *param);
3087 :
3088 : /**
3089 : * @brief Set a broadcast code to the specified receive state.
3090 : *
3091 : * @param conn Connection to the server.
3092 : * @param src_id Source ID of the receive state.
3093 : * @param broadcast_code The broadcast code.
3094 : *
3095 : * @retval 0 Success
3096 : * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or @p src_id is invalid
3097 : * @retval -EBUSY Another operation is already in progress for this @p conn
3098 : * @retval -ENOTCONN @p conn is not connected
3099 : * @retval -ENOMEM Could not allocated memory for the request
3100 : * @retval -ENOEXEC Unexpected scan or GATT error
3101 : */
3102 1 : int bt_bap_broadcast_assistant_set_broadcast_code(
3103 : struct bt_conn *conn, uint8_t src_id,
3104 : const uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]);
3105 :
3106 : /**
3107 : * @brief Remove a source from the server.
3108 : *
3109 : * @param conn Connection to the server.
3110 : * @param src_id Source ID of the receive state.
3111 : *
3112 : * @retval 0 Success
3113 : * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or @p src_id is invalid
3114 : * @retval -EBUSY Another operation is already in progress for this @p conn
3115 : * @retval -ENOTCONN @p conn is not connected
3116 : * @retval -ENOMEM Could not allocated memory for the request
3117 : * @retval -ENOEXEC Unexpected scan or GATT error
3118 : */
3119 1 : int bt_bap_broadcast_assistant_rem_src(struct bt_conn *conn, uint8_t src_id);
3120 :
3121 : /**
3122 : * @brief Read the specified receive state from the server.
3123 : *
3124 : * @param conn Connection to the server.
3125 : * @param idx The index of the receive start (0 up to the value from
3126 : * bt_bap_broadcast_assistant_discover_cb)
3127 : *
3128 : * @retval 0 Success
3129 : * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or @p src_id is invalid
3130 : * @retval -EBUSY Another operation is already in progress for this @p conn
3131 : * @retval -ENOTCONN @p conn is not connected
3132 : * @retval -ENOMEM Could not allocated memory for the request
3133 : * @retval -ENOEXEC Unexpected scan or GATT error
3134 : */
3135 1 : int bt_bap_broadcast_assistant_read_recv_state(struct bt_conn *conn, uint8_t idx);
3136 :
3137 : /** @} */ /* end of bt_bap */
3138 :
3139 : #ifdef __cplusplus
3140 : }
3141 : #endif
3142 :
3143 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_ */
|