1 /* 2 * Copyright (c) 2022-2023 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ 8 #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ 9 10 /** 11 * @brief Common Audio Profile (CAP) 12 * 13 * @defgroup bt_cap Common Audio Profile (CAP) 14 * 15 * @ingroup bluetooth 16 * @{ 17 * 18 * [Experimental] Users should note that the APIs can change 19 * as a part of ongoing development. 20 */ 21 22 #include <stdint.h> 23 24 #include <zephyr/bluetooth/audio/csip.h> 25 #include <zephyr/bluetooth/iso.h> 26 #include <zephyr/bluetooth/audio/audio.h> 27 #include <zephyr/bluetooth/audio/bap.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** @brief Abstract Audio Broadcast Source structure. */ 34 struct bt_cap_broadcast_source; 35 36 /** 37 * @brief Register the Common Audio Service. 38 * 39 * This will register and enable the service and make it discoverable by 40 * clients. This will also register a Coordinated Set Identification 41 * Service instance. 42 * 43 * This shall only be done as a server, and requires 44 * @kconfig{BT_CAP_ACCEPTOR_SET_MEMBER}. If @kconfig{BT_CAP_ACCEPTOR_SET_MEMBER} 45 * is not enabled, the Common Audio Service will by statically registered. 46 * 47 * @param[in] param Coordinated Set Identification Service register 48 * parameters. 49 * @param[out] svc_inst Pointer to the registered Coordinated Set 50 * Identification Service. 51 * 52 * @return 0 if success, errno on failure. 53 */ 54 int bt_cap_acceptor_register(const struct bt_csip_set_member_register_param *param, 55 struct bt_csip_set_member_svc_inst **svc_inst); 56 57 /** Callback structure for CAP procedures */ 58 struct bt_cap_initiator_cb { 59 #if defined(CONFIG_BT_BAP_UNICAST_CLIENT) 60 /** 61 * @brief Callback for bt_cap_initiator_unicast_discover(). 62 * 63 * @param conn The connection pointer supplied to 64 * bt_cap_initiator_unicast_discover(). 65 * @param err 0 if Common Audio Service was found else -ENODATA. 66 * @param csis_inst The Coordinated Set Identification Service if 67 * Common Audio Service was found and includes a 68 * Coordinated Set Identification Service. 69 * NULL on error or if remote device does not include 70 * Coordinated Set Identification Service. 71 */ 72 void (*unicast_discovery_complete)( 73 struct bt_conn *conn, int err, 74 const struct bt_csip_set_coordinator_csis_inst *csis_inst); 75 76 /** 77 * @brief Callback for bt_cap_initiator_unicast_audio_start(). 78 * 79 * @param err 0 if success, BT_GATT_ERR() with a 80 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 81 * by bt_cap_initiator_unicast_audio_cancel(). 82 * @param conn Pointer to the connection where the error 83 * occurred. NULL if @p err is 0 or if cancelled by 84 * bt_cap_initiator_unicast_audio_cancel() 85 */ 86 void (*unicast_start_complete)(int err, struct bt_conn *conn); 87 88 /** 89 * @brief Callback for bt_cap_initiator_unicast_audio_update(). 90 * 91 * @param err 0 if success, BT_GATT_ERR() with a 92 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 93 * by bt_cap_initiator_unicast_audio_cancel(). 94 * @param conn Pointer to the connection where the error 95 * occurred. NULL if @p err is 0 or if cancelled by 96 * bt_cap_initiator_unicast_audio_cancel() 97 */ 98 void (*unicast_update_complete)(int err, struct bt_conn *conn); 99 100 /** 101 * @brief Callback for bt_cap_initiator_unicast_audio_stop(). 102 * 103 * @param err 0 if success, BT_GATT_ERR() with a 104 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 105 * by bt_cap_initiator_unicast_audio_cancel(). 106 * @param conn Pointer to the connection where the error 107 * occurred. NULL if @p err is 0 or if cancelled by 108 * bt_cap_initiator_unicast_audio_cancel() 109 */ 110 void (*unicast_stop_complete)(int err, struct bt_conn *conn); 111 #endif /* CONFIG_BT_BAP_UNICAST_CLIENT */ 112 }; 113 114 /** 115 * @brief Discovers audio support on a remote device. 116 * 117 * This will discover the Common Audio Service (CAS) on the remote device, to 118 * verify if the remote device supports the Common Audio Profile. 119 * 120 * @param conn Connection to a remote server. 121 * 122 * @retval 0 Success 123 * @retval -EINVAL @p conn is NULL 124 * @retval -ENOTCONN @p conn is not connected 125 * @retval -ENOMEM Could not allocated memory for the request 126 */ 127 int bt_cap_initiator_unicast_discover(struct bt_conn *conn); 128 129 /** Type of CAP set */ 130 enum bt_cap_set_type { 131 /** The set is an ad-hoc set */ 132 BT_CAP_SET_TYPE_AD_HOC, 133 /** The set is a CSIP Coordinated Set */ 134 BT_CAP_SET_TYPE_CSIP, 135 }; 136 137 /** Represents a Common Audio Set member that are either in a Coordinated or ad-hoc set */ 138 union bt_cap_set_member { 139 /** Connection pointer if the type is BT_CAP_SET_TYPE_AD_HOC. */ 140 struct bt_conn *member; 141 142 /** CSIP Coordinated Set struct used if type is BT_CAP_SET_TYPE_CSIP. */ 143 struct bt_csip_set_coordinator_csis_inst *csip; 144 }; 145 146 struct bt_cap_stream { 147 struct bt_bap_stream bap_stream; 148 struct bt_bap_stream_ops *ops; 149 }; 150 151 /** @brief Register Audio operations for a Common Audio Profile stream. 152 * 153 * Register Audio operations for a stream. 154 * 155 * @param stream Stream object. 156 * @param ops Stream operations structure. 157 */ 158 void bt_cap_stream_ops_register(struct bt_cap_stream *stream, struct bt_bap_stream_ops *ops); 159 160 /** 161 * @brief Send data to Common Audio Profile stream without timestamp 162 * 163 * See bt_bap_stream_send() for more information 164 * 165 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 166 * 167 * @param stream Stream object. 168 * @param buf Buffer containing data to be sent. 169 * @param seq_num Packet Sequence number. This value shall be incremented for each call to this 170 * function and at least once per SDU interval for a specific channel. 171 * 172 * @retval -EINVAL if stream object is NULL 173 * @retval Any return value from bt_bap_stream_send() 174 */ 175 int bt_cap_stream_send(struct bt_cap_stream *stream, struct net_buf *buf, uint16_t seq_num); 176 177 /** 178 * @brief Send data to Common Audio Profile stream with timestamp 179 * 180 * See bt_bap_stream_send() for more information 181 * 182 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 183 * 184 * @param stream Stream object. 185 * @param buf Buffer containing data to be sent. 186 * @param seq_num Packet Sequence number. This value shall be incremented for each call to this 187 * function and at least once per SDU interval for a specific channel. 188 * @param ts Timestamp of the SDU in microseconds (us). This value can be used to transmit 189 * multiple SDUs in the same SDU interval in a CIG or BIG. 190 * 191 * @retval -EINVAL if stream object is NULL 192 * @retval Any return value from bt_bap_stream_send() 193 */ 194 int bt_cap_stream_send_ts(struct bt_cap_stream *stream, struct net_buf *buf, uint16_t seq_num, 195 uint32_t ts); 196 197 /** 198 * @brief Get ISO transmission timing info for a Common Audio Profile stream 199 * 200 * See bt_bap_stream_get_tx_sync() for more information 201 * 202 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 203 * 204 * @param[in] stream Stream object. 205 * @param[out] info Transmit info object. 206 * 207 * @retval -EINVAL if stream object is NULL 208 * @retval Any return value from bt_bap_stream_get_tx_sync() 209 */ 210 int bt_cap_stream_get_tx_sync(struct bt_cap_stream *stream, struct bt_iso_tx_info *info); 211 212 /** Stream specific parameters for the bt_cap_initiator_unicast_audio_start() function */ 213 struct bt_cap_unicast_audio_start_stream_param { 214 /** Coordinated or ad-hoc set member. */ 215 union bt_cap_set_member member; 216 217 /** @brief Stream for the @p member */ 218 struct bt_cap_stream *stream; 219 220 /** Endpoint reference for the @p stream */ 221 struct bt_bap_ep *ep; 222 223 /** 224 * @brief Codec configuration. 225 * 226 * The @p codec_cfg.meta shall include a list of CCIDs 227 * (@ref BT_AUDIO_METADATA_TYPE_CCID_LIST) as well as a non-0 228 * stream context (@ref BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT) bitfield. 229 */ 230 struct bt_audio_codec_cfg *codec_cfg; 231 }; 232 233 /** Parameters for the bt_cap_initiator_unicast_audio_start() function */ 234 struct bt_cap_unicast_audio_start_param { 235 /** The type of the set. */ 236 enum bt_cap_set_type type; 237 238 /** The number of parameters in @p stream_params */ 239 size_t count; 240 241 /** Array of stream parameters */ 242 struct bt_cap_unicast_audio_start_stream_param *stream_params; 243 }; 244 245 /** Stream specific parameters for the bt_cap_initiator_unicast_audio_update() function */ 246 struct bt_cap_unicast_audio_update_stream_param { 247 /** Stream to update */ 248 struct bt_cap_stream *stream; 249 250 /** The length of @p meta. */ 251 size_t meta_len; 252 253 /** @brief The new metadata. 254 * 255 * The metadata shall a list of CCIDs as 256 * well as a non-0 context bitfield. 257 */ 258 uint8_t *meta; 259 }; 260 261 /** Parameters for the bt_cap_initiator_unicast_audio_update() function */ 262 struct bt_cap_unicast_audio_update_param { 263 /** The type of the set. */ 264 enum bt_cap_set_type type; 265 266 /** The number of parameters in @p stream_params */ 267 size_t count; 268 269 /** Array of stream parameters */ 270 struct bt_cap_unicast_audio_update_stream_param *stream_params; 271 }; 272 273 /** Parameters for the bt_cap_initiator_unicast_audio_stop() function */ 274 struct bt_cap_unicast_audio_stop_param { 275 /** The type of the set. */ 276 enum bt_cap_set_type type; 277 278 /** The number of streams in @p streams */ 279 size_t count; 280 281 /** Array of streams to stop */ 282 struct bt_cap_stream **streams; 283 }; 284 285 /** 286 * @brief Register Common Audio Profile Initiator callbacks 287 * 288 * @param cb The callback structure. Shall remain static. 289 * 290 * @return 0 on success or negative error value on failure. 291 */ 292 int bt_cap_initiator_register_cb(const struct bt_cap_initiator_cb *cb); 293 294 /** 295 * @brief Setup and start unicast audio streams for a set of devices. 296 * 297 * The result of this operation is that the streams in @p param will be 298 * initialized and will be usable for streaming audio data. 299 * The @p unicast_group value can be used to update and stop the streams. 300 * 301 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 302 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 303 * to be enabled. 304 * 305 * @param param Parameters to start the audio streams. 306 * 307 * @return 0 on success or negative error value on failure. 308 */ 309 int bt_cap_initiator_unicast_audio_start(const struct bt_cap_unicast_audio_start_param *param); 310 311 /** 312 * @brief Update unicast audio streams. 313 * 314 * This will update the metadata of one or more streams. 315 * 316 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 317 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 318 * to be enabled. 319 * 320 * @param param Update parameters. 321 * 322 * @return 0 on success or negative error value on failure. 323 */ 324 int bt_cap_initiator_unicast_audio_update(const struct bt_cap_unicast_audio_update_param *param); 325 326 /** 327 * @brief Stop unicast audio streams. 328 * 329 * This will stop one or more streams. 330 * 331 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 332 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 333 * to be enabled. 334 * 335 * @param param Stop parameters. 336 * 337 * @return 0 on success or negative error value on failure. 338 */ 339 int bt_cap_initiator_unicast_audio_stop(const struct bt_cap_unicast_audio_stop_param *param); 340 341 /** @brief Cancel any current Common Audio Profile procedure 342 * 343 * This will stop the current procedure from continuing and making it possible to run a new 344 * Common Audio Profile procedure. 345 * 346 * It is recommended to do this if any existing procedure takes longer time than expected, which 347 * could indicate a missing response from the Common Audio Profile Acceptor. 348 * 349 * This does not send any requests to any Common Audio Profile Acceptors involved with the current 350 * procedure, and thus notifications from the Common Audio Profile Acceptors may arrive after this 351 * has been called. It is thus recommended to either only use this if a procedure has stalled, or 352 * wait a short while before starting any new Common Audio Profile procedure after this has been 353 * called to avoid getting notifications from the cancelled procedure. The wait time depends on 354 * the connection interval, the number of devices in the previous procedure and the behavior of the 355 * Common Audio Profile Acceptors. 356 * 357 * The respective callbacks of the procedure will be called as part of this with the connection 358 * pointer set to 0 and the err value set to -ECANCELED. 359 * 360 * @retval 0 on success 361 * @retval -EALREADY if no procedure is active 362 */ 363 int bt_cap_initiator_unicast_audio_cancel(void); 364 365 struct bt_cap_initiator_broadcast_stream_param { 366 /** Audio stream */ 367 struct bt_cap_stream *stream; 368 369 /** The length of the %p data array. 370 * 371 * The BIS specific data may be omitted and this set to 0. 372 */ 373 size_t data_len; 374 375 /** BIS Codec Specific Configuration */ 376 uint8_t *data; 377 }; 378 379 struct bt_cap_initiator_broadcast_subgroup_param { 380 /** The number of parameters in @p stream_params */ 381 size_t stream_count; 382 383 /** Array of stream parameters */ 384 struct bt_cap_initiator_broadcast_stream_param *stream_params; 385 386 /** Subgroup Codec configuration. */ 387 struct bt_audio_codec_cfg *codec_cfg; 388 }; 389 390 struct bt_cap_initiator_broadcast_create_param { 391 /** The number of parameters in @p subgroup_params */ 392 size_t subgroup_count; 393 394 /** Array of stream parameters */ 395 struct bt_cap_initiator_broadcast_subgroup_param *subgroup_params; 396 397 /** Quality of Service configuration. */ 398 struct bt_audio_codec_qos *qos; 399 400 /** @brief Broadcast Source packing mode. 401 * 402 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED. 403 * 404 * @note This is a recommendation to the controller, which the 405 * controller may ignore. 406 */ 407 uint8_t packing; 408 409 /** Whether or not to encrypt the streams. */ 410 bool encryption; 411 412 /** 413 * @brief 16-octet broadcast code. 414 * 415 * Only valid if @p encrypt is true. 416 * 417 * If the value is a string or a the value is less than 16 octets, 418 * the remaining octets shall be 0. 419 * 420 * Example: 421 * The string "Broadcast Code" shall be 422 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 423 */ 424 uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE]; 425 426 #if defined(CONFIG_BT_ISO_TEST_PARAMS) 427 /** @brief Immediate Repetition Count 428 * 429 * The number of times the scheduled payloads are transmitted in a 430 * given event. 431 * 432 * Value range from @ref BT_ISO_MIN_IRC to @ref BT_ISO_MAX_IRC. 433 */ 434 uint8_t irc; 435 436 /** @brief Pre-transmission offset 437 * 438 * Offset used for pre-transmissions. 439 * 440 * Value range from @ref BT_ISO_MIN_PTO to @ref BT_ISO_MAX_PTO. 441 */ 442 uint8_t pto; 443 444 /** @brief ISO interval 445 * 446 * Time between consecutive BIS anchor points. 447 * 448 * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to 449 * @ref BT_ISO_ISO_INTERVAL_MAX. 450 */ 451 uint16_t iso_interval; 452 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 453 }; 454 455 /** 456 * @brief Create a Common Audio Profile broadcast source. 457 * 458 * Create a new audio broadcast source with one or more audio streams. 459 * 460 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 461 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 462 * to be enabled. 463 * 464 * @param[in] param Parameters to start the audio streams. 465 * @param[out] broadcast_source Pointer to the broadcast source created. 466 * 467 * @return 0 on success or negative error value on failure. 468 */ 469 int bt_cap_initiator_broadcast_audio_create( 470 const struct bt_cap_initiator_broadcast_create_param *param, 471 struct bt_cap_broadcast_source **broadcast_source); 472 473 /** 474 * @brief Start Common Audio Profile broadcast source. 475 * 476 * The broadcast source will be visible for scanners once this has been called, 477 * and the device will advertise audio announcements. 478 * 479 * This will allow the streams in the broadcast source to send audio by calling 480 * bt_bap_stream_send(). 481 * 482 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 483 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 484 * to be enabled. 485 * 486 * @param broadcast_source Pointer to the broadcast source. 487 * @param adv Pointer to an extended advertising set with 488 * periodic advertising configured. 489 * 490 * @return 0 on success or negative error value on failure. 491 */ 492 int bt_cap_initiator_broadcast_audio_start(struct bt_cap_broadcast_source *broadcast_source, 493 struct bt_le_ext_adv *adv); 494 /** 495 * @brief Update broadcast audio streams for a Common Audio Profile broadcast source. 496 * 497 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 498 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 499 * to be enabled. 500 * 501 * @param broadcast_source The broadcast source to update. 502 * @param meta The new metadata. The metadata shall contain a list 503 * of CCIDs as well as a non-0 context bitfield. 504 * @param meta_len The length of @p meta. 505 * 506 * @return 0 on success or negative error value on failure. 507 */ 508 int bt_cap_initiator_broadcast_audio_update(struct bt_cap_broadcast_source *broadcast_source, 509 const uint8_t meta[], size_t meta_len); 510 511 /** 512 * @brief Stop broadcast audio streams for a Common Audio Profile broadcast source. 513 * 514 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 515 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 516 * to be enabled. 517 * 518 * @param broadcast_source The broadcast source to stop. The audio streams 519 * in this will be stopped and reset. 520 * 521 * @return 0 on success or negative error value on failure. 522 */ 523 int bt_cap_initiator_broadcast_audio_stop(struct bt_cap_broadcast_source *broadcast_source); 524 525 /** 526 * @brief Delete Common Audio Profile broadcast source 527 * 528 * This can only be done after the broadcast source has been stopped by calling 529 * bt_cap_initiator_broadcast_audio_stop() and after the 530 * bt_bap_stream_ops.stopped() callback has been called for all streams in the 531 * broadcast source. 532 * 533 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 534 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 535 * to be enabled. 536 * 537 * @param broadcast_source The broadcast source to delete. 538 * The @p broadcast_source will be invalidated. 539 * 540 * @return 0 on success or negative error value on failure. 541 */ 542 int bt_cap_initiator_broadcast_audio_delete(struct bt_cap_broadcast_source *broadcast_source); 543 544 /** 545 * @brief Get the broadcast ID of a Common Audio Profile broadcast source 546 * 547 * This will return the 3-octet broadcast ID that should be advertised in the 548 * extended advertising data with @ref BT_UUID_BROADCAST_AUDIO_VAL as 549 * @ref BT_DATA_SVC_DATA16. 550 * 551 * See table 3.14 in the Basic Audio Profile v1.0.1 for the structure. 552 * 553 * @param[in] broadcast_source Pointer to the broadcast source. 554 * @param[out] broadcast_id Pointer to the 3-octet broadcast ID. 555 * 556 * @return int 0 if on success, errno on error. 557 */ 558 int bt_cap_initiator_broadcast_get_id(const struct bt_cap_broadcast_source *broadcast_source, 559 uint32_t *const broadcast_id); 560 561 /** 562 * @brief Get the Broadcast Audio Stream Endpoint of a Common Audio Profile broadcast source 563 * 564 * This will encode the BASE of a broadcast source into a buffer, that can be 565 * used for advertisement. The encoded BASE will thus be encoded as 566 * little-endian. The BASE shall be put into the periodic advertising data 567 * (see bt_le_per_adv_set_data()). 568 * 569 * See table 3.15 in the Basic Audio Profile v1.0.1 for the structure. 570 * 571 * @param broadcast_source Pointer to the broadcast source. 572 * @param base_buf Pointer to a buffer where the BASE will be inserted. 573 * 574 * @return int 0 if on success, errno on error. 575 */ 576 int bt_cap_initiator_broadcast_get_base(struct bt_cap_broadcast_source *broadcast_source, 577 struct net_buf_simple *base_buf); 578 579 struct bt_cap_unicast_to_broadcast_param { 580 /** The source unicast group with the streams. */ 581 struct bt_bap_unicast_group *unicast_group; 582 583 /** 584 * @brief Whether or not to encrypt the streams. 585 * 586 * If set to true, then the broadcast code in @p broadcast_code 587 * will be used to encrypt the streams. 588 */ 589 bool encrypt; 590 591 /** 592 * @brief 16-octet broadcast code. 593 * 594 * Only valid if @p encrypt is true. 595 * 596 * If the value is a string or a the value is less than 16 octets, 597 * the remaining octets shall be 0. 598 * 599 * Example: 600 * The string "Broadcast Code" shall be 601 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 602 */ 603 uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]; 604 }; 605 606 /** 607 * @brief Hands over the data streams in a unicast group to a broadcast source. 608 * 609 * The streams in the unicast group will be stopped and the unicast group 610 * will be deleted. This can only be done for source streams. 611 * 612 * @note @kconfig{CONFIG_BT_CAP_INITIATOR}, 613 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} and 614 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 615 * to be enabled. 616 * 617 * @param param The parameters for the handover. 618 * @param source The resulting broadcast source. 619 * 620 * @return 0 on success or negative error value on failure. 621 */ 622 int bt_cap_initiator_unicast_to_broadcast(const struct bt_cap_unicast_to_broadcast_param *param, 623 struct bt_cap_broadcast_source **source); 624 625 struct bt_cap_broadcast_to_unicast_param { 626 /** 627 * @brief The source broadcast source with the streams. 628 * 629 * The broadcast source will be stopped and deleted. 630 */ 631 struct bt_cap_broadcast_source *broadcast_source; 632 633 /** The type of the set. */ 634 enum bt_cap_set_type type; 635 636 /** 637 * @brief The number of set members in @p members. 638 * 639 * This value shall match the number of streams in the 640 * @p broadcast_source. 641 * 642 */ 643 size_t count; 644 645 /** Coordinated or ad-hoc set members. */ 646 union bt_cap_set_member **members; 647 }; 648 649 /** 650 * @brief Hands over the data streams in a broadcast source to a unicast group. 651 * 652 * The streams in the broadcast source will be stopped and the broadcast source 653 * will be deleted. 654 * 655 * @note @kconfig{CONFIG_BT_CAP_INITIATOR}, 656 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} and 657 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 658 * to be enabled. 659 * 660 * @param[in] param The parameters for the handover. 661 * @param[out] unicast_group The resulting broadcast source. 662 * 663 * @return 0 on success or negative error value on failure. 664 */ 665 int bt_cap_initiator_broadcast_to_unicast(const struct bt_cap_broadcast_to_unicast_param *param, 666 struct bt_bap_unicast_group **unicast_group); 667 668 /** Callback structure for CAP procedures */ 669 struct bt_cap_commander_cb { 670 /** 671 * @brief Callback for bt_cap_initiator_unicast_discover(). 672 * 673 * @param conn The connection pointer supplied to 674 * bt_cap_initiator_unicast_discover(). 675 * @param err 0 if Common Audio Service was found else -ENODATA. 676 * @param csis_inst The Coordinated Set Identification Service if 677 * Common Audio Service was found and includes a 678 * Coordinated Set Identification Service. 679 * NULL on error or if remote device does not include 680 * Coordinated Set Identification Service. 681 */ 682 void (*discovery_complete)(struct bt_conn *conn, int err, 683 const struct bt_csip_set_coordinator_csis_inst *csis_inst); 684 685 #if defined(CONFIG_BT_VCP_VOL_CTLR) 686 /** 687 * @brief Callback for bt_cap_commander_change_volume(). 688 * 689 * @param conn Pointer to the connection where the error 690 * occurred. NULL if @p err is 0 or if cancelled by 691 * bt_cap_commander_cancel() 692 * @param err 0 on success, BT_GATT_ERR() with a 693 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 694 * by bt_cap_commander_cancel(). 695 */ 696 void (*volume_changed)(struct bt_conn *conn, int err); 697 698 #if defined(CONFIG_BT_VCP_VOL_CTLR_VOCS) 699 /** 700 * @brief Callback for bt_cap_commander_change_volume_offset(). 701 * 702 * @param conn Pointer to the connection where the error 703 * occurred. NULL if @p err is 0 or if cancelled by 704 * bt_cap_initiator_unicast_audio_cancel() 705 * @param err 0 on success, BT_GATT_ERR() with a 706 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 707 * by bt_cap_initiator_unicast_audio_cancel(). 708 */ 709 void (*volume_offset_changed)(struct bt_conn *conn, int err); 710 #endif /* CONFIG_BT_VCP_VOL_CTLR_VOCS */ 711 #endif /* CONFIG_BT_VCP_VOL_CTLR */ 712 }; 713 714 /** 715 * @brief Register Common Audio Profile Commander callbacks 716 * 717 * @param cb The callback structure. Shall remain static. 718 * 719 * @retval 0 Success 720 * @retval -EINVAL @p cb is NULL 721 * @retval -EALREADY Callbacks are already registered 722 */ 723 int bt_cap_commander_register_cb(const struct bt_cap_commander_cb *cb); 724 725 /** 726 * @brief Unregister Common Audio Profile Commander callbacks 727 * 728 * @param cb The callback structure that was previously registered. 729 * 730 * @retval 0 Success 731 * @retval -EINVAL @p cb is NULL or @p cb was not registered 732 */ 733 int bt_cap_commander_unregister_cb(const struct bt_cap_commander_cb *cb); 734 735 /** 736 * @brief Discovers audio support on a remote device. 737 * 738 * This will discover the Common Audio Service (CAS) on the remote device, to 739 * verify if the remote device supports the Common Audio Profile. 740 * 741 * @note @kconfig{CONFIG_BT_CAP_COMMANDER} must be enabled for this function. If 742 * @kconfig{CONFIG_BT_CAP_INITIATOR} is also enabled, it does not matter if 743 * bt_cap_commander_discover() or bt_cap_initiator_unicast_discover() is used. 744 * 745 * @param conn Connection to a remote server. 746 * 747 * @retval 0 Success 748 * @retval -EINVAL @p conn is NULL 749 * @retval -ENOTCONN @p conn is not connected 750 * @retval -ENOMEM Could not allocated memory for the request 751 * @retval -EBUSY Already doing discovery for @p conn 752 */ 753 int bt_cap_commander_discover(struct bt_conn *conn); 754 755 /** @brief Cancel any current Common Audio Profile commander procedure 756 * 757 * This will stop the current procedure from continuing and making it possible to run a new 758 * Common Audio Profile procedure. 759 * 760 * It is recommended to do this if any existing procedure takes longer time than expected, which 761 * could indicate a missing response from the Common Audio Profile Acceptor. 762 * 763 * This does not send any requests to any Common Audio Profile Acceptors involved with the current 764 * procedure, and thus notifications from the Common Audio Profile Acceptors may arrive after this 765 * has been called. It is thus recommended to either only use this if a procedure has stalled, or 766 * wait a short while before starting any new Common Audio Profile procedure after this has been 767 * called to avoid getting notifications from the cancelled procedure. The wait time depends on 768 * the connection interval, the number of devices in the previous procedure and the behavior of the 769 * Common Audio Profile Acceptors. 770 * 771 * The respective callbacks of the procedure will be called as part of this with the connection 772 * pointer set to NULL and the err value set to -ECANCELED. 773 * 774 * @retval 0 on success 775 * @retval -EALREADY if no procedure is active 776 */ 777 int bt_cap_commander_cancel(void); 778 779 struct bt_cap_commander_broadcast_reception_start_member_param { 780 /** Coordinated or ad-hoc set member. */ 781 union bt_cap_set_member member; 782 783 /** Address of the advertiser. */ 784 bt_addr_le_t addr; 785 786 /** SID of the advertising set. */ 787 uint8_t adv_sid; 788 789 /** 790 * @brief Periodic advertising interval in milliseconds. 791 * 792 * BT_BAP_PA_INTERVAL_UNKNOWN if unknown. 793 */ 794 uint16_t pa_interval; 795 796 /** 24-bit broadcast ID */ 797 uint32_t broadcast_id; 798 799 /** 800 * @brief Pointer to array of subgroups 801 * 802 * At least one bit in one of the subgroups bis_sync parameters shall be set. 803 */ 804 struct bt_bap_bass_subgroup *subgroups; 805 806 /** Number of subgroups */ 807 size_t num_subgroups; 808 }; 809 810 /** Parameters for starting broadcast reception */ 811 struct bt_cap_commander_broadcast_reception_start_param { 812 /** The type of the set. */ 813 enum bt_cap_set_type type; 814 815 /** The set of devices for this procedure */ 816 struct bt_cap_commander_broadcast_reception_start_member_param *param; 817 818 /** The number of parameters in @p param */ 819 size_t count; 820 }; 821 822 /** 823 * @brief Starts the reception of broadcast audio on one or more remote Common Audio Profile 824 * Acceptors 825 * 826 * @param param The parameters to start the broadcast audio 827 * 828 * @return 0 on success or negative error value on failure. 829 */ 830 int bt_cap_commander_broadcast_reception_start( 831 const struct bt_cap_commander_broadcast_reception_start_param *param); 832 833 /** Parameters for stopping broadcast reception */ 834 struct bt_cap_commander_broadcast_reception_stop_param { 835 /** The type of the set. */ 836 enum bt_cap_set_type type; 837 838 /** Coordinated or ad-hoc set member. */ 839 union bt_cap_set_member *members; 840 841 /** The number of members in @p members */ 842 size_t count; 843 }; 844 845 /** 846 * @brief Stops the reception of broadcast audio on one or more remote Common Audio Profile 847 * Acceptors 848 * 849 * @param param The parameters to stop the broadcast audio 850 * 851 * @return 0 on success or negative error value on failure. 852 */ 853 int bt_cap_commander_broadcast_reception_stop( 854 const struct bt_cap_commander_broadcast_reception_stop_param *param); 855 856 /** Parameters for changing absolute volume */ 857 struct bt_cap_commander_change_volume_param { 858 /** The type of the set. */ 859 enum bt_cap_set_type type; 860 861 /** Coordinated or ad-hoc set member. */ 862 union bt_cap_set_member *members; 863 864 /** The number of members in @p members */ 865 size_t count; 866 867 /** The absolute volume to set */ 868 uint8_t volume; 869 }; 870 871 /** 872 * @brief Change the volume on one or more Common Audio Profile Acceptors 873 * 874 * @param param The parameters for the volume change 875 * 876 * @return 0 on success or negative error value on failure. 877 */ 878 int bt_cap_commander_change_volume(const struct bt_cap_commander_change_volume_param *param); 879 880 struct bt_cap_commander_change_volume_offset_member_param { 881 /** Coordinated or ad-hoc set member. */ 882 union bt_cap_set_member member; 883 884 /** 885 * @brief The offset to set 886 * 887 * Value shall be between @ref BT_VOCS_MIN_OFFSET and @ref BT_VOCS_MAX_OFFSET 888 */ 889 int16_t offset; 890 }; 891 892 /** Parameters for changing volume offset */ 893 struct bt_cap_commander_change_volume_offset_param { 894 /** The type of the set. */ 895 enum bt_cap_set_type type; 896 897 /** The set of devices for this procedure */ 898 struct bt_cap_commander_change_volume_offset_member_param *param; 899 900 /** The number of parameters in @p param */ 901 size_t count; 902 }; 903 904 /** 905 * @brief Change the volume offset on one or more Common Audio Profile Acceptors 906 * 907 * @param param The parameters for the volume offset change 908 * 909 * @return 0 on success or negative error value on failure. 910 */ 911 int bt_cap_commander_change_volume_offset( 912 const struct bt_cap_commander_change_volume_offset_param *param); 913 914 /** Parameters for changing volume mute state */ 915 struct bt_cap_commander_change_volume_mute_state_param { 916 /** The type of the set. */ 917 enum bt_cap_set_type type; 918 919 /** Coordinated or ad-hoc set member. */ 920 union bt_cap_set_member *members; 921 922 /** The number of members in @p members */ 923 size_t count; 924 925 /** 926 * @brief The volume mute state to set 927 * 928 * true to mute, and false to unmute 929 */ 930 bool mute; 931 }; 932 933 /** 934 * @brief Change the volume mute state on one or more Common Audio Profile Acceptors 935 * 936 * @param param The parameters for the volume mute state change 937 * 938 * @return 0 on success or negative error value on failure. 939 */ 940 int bt_cap_commander_change_volume_mute_state( 941 const struct bt_cap_commander_change_volume_mute_state_param *param); 942 943 /** Parameters for changing microphone mute state */ 944 struct bt_cap_commander_change_microphone_mute_state_param { 945 /** The type of the set. */ 946 enum bt_cap_set_type type; 947 948 /** Coordinated or ad-hoc set member. */ 949 union bt_cap_set_member *members; 950 951 /** The number of members in @p members */ 952 size_t count; 953 954 /** 955 * @brief The microphone mute state to set 956 * 957 * true to mute, and false to unmute 958 */ 959 bool mute; 960 }; 961 962 /** 963 * @brief Change the microphone mute state on one or more Common Audio Profile Acceptors 964 * 965 * @param param The parameters for the microphone mute state change 966 * 967 * @return 0 on success or negative error value on failure. 968 */ 969 int bt_cap_commander_change_microphone_mute_state( 970 const struct bt_cap_commander_change_microphone_mute_state_param *param); 971 972 struct bt_cap_commander_change_microphone_gain_setting_member_param { 973 /** Coordinated or ad-hoc set member. */ 974 union bt_cap_set_member member; 975 976 /** @brief The microphone gain setting to set */ 977 int8_t gain; 978 }; 979 980 /** Parameters for changing microphone mute state */ 981 struct bt_cap_commander_change_microphone_gain_setting_param { 982 /** The type of the set. */ 983 enum bt_cap_set_type type; 984 985 /** The set of devices for this procedure */ 986 struct bt_cap_commander_change_microphone_gain_setting_member_param *param; 987 988 /** The number of parameters in @p param */ 989 size_t count; 990 }; 991 992 /** 993 * @brief Change the microphone gain setting on one or more Common Audio Profile Acceptors 994 * 995 * @param param The parameters for the microphone gain setting change 996 * 997 * @return 0 on success or negative error value on failure. 998 */ 999 int bt_cap_commander_change_microphone_gain_setting( 1000 const struct bt_cap_commander_change_microphone_gain_setting_param *param); 1001 #ifdef __cplusplus 1002 } 1003 #endif 1004 1005 /** 1006 * @} 1007 */ 1008 1009 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ */ 1010
