Line data Source code
1 1 : /**
2 : * @file
3 : * @brief Bluetooth Common Audio Profile (CAP) APIs.
4 : */
5 :
6 : /*
7 : * Copyright (c) 2022-2025 Nordic Semiconductor ASA
8 : *
9 : * SPDX-License-Identifier: Apache-2.0
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_
13 : #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_
14 :
15 : /**
16 : * @brief Common Audio Profile (CAP)
17 : *
18 : * @defgroup bt_cap Common Audio Profile (CAP)
19 : *
20 : * @since 3.2
21 : * @version 0.8.0
22 : *
23 : * @ingroup bluetooth
24 : * @{
25 : *
26 : * Common Audio Profile (CAP) provides procedures to start, update, and stop unicast and broadcast
27 : * Audio Streams on individual or groups of devices using procedures in the Basic Audio Profile
28 : * (BAP). This profile also provides procedures to control volume and device input on groups of
29 : * devices using procedures in the Volume Control Profile (VCP) and the Microphone Control Profile
30 : * (MICP). This profile specification also refers to the Common Audio Service (CAS).
31 : */
32 :
33 : #include <stdbool.h>
34 : #include <stddef.h>
35 : #include <stdint.h>
36 :
37 : #include <zephyr/bluetooth/audio/audio.h>
38 : #include <zephyr/bluetooth/audio/bap.h>
39 : #include <zephyr/bluetooth/audio/csip.h>
40 : #include <zephyr/bluetooth/addr.h>
41 : #include <zephyr/bluetooth/bluetooth.h>
42 : #include <zephyr/bluetooth/conn.h>
43 : #include <zephyr/bluetooth/iso.h>
44 : #include <zephyr/net_buf.h>
45 :
46 : #ifdef __cplusplus
47 : extern "C" {
48 : #endif
49 :
50 : /** @brief Abstract Audio Broadcast Source structure. */
51 : struct bt_cap_broadcast_source;
52 :
53 : /** @brief Abstract CAP Unicast Group structure. */
54 : struct bt_cap_unicast_group;
55 :
56 : /**
57 : * @brief Register the Common Audio Service.
58 : *
59 : * This will register and enable the service and make it discoverable by
60 : * clients. This will also register a Coordinated Set Identification
61 : * Service instance.
62 : *
63 : * This shall only be done as a server, and requires
64 : * @kconfig{BT_CAP_ACCEPTOR_SET_MEMBER}. If @kconfig{BT_CAP_ACCEPTOR_SET_MEMBER}
65 : * is not enabled, the Common Audio Service will by statically registered.
66 : *
67 : * @param[in] param Coordinated Set Identification Service register
68 : * parameters.
69 : * @param[out] svc_inst Pointer to the registered Coordinated Set
70 : * Identification Service.
71 : *
72 : * @return 0 if success, errno on failure.
73 : */
74 1 : int bt_cap_acceptor_register(const struct bt_csip_set_member_register_param *param,
75 : struct bt_csip_set_member_svc_inst **svc_inst);
76 :
77 : /** Callback structure for CAP procedures */
78 1 : struct bt_cap_initiator_cb {
79 : #if defined(CONFIG_BT_BAP_UNICAST_CLIENT) || defined(__DOXYGEN__)
80 : /**
81 : * @brief Callback for bt_cap_initiator_unicast_discover().
82 : *
83 : * @param conn The connection pointer supplied to
84 : * bt_cap_initiator_unicast_discover().
85 : * @param err 0 if Common Audio Service was found else -ENODATA.
86 : * @param member Pointer to the set member. NULL if err != 0.
87 : * @param csis_inst The Coordinated Set Identification Service if
88 : * Common Audio Service was found and includes a
89 : * Coordinated Set Identification Service.
90 : * NULL on error or if remote device does not include
91 : * Coordinated Set Identification Service. NULL if err != 0.
92 : */
93 1 : void (*unicast_discovery_complete)(
94 : struct bt_conn *conn, int err,
95 : const struct bt_csip_set_coordinator_set_member *member,
96 : const struct bt_csip_set_coordinator_csis_inst *csis_inst);
97 :
98 : /**
99 : * @brief Callback for bt_cap_initiator_unicast_audio_start().
100 : *
101 : * @param err 0 if success, BT_GATT_ERR() with a
102 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
103 : * by bt_cap_initiator_unicast_audio_cancel().
104 : * @param conn Pointer to the connection where the error
105 : * occurred. NULL if @p err is 0 or if cancelled by
106 : * bt_cap_initiator_unicast_audio_cancel()
107 : */
108 1 : void (*unicast_start_complete)(int err, struct bt_conn *conn);
109 :
110 : /**
111 : * @brief Callback for bt_cap_initiator_unicast_audio_update().
112 : *
113 : * @param err 0 if success, BT_GATT_ERR() with a
114 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
115 : * by bt_cap_initiator_unicast_audio_cancel().
116 : * @param conn Pointer to the connection where the error
117 : * occurred. NULL if @p err is 0 or if cancelled by
118 : * bt_cap_initiator_unicast_audio_cancel()
119 : */
120 1 : void (*unicast_update_complete)(int err, struct bt_conn *conn);
121 :
122 : /**
123 : * @brief Callback for bt_cap_initiator_unicast_audio_stop().
124 : *
125 : * @param err 0 if success, BT_GATT_ERR() with a
126 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
127 : * by bt_cap_initiator_unicast_audio_cancel().
128 : * @param conn Pointer to the connection where the error
129 : * occurred. NULL if @p err is 0 or if cancelled by
130 : * bt_cap_initiator_unicast_audio_cancel()
131 : */
132 1 : void (*unicast_stop_complete)(int err, struct bt_conn *conn);
133 : #endif /* CONFIG_BT_BAP_UNICAST_CLIENT */
134 : #if defined(CONFIG_BT_BAP_BROADCAST_SOURCE)
135 : /**
136 : * @brief The Broadcast Source has started and all of the streams are ready for audio data
137 : *
138 : * @param source The started Broadcast Source
139 : */
140 : void (*broadcast_started)(struct bt_cap_broadcast_source *source);
141 :
142 : /**
143 : * @brief The Broadcast Source has stopped and none of the streams are ready for audio data
144 : *
145 : * @param source The stopped Broadcast Source
146 : * @param reason The reason why the Broadcast Source stopped (see the BT_HCI_ERR_* values)
147 : */
148 : void (*broadcast_stopped)(struct bt_cap_broadcast_source *source, uint8_t reason);
149 : #endif /* CONFIG_BT_BAP_BROADCAST_SOURCE */
150 : };
151 :
152 : /**
153 : * @brief Discovers audio support on a remote device.
154 : *
155 : * This will discover the Common Audio Service (CAS) on the remote device, to
156 : * verify if the remote device supports the Common Audio Profile.
157 : *
158 : * @param conn Connection to a remote server.
159 : *
160 : * @retval 0 Success
161 : * @retval -EINVAL @p conn is NULL
162 : * @retval -ENOTCONN @p conn is not connected
163 : * @retval -ENOMEM Could not allocated memory for the request
164 : */
165 1 : int bt_cap_initiator_unicast_discover(struct bt_conn *conn);
166 :
167 : /** Type of CAP set */
168 1 : enum bt_cap_set_type {
169 : /** The set is an ad-hoc set */
170 : BT_CAP_SET_TYPE_AD_HOC,
171 : /** The set is a CSIP Coordinated Set */
172 : BT_CAP_SET_TYPE_CSIP,
173 : };
174 :
175 : /** Represents a Common Audio Set member that are either in a Coordinated or ad-hoc set */
176 1 : union bt_cap_set_member {
177 : /** Connection pointer if the type is BT_CAP_SET_TYPE_AD_HOC. */
178 1 : struct bt_conn *member;
179 :
180 : /** CSIP Coordinated Set struct used if type is BT_CAP_SET_TYPE_CSIP. */
181 1 : struct bt_csip_set_coordinator_csis_inst *csip;
182 : };
183 :
184 : /**
185 : * @brief Common Audio Profile stream structure.
186 : *
187 : * Streams represents a Basic Audio Profile (BAP) stream and operation callbacks.
188 : * See @ref bt_bap_stream for additional information.
189 : */
190 1 : struct bt_cap_stream {
191 : /** The underlying BAP audio stream */
192 1 : struct bt_bap_stream bap_stream;
193 :
194 : /** Audio stream operations */
195 1 : struct bt_bap_stream_ops *ops;
196 : };
197 :
198 : /**
199 : * @brief Register Audio operations for a Common Audio Profile stream.
200 : *
201 : * Register Audio operations for a stream.
202 : *
203 : * @param stream Stream object.
204 : * @param ops Stream operations structure.
205 : */
206 1 : void bt_cap_stream_ops_register(struct bt_cap_stream *stream, struct bt_bap_stream_ops *ops);
207 :
208 : /**
209 : * @brief Send data to Common Audio Profile stream without timestamp
210 : *
211 : * See bt_bap_stream_send() for more information
212 : *
213 : * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}.
214 : *
215 : * @param stream Stream object.
216 : * @param buf Buffer containing data to be sent.
217 : * @param seq_num Packet Sequence number. This value shall be incremented for each call to this
218 : * function and at least once per SDU interval for a specific channel.
219 : *
220 : * @retval -EINVAL if stream object is NULL
221 : * @retval Any return value from bt_bap_stream_send()
222 : */
223 1 : int bt_cap_stream_send(struct bt_cap_stream *stream, struct net_buf *buf, uint16_t seq_num);
224 :
225 : /**
226 : * @brief Send data to Common Audio Profile stream with timestamp
227 : *
228 : * See bt_bap_stream_send() for more information
229 : *
230 : * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}.
231 : *
232 : * @param stream Stream object.
233 : * @param buf Buffer containing data to be sent.
234 : * @param seq_num Packet Sequence number. This value shall be incremented for each call to this
235 : * function and at least once per SDU interval for a specific channel.
236 : * @param ts Timestamp of the SDU in microseconds (us). This value can be used to transmit
237 : * multiple SDUs in the same SDU interval in a CIG or BIG.
238 : *
239 : * @retval -EINVAL if stream object is NULL
240 : * @retval Any return value from bt_bap_stream_send()
241 : */
242 1 : int bt_cap_stream_send_ts(struct bt_cap_stream *stream, struct net_buf *buf, uint16_t seq_num,
243 : uint32_t ts);
244 :
245 : /**
246 : * @brief Get ISO transmission timing info for a Common Audio Profile stream
247 : *
248 : * See bt_bap_stream_get_tx_sync() for more information
249 : *
250 : * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}.
251 : *
252 : * @param[in] stream Stream object.
253 : * @param[out] info Transmit info object.
254 : *
255 : * @retval -EINVAL if stream object is NULL
256 : * @retval Any return value from bt_bap_stream_get_tx_sync()
257 : */
258 1 : int bt_cap_stream_get_tx_sync(struct bt_cap_stream *stream, struct bt_iso_tx_info *info);
259 :
260 : /** Parameter struct for each stream in the unicast group */
261 1 : struct bt_cap_unicast_group_stream_param {
262 : /** Pointer to a stream object. */
263 1 : struct bt_cap_stream *stream;
264 :
265 : /** The QoS settings for the stream object. */
266 1 : struct bt_bap_qos_cfg *qos_cfg;
267 : };
268 :
269 : /**
270 : * @brief Parameter struct for the unicast group functions
271 : *
272 : * Parameter struct for the bt_cap_unicast_group_create() and
273 : * bt_cap_unicast_group_add_streams() functions.
274 : */
275 1 : struct bt_cap_unicast_group_stream_pair_param {
276 : /** Pointer to a receiving stream parameters. */
277 1 : struct bt_cap_unicast_group_stream_param *rx_param;
278 :
279 : /** Pointer to a transmitting stream parameters. */
280 1 : struct bt_cap_unicast_group_stream_param *tx_param;
281 : };
282 :
283 : /** Parameters for the creating unicast groups with bt_cap_unicast_group_create() */
284 1 : struct bt_cap_unicast_group_param {
285 : /** The number of parameters in @p params */
286 1 : size_t params_count;
287 :
288 : /** Array of stream parameters */
289 1 : struct bt_cap_unicast_group_stream_pair_param *params;
290 :
291 : /**
292 : * @brief Unicast Group packing mode.
293 : *
294 : * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED.
295 : *
296 : * @note This is a recommendation to the controller, which the controller may ignore.
297 : */
298 1 : uint8_t packing;
299 :
300 : #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
301 : /**
302 : * @brief Central to Peripheral flush timeout
303 : *
304 : * The flush timeout in multiples of ISO_Interval for each payload sent
305 : * from the Central to Peripheral.
306 : *
307 : * Value range from @ref BT_ISO_FT_MIN to @ref BT_ISO_FT_MAX
308 : */
309 1 : uint8_t c_to_p_ft;
310 :
311 : /**
312 : * @brief Peripheral to Central flush timeout
313 : *
314 : * The flush timeout in multiples of ISO_Interval for each payload sent
315 : * from the Peripheral to Central.
316 : *
317 : * Value range from @ref BT_ISO_FT_MIN to @ref BT_ISO_FT_MAX.
318 : */
319 1 : uint8_t p_to_c_ft;
320 :
321 : /**
322 : * @brief ISO interval
323 : *
324 : * Time between consecutive CIS anchor points.
325 : *
326 : * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX.
327 : */
328 1 : uint16_t iso_interval;
329 : #endif /* CONFIG_BT_ISO_TEST_PARAMS */
330 : };
331 :
332 : /**
333 : * @brief Create unicast group.
334 : *
335 : * Create a new audio unicast group with one or more audio streams as a unicast client.
336 : * All streams shall share the same framing.
337 : * All streams in the same direction shall share the same interval and latency (see
338 : * @ref bt_bap_qos_cfg).
339 : *
340 : * @param[in] param The unicast group create parameters.
341 : * @param[out] unicast_group Pointer to the unicast group created.
342 : *
343 : * @return Zero on success or (negative) error code otherwise.
344 : */
345 1 : int bt_cap_unicast_group_create(const struct bt_cap_unicast_group_param *param,
346 : struct bt_cap_unicast_group **unicast_group);
347 :
348 : /**
349 : * @brief Reconfigure unicast group.
350 : *
351 : * Reconfigure a unicast group with one or more audio streams as a unicast client.
352 : * All streams shall share the same framing.
353 : * All streams in the same direction shall share the same interval and latency (see
354 : * @ref bt_bap_qos_cfg).
355 : * All streams in @p param shall already belong to @p unicast_group.
356 : * Use bt_cap_unicast_group_add_streams() to add additional streams.
357 : *
358 : * @param unicast_group Pointer to the unicast group created.
359 : * @param param The unicast group reconfigure parameters.
360 : *
361 : * @return Zero on success or (negative) error code otherwise.
362 : */
363 1 : int bt_cap_unicast_group_reconfig(struct bt_cap_unicast_group *unicast_group,
364 : const struct bt_cap_unicast_group_param *param);
365 :
366 : /**
367 : * @brief Add streams to a unicast group as a unicast client
368 : *
369 : * This function can be used to add additional streams to a bt_cap_unicast_group.
370 : *
371 : * This can be called at any time before any of the streams in the group has been started
372 : * (see bt_bap_stream_ops.started()).
373 : * This can also be called after the streams have been stopped (see bt_bap_stream_ops.stopped()).
374 : *
375 : * Once a stream has been added to a unicast group, it cannot be removed. To remove a stream from a
376 : * group, the group must be deleted with bt_cap_unicast_group_delete(), but this will require all
377 : * streams in the group to be released first.
378 : *
379 : * @param unicast_group Pointer to the unicast group
380 : * @param params Array of stream parameters with streams being added to the group.
381 : * @param num_param Number of parameters in @p params.
382 : *
383 : * @return 0 in case of success or negative value in case of error.
384 : */
385 1 : int bt_cap_unicast_group_add_streams(struct bt_cap_unicast_group *unicast_group,
386 : const struct bt_cap_unicast_group_stream_pair_param params[],
387 : size_t num_param);
388 :
389 : /**
390 : * @brief Delete audio unicast group.
391 : *
392 : * Delete a audio unicast group as a client. All streams in the group shall
393 : * be in the idle or configured state.
394 : *
395 : * @param unicast_group Pointer to the unicast group to delete
396 : *
397 : * @return Zero on success or (negative) error code otherwise.
398 : */
399 1 : int bt_cap_unicast_group_delete(struct bt_cap_unicast_group *unicast_group);
400 :
401 : /** Callback function for bt_bap_unicast_group_foreach_stream()
402 : *
403 : * @param stream The audio stream
404 : * @param user_data User data
405 : *
406 : * @retval true Stop iterating.
407 : * @retval false Continue iterating.
408 : */
409 1 : typedef bool (*bt_cap_unicast_group_foreach_stream_func_t)(struct bt_cap_stream *stream,
410 : void *user_data);
411 :
412 : /**
413 : * @brief Iterate through all streams in a unicast group
414 : *
415 : * @param unicast_group The unicast group
416 : * @param func The callback function
417 : * @param user_data User specified data that is sent to the callback function
418 : *
419 : * @retval 0 Success (even if no streams exists in the group).
420 : * @retval -ECANCELED The @p func returned true.
421 : * @retval -EINVAL @p unicast_group or @p func were NULL.
422 : */
423 1 : int bt_cap_unicast_group_foreach_stream(struct bt_cap_unicast_group *unicast_group,
424 : bt_cap_unicast_group_foreach_stream_func_t func,
425 : void *user_data);
426 :
427 : /** Structure holding information of audio stream endpoint */
428 1 : struct bt_cap_unicast_group_info {
429 : /** Pointer to the underlying Basic Audio Profile unicast group */
430 1 : const struct bt_bap_unicast_group *unicast_group;
431 : };
432 :
433 : /**
434 : * @brief Return structure holding information of unicast group
435 : *
436 : * @param unicast_group The unicast group object.
437 : * @param info The structure object to be filled with the info.
438 : *
439 : * @retval 0 Success
440 : * @retval -EINVAL @p unicast_group or @p info are NULL
441 : */
442 1 : int bt_cap_unicast_group_get_info(const struct bt_cap_unicast_group *unicast_group,
443 : struct bt_cap_unicast_group_info *info);
444 :
445 : /** Stream specific parameters for the bt_cap_initiator_unicast_audio_start() function */
446 1 : struct bt_cap_unicast_audio_start_stream_param {
447 : /** Coordinated or ad-hoc set member. */
448 1 : union bt_cap_set_member member;
449 :
450 : /** @brief Stream for the @p member */
451 1 : struct bt_cap_stream *stream;
452 :
453 : /** Endpoint reference for the @p stream */
454 1 : struct bt_bap_ep *ep;
455 :
456 : /**
457 : * @brief Codec configuration.
458 : *
459 : * The @p codec_cfg.meta shall include a list of CCIDs
460 : * (@ref BT_AUDIO_METADATA_TYPE_CCID_LIST) as well as a non-0
461 : * stream context (@ref BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT) bitfield.
462 : *
463 : * This value is assigned to the @p stream, and shall remain valid while the stream is
464 : * non-idle.
465 : */
466 1 : struct bt_audio_codec_cfg *codec_cfg;
467 : };
468 :
469 : /** Parameters for the bt_cap_initiator_unicast_audio_start() function */
470 1 : struct bt_cap_unicast_audio_start_param {
471 : /** The type of the set. */
472 1 : enum bt_cap_set_type type;
473 :
474 : /** The number of parameters in @p stream_params */
475 1 : size_t count;
476 :
477 : /** Array of stream parameters */
478 1 : struct bt_cap_unicast_audio_start_stream_param *stream_params;
479 : };
480 :
481 : /** Stream specific parameters for the bt_cap_initiator_unicast_audio_update() function */
482 1 : struct bt_cap_unicast_audio_update_stream_param {
483 : /** Stream to update */
484 1 : struct bt_cap_stream *stream;
485 :
486 : /** The length of @p meta. */
487 1 : size_t meta_len;
488 :
489 : /**
490 : * @brief The new metadata.
491 : *
492 : * The metadata shall contain a list of CCIDs as well as a non-0 context bitfield.
493 : */
494 1 : uint8_t *meta;
495 : };
496 :
497 : /** Parameters for the bt_cap_initiator_unicast_audio_update() function */
498 1 : struct bt_cap_unicast_audio_update_param {
499 : /** The type of the set. */
500 1 : enum bt_cap_set_type type;
501 :
502 : /** The number of parameters in @p stream_params */
503 1 : size_t count;
504 :
505 : /** Array of stream parameters */
506 1 : struct bt_cap_unicast_audio_update_stream_param *stream_params;
507 : };
508 :
509 : /** Parameters for the bt_cap_initiator_unicast_audio_stop() function */
510 1 : struct bt_cap_unicast_audio_stop_param {
511 : /** The type of the set. */
512 1 : enum bt_cap_set_type type;
513 :
514 : /** The number of streams in @p streams */
515 1 : size_t count;
516 :
517 : /** Array of streams to stop */
518 1 : struct bt_cap_stream **streams;
519 :
520 : /** Whether to release the streams after they have stopped */
521 1 : bool release;
522 : };
523 :
524 : /**
525 : * @brief Register Common Audio Profile Initiator callbacks
526 : *
527 : * @param cb The callback structure. Shall remain static.
528 : *
529 : * @return 0 on success or negative error value on failure.
530 : */
531 1 : int bt_cap_initiator_register_cb(const struct bt_cap_initiator_cb *cb);
532 :
533 : /**
534 : * @brief Unregister Common Audio Profile Initiator callbacks
535 : *
536 : * @param cb The callback structure that was previously registered.
537 : *
538 : * @retval 0 Success
539 : * @retval -EINVAL @p cb is NULL or @p cb was not registered
540 : */
541 1 : int bt_cap_initiator_unregister_cb(const struct bt_cap_initiator_cb *cb);
542 :
543 : /**
544 : * @brief Setup and start unicast audio streams for a set of devices.
545 : *
546 : * The result of this operation is that the streams in @p param will be
547 : * initialized and will be usable for streaming audio data.
548 : * The @p unicast_group value can be used to update and stop the streams.
549 : *
550 : * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and
551 : * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function
552 : * to be enabled.
553 : *
554 : * @param param Parameters to start the audio streams.
555 : *
556 : * @retval 0 on success
557 : * @retval -EBUSY if a CAP procedure is already in progress
558 : * @retval -EINVAL if any parameter is invalid
559 : * @retval -EALREADY All streams are already in the streaming state
560 : */
561 1 : int bt_cap_initiator_unicast_audio_start(const struct bt_cap_unicast_audio_start_param *param);
562 :
563 : /**
564 : * @brief Update unicast audio streams.
565 : *
566 : * This will update the metadata of one or more streams.
567 : *
568 : * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and
569 : * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function
570 : * to be enabled.
571 : *
572 : * @param param Update parameters.
573 : *
574 : * @return 0 on success or negative error value on failure.
575 : */
576 1 : int bt_cap_initiator_unicast_audio_update(const struct bt_cap_unicast_audio_update_param *param);
577 :
578 : /**
579 : * @brief Stop unicast audio streams.
580 : *
581 : * This will stop one or more streams.
582 : *
583 : * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and
584 : * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function
585 : * to be enabled.
586 : *
587 : * @param param Stop parameters.
588 : *
589 : * @return 0 on success
590 : * @retval -EBUSY if a CAP procedure is already in progress
591 : * @retval -EINVAL if any parameter is invalid
592 : * @retval -EALREADY if no state changes will occur
593 : */
594 1 : int bt_cap_initiator_unicast_audio_stop(const struct bt_cap_unicast_audio_stop_param *param);
595 :
596 : /**
597 : * @brief Cancel any current Common Audio Profile procedure
598 : *
599 : * This will stop the current procedure from continuing and making it possible to run a new
600 : * Common Audio Profile procedure.
601 : *
602 : * It is recommended to do this if any existing procedure takes longer time than expected, which
603 : * could indicate a missing response from the Common Audio Profile Acceptor.
604 : *
605 : * This does not send any requests to any Common Audio Profile Acceptors involved with the current
606 : * procedure, and thus notifications from the Common Audio Profile Acceptors may arrive after this
607 : * has been called. It is thus recommended to either only use this if a procedure has stalled, or
608 : * wait a short while before starting any new Common Audio Profile procedure after this has been
609 : * called to avoid getting notifications from the cancelled procedure. The wait time depends on
610 : * the connection interval, the number of devices in the previous procedure and the behavior of the
611 : * Common Audio Profile Acceptors.
612 : *
613 : * The respective callbacks of the procedure will be called as part of this with the connection
614 : * pointer set to 0 and the err value set to -ECANCELED.
615 : *
616 : * @retval 0 on success
617 : * @retval -EALREADY if no procedure is active
618 : */
619 1 : int bt_cap_initiator_unicast_audio_cancel(void);
620 :
621 : /**
622 : * Parameters part of @p bt_cap_initiator_broadcast_subgroup_param for
623 : * bt_cap_initiator_broadcast_audio_create()
624 : */
625 1 : struct bt_cap_initiator_broadcast_stream_param {
626 : /** Audio stream */
627 1 : struct bt_cap_stream *stream;
628 :
629 : /** The length of the %p data array.
630 : *
631 : * The BIS specific data may be omitted and this set to 0.
632 : */
633 1 : size_t data_len;
634 :
635 : /** BIS Codec Specific Configuration */
636 1 : uint8_t *data;
637 : };
638 :
639 : /**
640 : * Parameters part of @p bt_cap_initiator_broadcast_create_param for
641 : * bt_cap_initiator_broadcast_audio_create()
642 : */
643 1 : struct bt_cap_initiator_broadcast_subgroup_param {
644 : /** The number of parameters in @p stream_params */
645 1 : size_t stream_count;
646 :
647 : /** Array of stream parameters */
648 1 : struct bt_cap_initiator_broadcast_stream_param *stream_params;
649 :
650 : /** Subgroup Codec configuration. */
651 1 : struct bt_audio_codec_cfg *codec_cfg;
652 : };
653 :
654 : /** Parameters for * bt_cap_initiator_broadcast_audio_create() */
655 1 : struct bt_cap_initiator_broadcast_create_param {
656 : /** The number of parameters in @p subgroup_params */
657 1 : size_t subgroup_count;
658 :
659 : /** Array of stream parameters */
660 1 : struct bt_cap_initiator_broadcast_subgroup_param *subgroup_params;
661 :
662 : /** Quality of Service configuration. */
663 1 : struct bt_bap_qos_cfg *qos;
664 :
665 : /**
666 : * @brief Broadcast Source packing mode.
667 : *
668 : * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED.
669 : *
670 : * @note This is a recommendation to the controller, which the controller may ignore.
671 : */
672 1 : uint8_t packing;
673 :
674 : /** Whether or not to encrypt the streams. */
675 1 : bool encryption;
676 :
677 : /**
678 : * @brief 16-octet broadcast code.
679 : *
680 : * Only valid if @p encrypt is true.
681 : *
682 : * If the value is a string or a the value is less than 16 octets,
683 : * the remaining octets shall be 0.
684 : *
685 : * Example:
686 : * The string "Broadcast Code" shall be
687 : * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
688 : */
689 1 : uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE];
690 :
691 : #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__)
692 : /**
693 : * @brief Immediate Repetition Count
694 : *
695 : * The number of times the scheduled payloads are transmitted in a given event.
696 : *
697 : * Value range from @ref BT_ISO_IRC_MIN to @ref BT_ISO_IRC_MAX.
698 : */
699 1 : uint8_t irc;
700 :
701 : /**
702 : * @brief Pre-transmission offset
703 : *
704 : * Offset used for pre-transmissions.
705 : *
706 : * Value range from @ref BT_ISO_PTO_MIN to @ref BT_ISO_PTO_MAX.
707 : */
708 1 : uint8_t pto;
709 :
710 : /**
711 : * @brief ISO interval
712 : *
713 : * Time between consecutive BIS anchor points.
714 : *
715 : * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX.
716 : */
717 1 : uint16_t iso_interval;
718 : #endif /* CONFIG_BT_ISO_TEST_PARAMS */
719 : };
720 :
721 : /**
722 : * @brief Create a Common Audio Profile broadcast source.
723 : *
724 : * Create a new audio broadcast source with one or more audio streams.
725 : *
726 : * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and
727 : * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function
728 : * to be enabled.
729 : *
730 : * @param[in] param Parameters to start the audio streams.
731 : * @param[out] broadcast_source Pointer to the broadcast source created.
732 : *
733 : * @retval 0 Success
734 : * @retval -EINVAL @p param is invalid or @p broadcast_source is NULL
735 : * @retval -ENOMEM Could not allocate more broadcast sources, subgroups or ISO streams, or the
736 : * provided codec configuration data is too large when merging the BIS and subgroup
737 : * configuration data.
738 : * @retval -ENOEXEC The broadcast source failed to be created for other reasons
739 : */
740 1 : int bt_cap_initiator_broadcast_audio_create(
741 : const struct bt_cap_initiator_broadcast_create_param *param,
742 : struct bt_cap_broadcast_source **broadcast_source);
743 :
744 : /**
745 : * @brief Start Common Audio Profile broadcast source.
746 : *
747 : * The broadcast source will be visible for scanners once this has been called,
748 : * and the device will advertise audio announcements.
749 : *
750 : * This will allow the streams in the broadcast source to send audio by calling
751 : * bt_bap_stream_send().
752 : *
753 : * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and
754 : * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function
755 : * to be enabled.
756 : *
757 : * @param broadcast_source Pointer to the broadcast source.
758 : * @param adv Pointer to an extended advertising set with
759 : * periodic advertising configured.
760 : *
761 : * @return 0 on success or negative error value on failure.
762 : */
763 1 : int bt_cap_initiator_broadcast_audio_start(struct bt_cap_broadcast_source *broadcast_source,
764 : struct bt_le_ext_adv *adv);
765 : /**
766 : * @brief Update broadcast audio streams for a Common Audio Profile broadcast source.
767 : *
768 : * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and
769 : * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function
770 : * to be enabled.
771 : *
772 : * @param broadcast_source The broadcast source to update.
773 : * @param meta The new metadata. The metadata shall contain a list
774 : * of CCIDs as well as a non-0 context bitfield.
775 : * @param meta_len The length of @p meta.
776 : *
777 : * @return 0 on success or negative error value on failure.
778 : */
779 1 : int bt_cap_initiator_broadcast_audio_update(struct bt_cap_broadcast_source *broadcast_source,
780 : const uint8_t meta[], size_t meta_len);
781 :
782 : /**
783 : * @brief Stop broadcast audio streams for a Common Audio Profile broadcast source.
784 : *
785 : * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and
786 : * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function
787 : * to be enabled.
788 : *
789 : * @param broadcast_source The broadcast source to stop. The audio streams
790 : * in this will be stopped and reset.
791 : *
792 : * @return 0 on success or negative error value on failure.
793 : */
794 1 : int bt_cap_initiator_broadcast_audio_stop(struct bt_cap_broadcast_source *broadcast_source);
795 :
796 : /**
797 : * @brief Delete Common Audio Profile broadcast source
798 : *
799 : * This can only be done after the broadcast source has been stopped by calling
800 : * bt_cap_initiator_broadcast_audio_stop() and after the
801 : * bt_bap_stream_ops.stopped() callback has been called for all streams in the
802 : * broadcast source.
803 : *
804 : * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and
805 : * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function
806 : * to be enabled.
807 : *
808 : * @param broadcast_source The broadcast source to delete.
809 : * The @p broadcast_source will be invalidated.
810 : *
811 : * @return 0 on success or negative error value on failure.
812 : */
813 1 : int bt_cap_initiator_broadcast_audio_delete(struct bt_cap_broadcast_source *broadcast_source);
814 :
815 : /**
816 : * @brief Get the Broadcast Audio Stream Endpoint of a Common Audio Profile broadcast source
817 : *
818 : * This will encode the BASE of a broadcast source into a buffer, that can be
819 : * used for advertisement. The encoded BASE will thus be encoded as
820 : * little-endian. The BASE shall be put into the periodic advertising data
821 : * (see bt_le_per_adv_set_data()).
822 : *
823 : * See table 3.15 in the Basic Audio Profile v1.0.1 for the structure.
824 : *
825 : * @param broadcast_source Pointer to the broadcast source.
826 : * @param base_buf Pointer to a buffer where the BASE will be inserted.
827 : *
828 : * @return int 0 if on success, errno on error.
829 : */
830 1 : int bt_cap_initiator_broadcast_get_base(struct bt_cap_broadcast_source *broadcast_source,
831 : struct net_buf_simple *base_buf);
832 :
833 : /** Callback function for bt_cap_initiator_broadcast_foreach_stream()
834 : *
835 : * @param stream The audio stream
836 : * @param user_data User data
837 : *
838 : * @retval true Stop iterating.
839 : * @retval false Continue iterating.
840 : */
841 1 : typedef bool (*bt_cap_initiator_broadcast_foreach_stream_func_t)(struct bt_cap_stream *stream,
842 : void *user_data);
843 :
844 : /**
845 : * @brief Iterate through all streams in a broadcast source
846 : *
847 : * @param broadcast_source The broadcast source.
848 : * @param func The callback function.
849 : * @param user_data User specified data that is sent to the callback function.
850 : *
851 : * @retval 0 Success (even if no streams exists in the group).
852 : * @retval -ECANCELED The @p func returned true.
853 : * @retval -EINVAL @p broadcast_source or @p func were NULL.
854 : */
855 1 : int bt_cap_initiator_broadcast_foreach_stream(struct bt_cap_broadcast_source *broadcast_source,
856 : bt_cap_initiator_broadcast_foreach_stream_func_t func,
857 : void *user_data);
858 :
859 : /** Parameters for bt_cap_handover_unicast_to_broadcast() */
860 1 : struct bt_cap_handover_unicast_to_broadcast_param {
861 : /** The type of the set. */
862 1 : enum bt_cap_set_type type;
863 :
864 : /** The source unicast group with the streams. */
865 1 : struct bt_cap_unicast_group *unicast_group;
866 :
867 : /**
868 : * @brief The advertising set to use for the broadcast source
869 : *
870 : * This shall remain valid until the procedure has completed.
871 : * If the advertising set is not started at the time of calling
872 : * bt_cap_handover_unicast_to_broadcast(),
873 : * the procedure will start the advertising set with @ref BT_LE_EXT_ADV_START_DEFAULT.
874 : */
875 1 : struct bt_le_ext_adv *ext_adv;
876 :
877 : /** The periodic advertising interval configured for the advertising set. */
878 1 : uint16_t pa_interval;
879 :
880 : /** The broadcast ID the advertising set is, or will be, using. */
881 1 : uint32_t broadcast_id;
882 :
883 : /**
884 : * @brief Broadcast source parameters.
885 : *
886 : * These parameters shall remain valid until the procedure has completed.
887 : */
888 1 : struct bt_cap_initiator_broadcast_create_param *broadcast_create_param;
889 : };
890 :
891 : /** Callback structure for CAP procedures */
892 1 : struct bt_cap_handover_cb {
893 : /**
894 : * @brief The unicast to broadcast handover procedure has finished
895 : *
896 : * @param err 0 if success else a negative errno value.
897 : * @param conn Pointer to the connection where the error occurred or NULL if local failure.
898 : * @param unicast_group NULL if the unicast group was deleted during the procedure, else
899 : * pointer to the unicast group provided in the parameters.
900 : * @param broadcast_source Pointer to newly created broadcast source, or NULL in case of an
901 : * error happening before it was created.
902 : */
903 1 : void (*unicast_to_broadcast_complete)(int err, struct bt_conn *conn,
904 : struct bt_cap_unicast_group *unicast_group,
905 : struct bt_cap_broadcast_source *broadcast_source);
906 :
907 : /**
908 : * @brief The broadcast to unicast handover procedure has finished
909 : *
910 : * @param err 0 if success else a negative errno value.
911 : * @param conn Pointer to the connection where the error occurred or NULL if local failure.
912 : * @param broadcast_source NULL if the broadcast sourced was deleted during the procedure,
913 : * else pointer to the broadcast sourced provided in the parameters.
914 : * @param unicast_group Pointer to newly created unicast group, or NULL in case of an
915 : * error happening before it was created.
916 : */
917 1 : void (*broadcast_to_unicast_complete)(int err, struct bt_conn *conn,
918 : struct bt_cap_broadcast_source *broadcast_source,
919 : struct bt_cap_unicast_group *unicast_group);
920 : };
921 :
922 : /**
923 : * @brief Register Common Audio Profile Handover callbacks
924 : *
925 : * @param cb The callback structure. Shall remain static.
926 : *
927 : * @return 0 on success or negative error value on failure.
928 : */
929 1 : int bt_cap_handover_register_cb(const struct bt_cap_handover_cb *cb);
930 :
931 : /**
932 : * @brief Unregister Common Audio Profile Handover callbacks
933 : *
934 : * @param cb The callback structure that was previously registered.
935 : *
936 : * @retval 0 Success
937 : * @retval -EINVAL @p cb is NULL or @p cb was not registered
938 : */
939 1 : int bt_cap_handover_unregister_cb(const struct bt_cap_handover_cb *cb);
940 :
941 : /**
942 : * @brief Hands over the sink streams in a unicast group to a broadcast source.
943 : *
944 : * All streams in the provided unicast group will be stopped and released. The sink streams will be
945 : * tranferred to a broadcast source, and the broadcast source information will be shared with
946 : * all accepters that are currently receiving audio. Any stream that is not in the streaming state
947 : * will only be released.
948 : *
949 : * bt_bap_broadcast_assistant_discover() must have been successfully perform for all members in @p
950 : * param before starting this procedure.
951 : *
952 : * @kconfig_dep{CONFIG_BT_CAP_HANDOVER}
953 : *
954 : * @param param The parameters for the handover.
955 : *
956 : * @return 0 on success or negative error value on failure.
957 : */
958 1 : int bt_cap_handover_unicast_to_broadcast(
959 : const struct bt_cap_handover_unicast_to_broadcast_param *param);
960 :
961 : /** Parameters for bt_cap_handover_broadcast_to_unicast() */
962 1 : struct bt_cap_handover_broadcast_to_unicast_param {
963 : /**
964 : * @brief Parameters for stopping broadcast audio reception on acceptors
965 : *
966 : * This parameter is optional as stopping the broadcast audio should automatically stop
967 : * broadcast audio reception on the acceptors. Omitting this parameter will rely on the CAP
968 : * acceptors timing out on the BIG once it is stopped. The timeout on the CAP acceptors will
969 : * be between @ref BT_ISO_SYNC_TIMEOUT_MIN and @ref BT_ISO_SYNC_TIMEOUT_MAX.
970 : */
971 1 : struct bt_cap_commander_broadcast_reception_stop_param *reception_stop_param;
972 :
973 : /** @brief Broadcast ID of the @p broadcast_source
974 : *
975 : * Ignored if @p reception_stop_param is not NULL.
976 : */
977 1 : uint32_t broadcast_id;
978 :
979 : /** @brief Advertising set ID of the @p broadcast_source
980 : *
981 : * Ignored if @p reception_stop_param is not NULL.
982 : */
983 1 : uint8_t adv_sid;
984 :
985 : /** @brief Advertising type of the advertising address of @p broadcast_source
986 : *
987 : * Ignored if @p reception_stop_param is not NULL.
988 : */
989 1 : uint8_t adv_type;
990 :
991 : /**
992 : * @brief The source broadcast source with the streams.
993 : *
994 : * The broadcast source will be stopped and deleted.
995 : */
996 1 : struct bt_cap_broadcast_source *broadcast_source;
997 :
998 : /* Parameters for the unicast group to be created */
999 0 : struct bt_cap_unicast_group_param *unicast_group_param;
1000 :
1001 : /* Parameters for starting the unicast audio */
1002 0 : struct bt_cap_unicast_audio_start_param *unicast_start_param;
1003 : };
1004 :
1005 : /**
1006 : * @brief Hands over the data streams in a broadcast source to a unicast group.
1007 : *
1008 : * The streams in the broadcast source will be stopped and the broadcast source
1009 : * will be deleted.
1010 : *
1011 : * @kconfig_dep{CONFIG_BT_CAP_HANDOVER}
1012 : *
1013 : * @param[in] param The parameters for the handover.
1014 : *
1015 : * @return 0 on success or negative error value on failure.
1016 : */
1017 1 : int bt_cap_handover_broadcast_to_unicast(
1018 : const struct bt_cap_handover_broadcast_to_unicast_param *param);
1019 :
1020 : /** Callback structure for CAP procedures */
1021 1 : struct bt_cap_commander_cb {
1022 : /**
1023 : * @brief Callback for bt_cap_initiator_unicast_discover().
1024 : *
1025 : * @param conn The connection pointer supplied to
1026 : * bt_cap_initiator_unicast_discover().
1027 : * @param err 0 if Common Audio Service was found else -ENODATA.
1028 : * @param member Pointer to the set member. NULL if err != 0.
1029 : * @param csis_inst The Coordinated Set Identification Service if
1030 : * Common Audio Service was found and includes a
1031 : * Coordinated Set Identification Service.
1032 : * NULL on error or if remote device does not include
1033 : * Coordinated Set Identification Service. NULL if err != 0.
1034 : */
1035 1 : void (*discovery_complete)(struct bt_conn *conn, int err,
1036 : const struct bt_csip_set_coordinator_set_member *member,
1037 : const struct bt_csip_set_coordinator_csis_inst *csis_inst);
1038 :
1039 : #if defined(CONFIG_BT_VCP_VOL_CTLR) || defined(__DOXYGEN__)
1040 : /**
1041 : * @brief Callback for bt_cap_commander_change_volume().
1042 : *
1043 : * @param conn Pointer to the connection where the error
1044 : * occurred. NULL if @p err is 0 or if cancelled by
1045 : * bt_cap_commander_cancel()
1046 : * @param err 0 on success, BT_GATT_ERR() with a
1047 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1048 : * by bt_cap_commander_cancel().
1049 : */
1050 1 : void (*volume_changed)(struct bt_conn *conn, int err);
1051 :
1052 : /**
1053 : * @brief Callback for bt_cap_commander_change_volume_mute_state().
1054 : *
1055 : * @param conn Pointer to the connection where the error
1056 : * occurred. NULL if @p err is 0 or if cancelled by
1057 : * bt_cap_commander_cancel()
1058 : * @param err 0 on success, BT_GATT_ERR() with a
1059 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1060 : * by bt_cap_commander_cancel().
1061 : */
1062 1 : void (*volume_mute_changed)(struct bt_conn *conn, int err);
1063 :
1064 : #if defined(CONFIG_BT_VCP_VOL_CTLR_VOCS) || defined(__DOXYGEN__)
1065 : /**
1066 : * @brief Callback for bt_cap_commander_change_volume_offset().
1067 : *
1068 : * @param conn Pointer to the connection where the error
1069 : * occurred. NULL if @p err is 0 or if cancelled by
1070 : * bt_cap_commander_cancel()
1071 : * @param err 0 on success, BT_GATT_ERR() with a
1072 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1073 : * by bt_cap_commander_cancel().
1074 : */
1075 1 : void (*volume_offset_changed)(struct bt_conn *conn, int err);
1076 : #endif /* CONFIG_BT_VCP_VOL_CTLR_VOCS */
1077 : #endif /* CONFIG_BT_VCP_VOL_CTLR */
1078 : #if defined(CONFIG_BT_MICP_MIC_CTLR) || defined(__DOXYGEN__)
1079 : /**
1080 : * @brief Callback for bt_cap_commander_change_microphone_mute_state().
1081 : *
1082 : * @param conn Pointer to the connection where the error
1083 : * occurred. NULL if @p err is 0 or if cancelled by
1084 : * bt_cap_commander_cancel()
1085 : * @param err 0 on success, BT_GATT_ERR() with a
1086 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1087 : * by bt_cap_commander_cancel().
1088 : */
1089 1 : void (*microphone_mute_changed)(struct bt_conn *conn, int err);
1090 : #if defined(CONFIG_BT_MICP_MIC_CTLR_AICS) || defined(__DOXYGEN__)
1091 : /**
1092 : * @brief Callback for bt_cap_commander_change_microphone_gain_setting().
1093 : *
1094 : * @param conn Pointer to the connection where the error
1095 : * occurred. NULL if @p err is 0 or if cancelled by
1096 : * bt_cap_commander_cancel()
1097 : * @param err 0 on success, BT_GATT_ERR() with a
1098 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1099 : * by bt_cap_commander_cancel().
1100 : */
1101 1 : void (*microphone_gain_changed)(struct bt_conn *conn, int err);
1102 : #endif /* CONFIG_BT_MICP_MIC_CTLR_AICS */
1103 : #endif /* CONFIG_BT_MICP_MIC_CTLR */
1104 :
1105 : #if defined(CONFIG_BT_BAP_BROADCAST_ASSISTANT) || defined(__DOXYGEN__)
1106 : /**
1107 : * @brief Callback for bt_cap_commander_broadcast_reception_start().
1108 : *
1109 : * @param conn Pointer to the connection where the error
1110 : * occurred. NULL if @p err is 0 or if cancelled by
1111 : * bt_cap_commander_cancel()
1112 : * @param err 0 on success, BT_GATT_ERR() with a
1113 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1114 : * by bt_cap_commander_cancel().
1115 : */
1116 1 : void (*broadcast_reception_start)(struct bt_conn *conn, int err);
1117 : /**
1118 : * @brief Callback for bt_cap_commander_broadcast_reception_stop().
1119 : *
1120 : * @param conn Pointer to the connection where the error
1121 : * occurred. NULL if @p err is 0 or if cancelled by
1122 : * bt_cap_commander_cancel()
1123 : * @param err 0 on success, BT_GATT_ERR() with a
1124 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1125 : * by bt_cap_commander_cancel().
1126 : */
1127 1 : void (*broadcast_reception_stop)(struct bt_conn *conn, int err);
1128 : /**
1129 : * @brief Callback for bt_cap_commander_distribute_broadcast_code().
1130 : *
1131 : * @param conn Pointer to the connection where the error
1132 : * occurred. NULL if @p err is 0 or if cancelled by
1133 : * bt_cap_commander_cancel()
1134 : * @param err 0 on success, BT_GATT_ERR() with a
1135 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1136 : * by bt_cap_commander_cancel().
1137 : */
1138 1 : void (*distribute_broadcast_code)(struct bt_conn *conn, int err);
1139 : #endif /* CONFIG_BT_BAP_BROADCAST_ASSISTANT */
1140 : };
1141 :
1142 : /**
1143 : * @brief Register Common Audio Profile Commander callbacks
1144 : *
1145 : * @param cb The callback structure. Shall remain static.
1146 : *
1147 : * @retval 0 Success
1148 : * @retval -EINVAL @p cb is NULL
1149 : * @retval -EALREADY Callbacks are already registered
1150 : */
1151 1 : int bt_cap_commander_register_cb(const struct bt_cap_commander_cb *cb);
1152 :
1153 : /**
1154 : * @brief Unregister Common Audio Profile Commander callbacks
1155 : *
1156 : * @param cb The callback structure that was previously registered.
1157 : *
1158 : * @retval 0 Success
1159 : * @retval -EINVAL @p cb is NULL or @p cb was not registered
1160 : */
1161 1 : int bt_cap_commander_unregister_cb(const struct bt_cap_commander_cb *cb);
1162 :
1163 : /**
1164 : * @brief Discovers audio support on a remote device.
1165 : *
1166 : * This will discover the Common Audio Service (CAS) on the remote device, to
1167 : * verify if the remote device supports the Common Audio Profile.
1168 : *
1169 : * @note @kconfig{CONFIG_BT_CAP_COMMANDER} must be enabled for this function. If
1170 : * @kconfig{CONFIG_BT_CAP_INITIATOR} is also enabled, it does not matter if
1171 : * bt_cap_commander_discover() or bt_cap_initiator_unicast_discover() is used.
1172 : *
1173 : * @param conn Connection to a remote server.
1174 : *
1175 : * @retval 0 Success
1176 : * @retval -EINVAL @p conn is NULL
1177 : * @retval -ENOTCONN @p conn is not connected
1178 : * @retval -ENOMEM Could not allocated memory for the request
1179 : * @retval -EBUSY Already doing discovery for @p conn
1180 : */
1181 1 : int bt_cap_commander_discover(struct bt_conn *conn);
1182 :
1183 : /**
1184 : * @brief Cancel any current Common Audio Profile commander procedure
1185 : *
1186 : * This will stop the current procedure from continuing and making it possible to run a new
1187 : * Common Audio Profile procedure.
1188 : *
1189 : * It is recommended to do this if any existing procedure takes longer time than expected, which
1190 : * could indicate a missing response from the Common Audio Profile Acceptor.
1191 : *
1192 : * This does not send any requests to any Common Audio Profile Acceptors involved with the
1193 : * current procedure, and thus notifications from the Common Audio Profile Acceptors may
1194 : * arrive after this has been called. It is thus recommended to either only use this if a
1195 : * procedure has stalled, or wait a short while before starting any new Common Audio Profile
1196 : * procedure after this has been called to avoid getting notifications from the cancelled
1197 : * procedure. The wait time depends on the connection interval, the number of devices in the
1198 : * previous procedure and the behavior of the Common Audio Profile Acceptors.
1199 : *
1200 : * The respective callbacks of the procedure will be called as part of this with the connection
1201 : * pointer set to NULL and the err value set to -ECANCELED.
1202 : *
1203 : * @retval 0 on success
1204 : * @retval -EALREADY if no procedure is active
1205 : */
1206 1 : int bt_cap_commander_cancel(void);
1207 :
1208 : /**
1209 : * Parameters part of @ref bt_cap_commander_broadcast_reception_start_param for
1210 : * bt_cap_commander_broadcast_reception_start()
1211 : */
1212 1 : struct bt_cap_commander_broadcast_reception_start_member_param {
1213 : /** Coordinated or ad-hoc set member. */
1214 1 : union bt_cap_set_member member;
1215 :
1216 : /** Address of the advertiser. */
1217 1 : bt_addr_le_t addr;
1218 :
1219 : /** SID of the advertising set. */
1220 1 : uint8_t adv_sid;
1221 :
1222 : /**
1223 : * @brief Periodic advertising interval in milliseconds.
1224 : *
1225 : * BT_BAP_PA_INTERVAL_UNKNOWN if unknown.
1226 : */
1227 1 : uint16_t pa_interval;
1228 :
1229 : /** 24-bit broadcast ID */
1230 1 : uint32_t broadcast_id;
1231 :
1232 : /**
1233 : * @brief Pointer to array of subgroups
1234 : *
1235 : * At least one bit in one of the subgroups bis_sync parameters shall be set.
1236 : */
1237 1 : struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS];
1238 :
1239 : /** Number of subgroups */
1240 1 : size_t num_subgroups;
1241 : };
1242 :
1243 : /** Parameters for starting broadcast reception */
1244 1 : struct bt_cap_commander_broadcast_reception_start_param {
1245 : /** The type of the set. */
1246 1 : enum bt_cap_set_type type;
1247 :
1248 : /** The set of devices for this procedure */
1249 1 : struct bt_cap_commander_broadcast_reception_start_member_param *param;
1250 :
1251 : /** The number of parameters in @p param */
1252 1 : size_t count;
1253 : };
1254 :
1255 : /**
1256 : * @brief Starts the reception of broadcast audio on one or more remote Common Audio Profile
1257 : * Acceptors
1258 : *
1259 : * @param param The parameters to start the broadcast audio
1260 : *
1261 : * @return 0 on success or negative error value on failure.
1262 : */
1263 1 : int bt_cap_commander_broadcast_reception_start(
1264 : const struct bt_cap_commander_broadcast_reception_start_param *param);
1265 :
1266 : /** Member parameters for stopping broadcast reception */
1267 1 : struct bt_cap_commander_broadcast_reception_stop_member_param {
1268 : /** Coordinated or ad-hoc set member. */
1269 1 : union bt_cap_set_member member;
1270 :
1271 : /** Source ID of the receive state. */
1272 1 : uint8_t src_id;
1273 :
1274 : /** Number of subgroups */
1275 1 : size_t num_subgroups;
1276 : };
1277 :
1278 : /** Parameters for stopping broadcast reception */
1279 1 : struct bt_cap_commander_broadcast_reception_stop_param {
1280 : /** The type of the set. */
1281 1 : enum bt_cap_set_type type;
1282 :
1283 : /** The set of devices for this procedure */
1284 1 : struct bt_cap_commander_broadcast_reception_stop_member_param *param;
1285 :
1286 : /** The number of parameters in @p param */
1287 1 : size_t count;
1288 : };
1289 :
1290 : /**
1291 : * @brief Stops the reception of broadcast audio on one or more remote Common Audio Profile
1292 : * Acceptors
1293 : *
1294 : * @param param The parameters to stop the broadcast audio
1295 : *
1296 : * @return 0 on success or negative error value on failure.
1297 : */
1298 1 : int bt_cap_commander_broadcast_reception_stop(
1299 : const struct bt_cap_commander_broadcast_reception_stop_param *param);
1300 :
1301 : /** Member parameters for distributing broadcast code */
1302 1 : struct bt_cap_commander_distribute_broadcast_code_member_param {
1303 : /** Coordinated or ad-hoc set member. */
1304 1 : union bt_cap_set_member member;
1305 :
1306 : /** Source ID of the receive state. */
1307 1 : uint8_t src_id;
1308 : };
1309 :
1310 : /** Parameters for distributing broadcast code */
1311 1 : struct bt_cap_commander_distribute_broadcast_code_param {
1312 : /** The type of the set. */
1313 1 : enum bt_cap_set_type type;
1314 :
1315 : /** The set of devices for this procedure */
1316 1 : struct bt_cap_commander_distribute_broadcast_code_member_param *param;
1317 :
1318 : /** The number of parameters in @p param */
1319 1 : size_t count;
1320 :
1321 : /**
1322 : * @brief 16-octet broadcast code.
1323 : *
1324 : * If the value is a string or a the value is less than 16 octets,
1325 : * the remaining octets shall be 0.
1326 : *
1327 : * Example:
1328 : * The string "Broadcast Code" shall be
1329 : * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
1330 : */
1331 1 : uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE];
1332 : };
1333 :
1334 : /**
1335 : * @brief Distributes the broadcast code on one or more remote Common Audio Profile
1336 : * Acceptors
1337 : *
1338 : * @param param The parameters for distributing the broadcast code
1339 : *
1340 : * @return 0 on success or negative error value on failure.
1341 : */
1342 1 : int bt_cap_commander_distribute_broadcast_code(
1343 : const struct bt_cap_commander_distribute_broadcast_code_param *param);
1344 :
1345 : /** Parameters for changing absolute volume */
1346 1 : struct bt_cap_commander_change_volume_param {
1347 : /** The type of the set. */
1348 1 : enum bt_cap_set_type type;
1349 :
1350 : /** Coordinated or ad-hoc set member. */
1351 1 : union bt_cap_set_member *members;
1352 :
1353 : /** The number of members in @p members */
1354 1 : size_t count;
1355 :
1356 : /** The absolute volume to set */
1357 1 : uint8_t volume;
1358 : };
1359 :
1360 : /**
1361 : * @brief Change the volume on one or more Common Audio Profile Acceptors
1362 : *
1363 : * @param param The parameters for the volume change
1364 : *
1365 : * @return 0 on success or negative error value on failure.
1366 : */
1367 1 : int bt_cap_commander_change_volume(const struct bt_cap_commander_change_volume_param *param);
1368 :
1369 : /**
1370 : * Parameters part of @ref bt_cap_commander_change_volume_offset_param for
1371 : * bt_cap_commander_change_volume_offset()
1372 : */
1373 1 : struct bt_cap_commander_change_volume_offset_member_param {
1374 : /** Coordinated or ad-hoc set member. */
1375 1 : union bt_cap_set_member member;
1376 :
1377 : /**
1378 : * @brief The offset to set
1379 : *
1380 : * Value shall be between @ref BT_VOCS_MIN_OFFSET and @ref BT_VOCS_MAX_OFFSET
1381 : */
1382 1 : int16_t offset;
1383 : };
1384 :
1385 : /** Parameters for changing volume offset */
1386 1 : struct bt_cap_commander_change_volume_offset_param {
1387 : /** The type of the set. */
1388 1 : enum bt_cap_set_type type;
1389 :
1390 : /** The set of devices for this procedure */
1391 1 : struct bt_cap_commander_change_volume_offset_member_param *param;
1392 :
1393 : /** The number of parameters in @p param */
1394 1 : size_t count;
1395 : };
1396 :
1397 : /**
1398 : * @brief Change the volume offset on one or more Common Audio Profile Acceptors
1399 : *
1400 : * @param param The parameters for the volume offset change
1401 : *
1402 : * @return 0 on success or negative error value on failure.
1403 : */
1404 1 : int bt_cap_commander_change_volume_offset(
1405 : const struct bt_cap_commander_change_volume_offset_param *param);
1406 :
1407 : /** Parameters for changing volume mute state */
1408 1 : struct bt_cap_commander_change_volume_mute_state_param {
1409 : /** The type of the set. */
1410 1 : enum bt_cap_set_type type;
1411 :
1412 : /** Coordinated or ad-hoc set member. */
1413 1 : union bt_cap_set_member *members;
1414 :
1415 : /** The number of members in @p members */
1416 1 : size_t count;
1417 :
1418 : /**
1419 : * @brief The volume mute state to set
1420 : *
1421 : * true to mute, and false to unmute
1422 : */
1423 1 : bool mute;
1424 : };
1425 :
1426 : /**
1427 : * @brief Change the volume mute state on one or more Common Audio Profile Acceptors
1428 : *
1429 : * @param param The parameters for the volume mute state change
1430 : *
1431 : * @return 0 on success or negative error value on failure.
1432 : */
1433 1 : int bt_cap_commander_change_volume_mute_state(
1434 : const struct bt_cap_commander_change_volume_mute_state_param *param);
1435 :
1436 : /** Parameters for changing microphone mute state */
1437 1 : struct bt_cap_commander_change_microphone_mute_state_param {
1438 : /** The type of the set. */
1439 1 : enum bt_cap_set_type type;
1440 :
1441 : /** Coordinated or ad-hoc set member. */
1442 1 : union bt_cap_set_member *members;
1443 :
1444 : /** The number of members in @p members */
1445 1 : size_t count;
1446 :
1447 : /**
1448 : * @brief The microphone mute state to set
1449 : *
1450 : * true to mute, and false to unmute
1451 : */
1452 1 : bool mute;
1453 : };
1454 :
1455 : /**
1456 : * @brief Change the microphone mute state on one or more Common Audio Profile Acceptors
1457 : *
1458 : * @param param The parameters for the microphone mute state change
1459 : *
1460 : * @return 0 on success or negative error value on failure.
1461 : */
1462 1 : int bt_cap_commander_change_microphone_mute_state(
1463 : const struct bt_cap_commander_change_microphone_mute_state_param *param);
1464 :
1465 : /**
1466 : * Parameters part of @ref bt_cap_commander_change_microphone_gain_setting_param for
1467 : * bt_cap_commander_change_microphone_gain_setting()
1468 : */
1469 1 : struct bt_cap_commander_change_microphone_gain_setting_member_param {
1470 : /** Coordinated or ad-hoc set member. */
1471 1 : union bt_cap_set_member member;
1472 :
1473 : /** @brief The microphone gain setting to set */
1474 1 : int8_t gain;
1475 : };
1476 :
1477 : /** Parameters for changing microphone mute state */
1478 1 : struct bt_cap_commander_change_microphone_gain_setting_param {
1479 : /** The type of the set. */
1480 1 : enum bt_cap_set_type type;
1481 :
1482 : /** The set of devices for this procedure */
1483 1 : struct bt_cap_commander_change_microphone_gain_setting_member_param *param;
1484 :
1485 : /** The number of parameters in @p param */
1486 1 : size_t count;
1487 : };
1488 :
1489 : /**
1490 : * @brief Change the microphone gain setting on one or more Common Audio Profile Acceptors
1491 : *
1492 : * @param param The parameters for the microphone gain setting change
1493 : *
1494 : * @return 0 on success or negative error value on failure.
1495 : */
1496 1 : int bt_cap_commander_change_microphone_gain_setting(
1497 : const struct bt_cap_commander_change_microphone_gain_setting_param *param);
1498 : #ifdef __cplusplus
1499 : }
1500 : #endif
1501 :
1502 : /**
1503 : * @}
1504 : */
1505 :
1506 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ */
|
