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 : /**
909 : * @brief Register Common Audio Profile Handover callbacks
910 : *
911 : * @param cb The callback structure. Shall remain static.
912 : *
913 : * @return 0 on success or negative error value on failure.
914 : */
915 1 : int bt_cap_handover_register_cb(const struct bt_cap_handover_cb *cb);
916 :
917 : /**
918 : * @brief Unregister Common Audio Profile Handover callbacks
919 : *
920 : * @param cb The callback structure that was previously registered.
921 : *
922 : * @retval 0 Success
923 : * @retval -EINVAL @p cb is NULL or @p cb was not registered
924 : */
925 1 : int bt_cap_handover_unregister_cb(const struct bt_cap_handover_cb *cb);
926 :
927 : /**
928 : * @brief Hands over the sink streams in a unicast group to a broadcast source.
929 : *
930 : * All streams in the provided unicast group will be stopped and released. The sink streams will be
931 : * tranferred to a broadcast source, and the broadcast source information will be shared with
932 : * all accepters that are currently receiving audio. Any stream that is not in the streaming state
933 : * will only be released.
934 : *
935 : * bt_bap_broadcast_assistant_discover() must have been successfully perform for all members in @p
936 : * param before starting this procedure.
937 : *
938 : * @kconfig_dep{CONFIG_BT_CAP_HANDOVER}
939 : *
940 : * @param param The parameters for the handover.
941 : *
942 : * @return 0 on success or negative error value on failure.
943 : */
944 1 : int bt_cap_handover_unicast_to_broadcast(
945 : const struct bt_cap_handover_unicast_to_broadcast_param *param);
946 :
947 : /** Parameters for bt_cap_handover_broadcast_to_unicast() */
948 1 : struct bt_cap_handover_broadcast_to_unicast_param {
949 : /**
950 : * @brief The source broadcast source with the streams.
951 : *
952 : * The broadcast source will be stopped and deleted.
953 : */
954 1 : struct bt_cap_broadcast_source *broadcast_source;
955 :
956 : /** The type of the set. */
957 1 : enum bt_cap_set_type type;
958 :
959 : /**
960 : * @brief The number of set members in @p members.
961 : *
962 : * This value shall match the number of streams in the
963 : * @p broadcast_source.
964 : *
965 : */
966 1 : size_t count;
967 :
968 : /** Coordinated or ad-hoc set members. */
969 1 : union bt_cap_set_member **members;
970 : };
971 :
972 : /**
973 : * @brief Hands over the data streams in a broadcast source to a unicast group.
974 : *
975 : * The streams in the broadcast source will be stopped and the broadcast source
976 : * will be deleted.
977 : *
978 : * @kconfig_dep{CONFIG_BT_CAP_HANDOVER}
979 : *
980 : * @param[in] param The parameters for the handover.
981 : * @param[out] unicast_group The resulting broadcast source.
982 : *
983 : * @return 0 on success or negative error value on failure.
984 : */
985 1 : int bt_cap_handover_broadcast_to_unicast(
986 : const struct bt_cap_handover_broadcast_to_unicast_param *param,
987 : struct bt_bap_unicast_group **unicast_group);
988 :
989 : /** Callback structure for CAP procedures */
990 1 : struct bt_cap_commander_cb {
991 : /**
992 : * @brief Callback for bt_cap_initiator_unicast_discover().
993 : *
994 : * @param conn The connection pointer supplied to
995 : * bt_cap_initiator_unicast_discover().
996 : * @param err 0 if Common Audio Service was found else -ENODATA.
997 : * @param member Pointer to the set member. NULL if err != 0.
998 : * @param csis_inst The Coordinated Set Identification Service if
999 : * Common Audio Service was found and includes a
1000 : * Coordinated Set Identification Service.
1001 : * NULL on error or if remote device does not include
1002 : * Coordinated Set Identification Service. NULL if err != 0.
1003 : */
1004 1 : void (*discovery_complete)(struct bt_conn *conn, int err,
1005 : const struct bt_csip_set_coordinator_set_member *member,
1006 : const struct bt_csip_set_coordinator_csis_inst *csis_inst);
1007 :
1008 : #if defined(CONFIG_BT_VCP_VOL_CTLR) || defined(__DOXYGEN__)
1009 : /**
1010 : * @brief Callback for bt_cap_commander_change_volume().
1011 : *
1012 : * @param conn Pointer to the connection where the error
1013 : * occurred. NULL if @p err is 0 or if cancelled by
1014 : * bt_cap_commander_cancel()
1015 : * @param err 0 on success, BT_GATT_ERR() with a
1016 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1017 : * by bt_cap_commander_cancel().
1018 : */
1019 1 : void (*volume_changed)(struct bt_conn *conn, int err);
1020 :
1021 : /**
1022 : * @brief Callback for bt_cap_commander_change_volume_mute_state().
1023 : *
1024 : * @param conn Pointer to the connection where the error
1025 : * occurred. NULL if @p err is 0 or if cancelled by
1026 : * bt_cap_commander_cancel()
1027 : * @param err 0 on success, BT_GATT_ERR() with a
1028 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1029 : * by bt_cap_commander_cancel().
1030 : */
1031 1 : void (*volume_mute_changed)(struct bt_conn *conn, int err);
1032 :
1033 : #if defined(CONFIG_BT_VCP_VOL_CTLR_VOCS) || defined(__DOXYGEN__)
1034 : /**
1035 : * @brief Callback for bt_cap_commander_change_volume_offset().
1036 : *
1037 : * @param conn Pointer to the connection where the error
1038 : * occurred. NULL if @p err is 0 or if cancelled by
1039 : * bt_cap_commander_cancel()
1040 : * @param err 0 on success, BT_GATT_ERR() with a
1041 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1042 : * by bt_cap_commander_cancel().
1043 : */
1044 1 : void (*volume_offset_changed)(struct bt_conn *conn, int err);
1045 : #endif /* CONFIG_BT_VCP_VOL_CTLR_VOCS */
1046 : #endif /* CONFIG_BT_VCP_VOL_CTLR */
1047 : #if defined(CONFIG_BT_MICP_MIC_CTLR) || defined(__DOXYGEN__)
1048 : /**
1049 : * @brief Callback for bt_cap_commander_change_microphone_mute_state().
1050 : *
1051 : * @param conn Pointer to the connection where the error
1052 : * occurred. NULL if @p err is 0 or if cancelled by
1053 : * bt_cap_commander_cancel()
1054 : * @param err 0 on success, BT_GATT_ERR() with a
1055 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1056 : * by bt_cap_commander_cancel().
1057 : */
1058 1 : void (*microphone_mute_changed)(struct bt_conn *conn, int err);
1059 : #if defined(CONFIG_BT_MICP_MIC_CTLR_AICS) || defined(__DOXYGEN__)
1060 : /**
1061 : * @brief Callback for bt_cap_commander_change_microphone_gain_setting().
1062 : *
1063 : * @param conn Pointer to the connection where the error
1064 : * occurred. NULL if @p err is 0 or if cancelled by
1065 : * bt_cap_commander_cancel()
1066 : * @param err 0 on success, BT_GATT_ERR() with a
1067 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1068 : * by bt_cap_commander_cancel().
1069 : */
1070 1 : void (*microphone_gain_changed)(struct bt_conn *conn, int err);
1071 : #endif /* CONFIG_BT_MICP_MIC_CTLR_AICS */
1072 : #endif /* CONFIG_BT_MICP_MIC_CTLR */
1073 :
1074 : #if defined(CONFIG_BT_BAP_BROADCAST_ASSISTANT) || defined(__DOXYGEN__)
1075 : /**
1076 : * @brief Callback for bt_cap_commander_broadcast_reception_start().
1077 : *
1078 : * @param conn Pointer to the connection where the error
1079 : * occurred. NULL if @p err is 0 or if cancelled by
1080 : * bt_cap_commander_cancel()
1081 : * @param err 0 on success, BT_GATT_ERR() with a
1082 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1083 : * by bt_cap_commander_cancel().
1084 : */
1085 1 : void (*broadcast_reception_start)(struct bt_conn *conn, int err);
1086 : /**
1087 : * @brief Callback for bt_cap_commander_broadcast_reception_stop().
1088 : *
1089 : * @param conn Pointer to the connection where the error
1090 : * occurred. NULL if @p err is 0 or if cancelled by
1091 : * bt_cap_commander_cancel()
1092 : * @param err 0 on success, BT_GATT_ERR() with a
1093 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1094 : * by bt_cap_commander_cancel().
1095 : */
1096 1 : void (*broadcast_reception_stop)(struct bt_conn *conn, int err);
1097 : /**
1098 : * @brief Callback for bt_cap_commander_distribute_broadcast_code().
1099 : *
1100 : * @param conn Pointer to the connection where the error
1101 : * occurred. NULL if @p err is 0 or if cancelled by
1102 : * bt_cap_commander_cancel()
1103 : * @param err 0 on success, BT_GATT_ERR() with a
1104 : * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled
1105 : * by bt_cap_commander_cancel().
1106 : */
1107 1 : void (*distribute_broadcast_code)(struct bt_conn *conn, int err);
1108 : #endif /* CONFIG_BT_BAP_BROADCAST_ASSISTANT */
1109 : };
1110 :
1111 : /**
1112 : * @brief Register Common Audio Profile Commander callbacks
1113 : *
1114 : * @param cb The callback structure. Shall remain static.
1115 : *
1116 : * @retval 0 Success
1117 : * @retval -EINVAL @p cb is NULL
1118 : * @retval -EALREADY Callbacks are already registered
1119 : */
1120 1 : int bt_cap_commander_register_cb(const struct bt_cap_commander_cb *cb);
1121 :
1122 : /**
1123 : * @brief Unregister Common Audio Profile Commander callbacks
1124 : *
1125 : * @param cb The callback structure that was previously registered.
1126 : *
1127 : * @retval 0 Success
1128 : * @retval -EINVAL @p cb is NULL or @p cb was not registered
1129 : */
1130 1 : int bt_cap_commander_unregister_cb(const struct bt_cap_commander_cb *cb);
1131 :
1132 : /**
1133 : * @brief Discovers audio support on a remote device.
1134 : *
1135 : * This will discover the Common Audio Service (CAS) on the remote device, to
1136 : * verify if the remote device supports the Common Audio Profile.
1137 : *
1138 : * @note @kconfig{CONFIG_BT_CAP_COMMANDER} must be enabled for this function. If
1139 : * @kconfig{CONFIG_BT_CAP_INITIATOR} is also enabled, it does not matter if
1140 : * bt_cap_commander_discover() or bt_cap_initiator_unicast_discover() is used.
1141 : *
1142 : * @param conn Connection to a remote server.
1143 : *
1144 : * @retval 0 Success
1145 : * @retval -EINVAL @p conn is NULL
1146 : * @retval -ENOTCONN @p conn is not connected
1147 : * @retval -ENOMEM Could not allocated memory for the request
1148 : * @retval -EBUSY Already doing discovery for @p conn
1149 : */
1150 1 : int bt_cap_commander_discover(struct bt_conn *conn);
1151 :
1152 : /**
1153 : * @brief Cancel any current Common Audio Profile commander procedure
1154 : *
1155 : * This will stop the current procedure from continuing and making it possible to run a new
1156 : * Common Audio Profile procedure.
1157 : *
1158 : * It is recommended to do this if any existing procedure takes longer time than expected, which
1159 : * could indicate a missing response from the Common Audio Profile Acceptor.
1160 : *
1161 : * This does not send any requests to any Common Audio Profile Acceptors involved with the
1162 : * current procedure, and thus notifications from the Common Audio Profile Acceptors may
1163 : * arrive after this has been called. It is thus recommended to either only use this if a
1164 : * procedure has stalled, or wait a short while before starting any new Common Audio Profile
1165 : * procedure after this has been called to avoid getting notifications from the cancelled
1166 : * procedure. The wait time depends on the connection interval, the number of devices in the
1167 : * previous procedure and the behavior of the Common Audio Profile Acceptors.
1168 : *
1169 : * The respective callbacks of the procedure will be called as part of this with the connection
1170 : * pointer set to NULL and the err value set to -ECANCELED.
1171 : *
1172 : * @retval 0 on success
1173 : * @retval -EALREADY if no procedure is active
1174 : */
1175 1 : int bt_cap_commander_cancel(void);
1176 :
1177 : /**
1178 : * Parameters part of @ref bt_cap_commander_broadcast_reception_start_param for
1179 : * bt_cap_commander_broadcast_reception_start()
1180 : */
1181 1 : struct bt_cap_commander_broadcast_reception_start_member_param {
1182 : /** Coordinated or ad-hoc set member. */
1183 1 : union bt_cap_set_member member;
1184 :
1185 : /** Address of the advertiser. */
1186 1 : bt_addr_le_t addr;
1187 :
1188 : /** SID of the advertising set. */
1189 1 : uint8_t adv_sid;
1190 :
1191 : /**
1192 : * @brief Periodic advertising interval in milliseconds.
1193 : *
1194 : * BT_BAP_PA_INTERVAL_UNKNOWN if unknown.
1195 : */
1196 1 : uint16_t pa_interval;
1197 :
1198 : /** 24-bit broadcast ID */
1199 1 : uint32_t broadcast_id;
1200 :
1201 : /**
1202 : * @brief Pointer to array of subgroups
1203 : *
1204 : * At least one bit in one of the subgroups bis_sync parameters shall be set.
1205 : */
1206 1 : struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS];
1207 :
1208 : /** Number of subgroups */
1209 1 : size_t num_subgroups;
1210 : };
1211 :
1212 : /** Parameters for starting broadcast reception */
1213 1 : struct bt_cap_commander_broadcast_reception_start_param {
1214 : /** The type of the set. */
1215 1 : enum bt_cap_set_type type;
1216 :
1217 : /** The set of devices for this procedure */
1218 1 : struct bt_cap_commander_broadcast_reception_start_member_param *param;
1219 :
1220 : /** The number of parameters in @p param */
1221 1 : size_t count;
1222 : };
1223 :
1224 : /**
1225 : * @brief Starts the reception of broadcast audio on one or more remote Common Audio Profile
1226 : * Acceptors
1227 : *
1228 : * @param param The parameters to start the broadcast audio
1229 : *
1230 : * @return 0 on success or negative error value on failure.
1231 : */
1232 1 : int bt_cap_commander_broadcast_reception_start(
1233 : const struct bt_cap_commander_broadcast_reception_start_param *param);
1234 :
1235 : /** Member parameters for stopping broadcast reception */
1236 1 : struct bt_cap_commander_broadcast_reception_stop_member_param {
1237 : /** Coordinated or ad-hoc set member. */
1238 1 : union bt_cap_set_member member;
1239 :
1240 : /** Source ID of the receive state. */
1241 1 : uint8_t src_id;
1242 :
1243 : /** Number of subgroups */
1244 1 : size_t num_subgroups;
1245 : };
1246 :
1247 : /** Parameters for stopping broadcast reception */
1248 1 : struct bt_cap_commander_broadcast_reception_stop_param {
1249 : /** The type of the set. */
1250 1 : enum bt_cap_set_type type;
1251 :
1252 : /** The set of devices for this procedure */
1253 1 : struct bt_cap_commander_broadcast_reception_stop_member_param *param;
1254 :
1255 : /** The number of parameters in @p param */
1256 1 : size_t count;
1257 : };
1258 :
1259 : /**
1260 : * @brief Stops the reception of broadcast audio on one or more remote Common Audio Profile
1261 : * Acceptors
1262 : *
1263 : * @param param The parameters to stop the broadcast audio
1264 : *
1265 : * @return 0 on success or negative error value on failure.
1266 : */
1267 1 : int bt_cap_commander_broadcast_reception_stop(
1268 : const struct bt_cap_commander_broadcast_reception_stop_param *param);
1269 :
1270 : /** Member parameters for distributing broadcast code */
1271 1 : struct bt_cap_commander_distribute_broadcast_code_member_param {
1272 : /** Coordinated or ad-hoc set member. */
1273 1 : union bt_cap_set_member member;
1274 :
1275 : /** Source ID of the receive state. */
1276 1 : uint8_t src_id;
1277 : };
1278 :
1279 : /** Parameters for distributing broadcast code */
1280 1 : struct bt_cap_commander_distribute_broadcast_code_param {
1281 : /** The type of the set. */
1282 1 : enum bt_cap_set_type type;
1283 :
1284 : /** The set of devices for this procedure */
1285 1 : struct bt_cap_commander_distribute_broadcast_code_member_param *param;
1286 :
1287 : /** The number of parameters in @p param */
1288 1 : size_t count;
1289 :
1290 : /**
1291 : * @brief 16-octet broadcast code.
1292 : *
1293 : * If the value is a string or a the value is less than 16 octets,
1294 : * the remaining octets shall be 0.
1295 : *
1296 : * Example:
1297 : * The string "Broadcast Code" shall be
1298 : * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]
1299 : */
1300 1 : uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE];
1301 : };
1302 :
1303 : /**
1304 : * @brief Distributes the broadcast code on one or more remote Common Audio Profile
1305 : * Acceptors
1306 : *
1307 : * @param param The parameters for distributing the broadcast code
1308 : *
1309 : * @return 0 on success or negative error value on failure.
1310 : */
1311 1 : int bt_cap_commander_distribute_broadcast_code(
1312 : const struct bt_cap_commander_distribute_broadcast_code_param *param);
1313 :
1314 : /** Parameters for changing absolute volume */
1315 1 : struct bt_cap_commander_change_volume_param {
1316 : /** The type of the set. */
1317 1 : enum bt_cap_set_type type;
1318 :
1319 : /** Coordinated or ad-hoc set member. */
1320 1 : union bt_cap_set_member *members;
1321 :
1322 : /** The number of members in @p members */
1323 1 : size_t count;
1324 :
1325 : /** The absolute volume to set */
1326 1 : uint8_t volume;
1327 : };
1328 :
1329 : /**
1330 : * @brief Change the volume on one or more Common Audio Profile Acceptors
1331 : *
1332 : * @param param The parameters for the volume change
1333 : *
1334 : * @return 0 on success or negative error value on failure.
1335 : */
1336 1 : int bt_cap_commander_change_volume(const struct bt_cap_commander_change_volume_param *param);
1337 :
1338 : /**
1339 : * Parameters part of @ref bt_cap_commander_change_volume_offset_param for
1340 : * bt_cap_commander_change_volume_offset()
1341 : */
1342 1 : struct bt_cap_commander_change_volume_offset_member_param {
1343 : /** Coordinated or ad-hoc set member. */
1344 1 : union bt_cap_set_member member;
1345 :
1346 : /**
1347 : * @brief The offset to set
1348 : *
1349 : * Value shall be between @ref BT_VOCS_MIN_OFFSET and @ref BT_VOCS_MAX_OFFSET
1350 : */
1351 1 : int16_t offset;
1352 : };
1353 :
1354 : /** Parameters for changing volume offset */
1355 1 : struct bt_cap_commander_change_volume_offset_param {
1356 : /** The type of the set. */
1357 1 : enum bt_cap_set_type type;
1358 :
1359 : /** The set of devices for this procedure */
1360 1 : struct bt_cap_commander_change_volume_offset_member_param *param;
1361 :
1362 : /** The number of parameters in @p param */
1363 1 : size_t count;
1364 : };
1365 :
1366 : /**
1367 : * @brief Change the volume offset on one or more Common Audio Profile Acceptors
1368 : *
1369 : * @param param The parameters for the volume offset change
1370 : *
1371 : * @return 0 on success or negative error value on failure.
1372 : */
1373 1 : int bt_cap_commander_change_volume_offset(
1374 : const struct bt_cap_commander_change_volume_offset_param *param);
1375 :
1376 : /** Parameters for changing volume mute state */
1377 1 : struct bt_cap_commander_change_volume_mute_state_param {
1378 : /** The type of the set. */
1379 1 : enum bt_cap_set_type type;
1380 :
1381 : /** Coordinated or ad-hoc set member. */
1382 1 : union bt_cap_set_member *members;
1383 :
1384 : /** The number of members in @p members */
1385 1 : size_t count;
1386 :
1387 : /**
1388 : * @brief The volume mute state to set
1389 : *
1390 : * true to mute, and false to unmute
1391 : */
1392 1 : bool mute;
1393 : };
1394 :
1395 : /**
1396 : * @brief Change the volume mute state on one or more Common Audio Profile Acceptors
1397 : *
1398 : * @param param The parameters for the volume mute state change
1399 : *
1400 : * @return 0 on success or negative error value on failure.
1401 : */
1402 1 : int bt_cap_commander_change_volume_mute_state(
1403 : const struct bt_cap_commander_change_volume_mute_state_param *param);
1404 :
1405 : /** Parameters for changing microphone mute state */
1406 1 : struct bt_cap_commander_change_microphone_mute_state_param {
1407 : /** The type of the set. */
1408 1 : enum bt_cap_set_type type;
1409 :
1410 : /** Coordinated or ad-hoc set member. */
1411 1 : union bt_cap_set_member *members;
1412 :
1413 : /** The number of members in @p members */
1414 1 : size_t count;
1415 :
1416 : /**
1417 : * @brief The microphone mute state to set
1418 : *
1419 : * true to mute, and false to unmute
1420 : */
1421 1 : bool mute;
1422 : };
1423 :
1424 : /**
1425 : * @brief Change the microphone mute state on one or more Common Audio Profile Acceptors
1426 : *
1427 : * @param param The parameters for the microphone mute state change
1428 : *
1429 : * @return 0 on success or negative error value on failure.
1430 : */
1431 1 : int bt_cap_commander_change_microphone_mute_state(
1432 : const struct bt_cap_commander_change_microphone_mute_state_param *param);
1433 :
1434 : /**
1435 : * Parameters part of @ref bt_cap_commander_change_microphone_gain_setting_param for
1436 : * bt_cap_commander_change_microphone_gain_setting()
1437 : */
1438 1 : struct bt_cap_commander_change_microphone_gain_setting_member_param {
1439 : /** Coordinated or ad-hoc set member. */
1440 1 : union bt_cap_set_member member;
1441 :
1442 : /** @brief The microphone gain setting to set */
1443 1 : int8_t gain;
1444 : };
1445 :
1446 : /** Parameters for changing microphone mute state */
1447 1 : struct bt_cap_commander_change_microphone_gain_setting_param {
1448 : /** The type of the set. */
1449 1 : enum bt_cap_set_type type;
1450 :
1451 : /** The set of devices for this procedure */
1452 1 : struct bt_cap_commander_change_microphone_gain_setting_member_param *param;
1453 :
1454 : /** The number of parameters in @p param */
1455 1 : size_t count;
1456 : };
1457 :
1458 : /**
1459 : * @brief Change the microphone gain setting on one or more Common Audio Profile Acceptors
1460 : *
1461 : * @param param The parameters for the microphone gain setting change
1462 : *
1463 : * @return 0 on success or negative error value on failure.
1464 : */
1465 1 : int bt_cap_commander_change_microphone_gain_setting(
1466 : const struct bt_cap_commander_change_microphone_gain_setting_param *param);
1467 : #ifdef __cplusplus
1468 : }
1469 : #endif
1470 :
1471 : /**
1472 : * @}
1473 : */
1474 :
1475 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ */
|
