1 /** @file 2 * @brief Header for Bluetooth BAP. 3 * 4 * Copyright (c) 2020 Bose Corporation 5 * Copyright (c) 2021-2023 Nordic Semiconductor ASA 6 * 7 * SPDX-License-Identifier: Apache-2.0 8 */ 9 10 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_ 11 #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_ 12 13 /** 14 * @brief Bluetooth Basic Audio Profile (BAP) 15 * @defgroup bt_bap Bluetooth Basic Audio Profile 16 * @ingroup bluetooth 17 * @{ 18 */ 19 20 #include <zephyr/bluetooth/conn.h> 21 #include <zephyr/bluetooth/audio/audio.h> 22 23 #if defined(CONFIG_BT_BAP_SCAN_DELEGATOR) 24 #define BT_BAP_SCAN_DELEGATOR_MAX_METADATA_LEN CONFIG_BT_BAP_SCAN_DELEGATOR_MAX_METADATA_LEN 25 #define BT_BAP_SCAN_DELEGATOR_MAX_SUBGROUPS CONFIG_BT_BAP_SCAN_DELEGATOR_MAX_SUBGROUPS 26 #else 27 #define BT_BAP_SCAN_DELEGATOR_MAX_METADATA_LEN 0 28 #define BT_BAP_SCAN_DELEGATOR_MAX_SUBGROUPS 0 29 #endif 30 31 /** The minimum size of a Broadcast Audio Source Endpoint (BASE) 32 * 2 octets UUID 33 * 3 octets presentation delay 34 * 1 octet number of subgroups (which is minimum 1) 35 * 1 octet number of BIS (which is minimum 1) 36 * 5 octets codec_id 37 * 1 octet codec configuration length (which may be 0) 38 * 1 octet metadata length (which may be 0) 39 * 1 octet BIS index 40 * 1 octet BIS specific codec configuration length (which may be 0) 41 */ 42 #define BT_BAP_BASE_MIN_SIZE 16 43 44 /** The minimum size of a bt_bap_base_bis_data */ 45 #define BT_BAP_BASE_BIS_DATA_MIN_SIZE 2 /* index and length */ 46 47 /** Periodic advertising state reported by the Scan Delegator */ 48 enum bt_bap_pa_state { 49 /** The periodic advertising has not been synchronized */ 50 BT_BAP_PA_STATE_NOT_SYNCED = 0x00, 51 52 /** Waiting for SyncInfo from Broadcast Assistant */ 53 BT_BAP_PA_STATE_INFO_REQ = 0x01, 54 55 /** Synchronized to periodic advertising */ 56 BT_BAP_PA_STATE_SYNCED = 0x02, 57 58 /** Failed to synchronized to periodic advertising */ 59 BT_BAP_PA_STATE_FAILED = 0x03, 60 61 /** No periodic advertising sync transfer receiver from Broadcast Assistant */ 62 BT_BAP_PA_STATE_NO_PAST = 0x04, 63 }; 64 65 /** Broadcast Isochronous Group encryption state reported by the Scan Delegator */ 66 enum bt_bap_big_enc_state { 67 /** The Broadcast Isochronous Group not encrypted */ 68 BT_BAP_BIG_ENC_STATE_NO_ENC = 0x00, 69 70 /** The Broadcast Isochronous Group broadcast code requested */ 71 BT_BAP_BIG_ENC_STATE_BCODE_REQ = 0x01, 72 73 /** The Broadcast Isochronous Group decrypted */ 74 BT_BAP_BIG_ENC_STATE_DEC = 0x02, 75 76 /** The Broadcast Isochronous Group bad broadcast code */ 77 BT_BAP_BIG_ENC_STATE_BAD_CODE = 0x03, 78 }; 79 80 /** Broadcast Audio Scan Service (BASS) specific ATT error codes */ 81 enum bt_bap_bass_att_err { 82 /** Opcode not supported */ 83 BT_BAP_BASS_ERR_OPCODE_NOT_SUPPORTED = 0x80, 84 85 /** Invalid source ID supplied */ 86 BT_BAP_BASS_ERR_INVALID_SRC_ID = 0x81, 87 }; 88 89 /** Value indicating that the periodic advertising interval is unknown */ 90 #define BT_BAP_PA_INTERVAL_UNKNOWN 0xFFFF 91 92 /** @brief Broadcast Assistant no BIS sync preference 93 * 94 * Value indicating that the Broadcast Assistant has no preference to which BIS 95 * the Scan Delegator syncs to 96 */ 97 #define BT_BAP_BIS_SYNC_NO_PREF 0xFFFFFFFF 98 99 #if defined(CONFIG_BT_BAP_BROADCAST_SINK) 100 /* TODO: Since these are also used for the broadcast assistant, 101 * they should not be tied to the broadcast sink 102 */ 103 #define BROADCAST_SNK_STREAM_CNT CONFIG_BT_BAP_BROADCAST_SNK_STREAM_COUNT 104 #define BROADCAST_SNK_SUBGROUP_CNT CONFIG_BT_BAP_BROADCAST_SNK_SUBGROUP_COUNT 105 #else /* !CONFIG_BT_BAP_BROADCAST_SINK */ 106 #define BROADCAST_SNK_STREAM_CNT 0 107 #define BROADCAST_SNK_SUBGROUP_CNT 0 108 #endif /* CONFIG_BT_BAP_BROADCAST_SINK*/ 109 110 /** Endpoint states */ 111 enum bt_bap_ep_state { 112 /** Audio Stream Endpoint Idle state */ 113 BT_BAP_EP_STATE_IDLE = 0x00, 114 115 /** Audio Stream Endpoint Codec Configured state */ 116 BT_BAP_EP_STATE_CODEC_CONFIGURED = 0x01, 117 118 /** Audio Stream Endpoint QoS Configured state */ 119 BT_BAP_EP_STATE_QOS_CONFIGURED = 0x02, 120 121 /** Audio Stream Endpoint Enabling state */ 122 BT_BAP_EP_STATE_ENABLING = 0x03, 123 124 /** Audio Stream Endpoint Streaming state */ 125 BT_BAP_EP_STATE_STREAMING = 0x04, 126 127 /** Audio Stream Endpoint Disabling state */ 128 BT_BAP_EP_STATE_DISABLING = 0x05, 129 130 /** Audio Stream Endpoint Streaming state */ 131 BT_BAP_EP_STATE_RELEASING = 0x06, 132 }; 133 134 /** 135 * @brief Response Status Code 136 * 137 * These are sent by the server to the client when a stream operation is 138 * requested. 139 */ 140 enum bt_bap_ascs_rsp_code { 141 /** Server completed operation successfully */ 142 BT_BAP_ASCS_RSP_CODE_SUCCESS = 0x00, 143 /** Server did not support operation by client */ 144 BT_BAP_ASCS_RSP_CODE_NOT_SUPPORTED = 0x01, 145 /** Server rejected due to invalid operation length */ 146 BT_BAP_ASCS_RSP_CODE_INVALID_LENGTH = 0x02, 147 /** Invalid ASE ID */ 148 BT_BAP_ASCS_RSP_CODE_INVALID_ASE = 0x03, 149 /** Invalid ASE state */ 150 BT_BAP_ASCS_RSP_CODE_INVALID_ASE_STATE = 0x04, 151 /** Invalid operation for direction */ 152 BT_BAP_ASCS_RSP_CODE_INVALID_DIR = 0x05, 153 /** Capabilities not supported by server */ 154 BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED = 0x06, 155 /** Configuration parameters not supported by server */ 156 BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED = 0x07, 157 /** Configuration parameters rejected by server */ 158 BT_BAP_ASCS_RSP_CODE_CONF_REJECTED = 0x08, 159 /** Invalid Configuration parameters */ 160 BT_BAP_ASCS_RSP_CODE_CONF_INVALID = 0x09, 161 /** Unsupported metadata */ 162 BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED = 0x0a, 163 /** Metadata rejected by server */ 164 BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED = 0x0b, 165 /** Invalid metadata */ 166 BT_BAP_ASCS_RSP_CODE_METADATA_INVALID = 0x0c, 167 /** Server has insufficient resources */ 168 BT_BAP_ASCS_RSP_CODE_NO_MEM = 0x0d, 169 /** Unspecified error */ 170 BT_BAP_ASCS_RSP_CODE_UNSPECIFIED = 0x0e, 171 }; 172 173 /** 174 * @brief Response Reasons 175 * 176 * These are used if the @ref bt_bap_ascs_rsp_code value is 177 * @ref BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED, @ref BT_BAP_ASCS_RSP_CODE_CONF_REJECTED or 178 * @ref BT_BAP_ASCS_RSP_CODE_CONF_INVALID. 179 */ 180 enum bt_bap_ascs_reason { 181 /** No reason */ 182 BT_BAP_ASCS_REASON_NONE = 0x00, 183 /** Codec ID */ 184 BT_BAP_ASCS_REASON_CODEC = 0x01, 185 /** Codec configuration */ 186 BT_BAP_ASCS_REASON_CODEC_DATA = 0x02, 187 /** SDU interval */ 188 BT_BAP_ASCS_REASON_INTERVAL = 0x03, 189 /** Framing */ 190 BT_BAP_ASCS_REASON_FRAMING = 0x04, 191 /** PHY */ 192 BT_BAP_ASCS_REASON_PHY = 0x05, 193 /** Maximum SDU size*/ 194 BT_BAP_ASCS_REASON_SDU = 0x06, 195 /** RTN */ 196 BT_BAP_ASCS_REASON_RTN = 0x07, 197 /** Max transport latency */ 198 BT_BAP_ASCS_REASON_LATENCY = 0x08, 199 /** Presendation delay */ 200 BT_BAP_ASCS_REASON_PD = 0x09, 201 /** Invalid CIS mapping */ 202 BT_BAP_ASCS_REASON_CIS = 0x0a, 203 }; 204 205 /** @brief Structure storing values of fields of ASE Control Point notification. */ 206 struct bt_bap_ascs_rsp { 207 /** @brief Value of the Response Code field. */ 208 enum bt_bap_ascs_rsp_code code; 209 210 /** 211 * @brief Value of the Reason field. 212 * 213 * The meaning of this value depend on the Response Code field. 214 */ 215 union { 216 /** 217 * @brief Response reason 218 * 219 * If the Response Code is one of the following: 220 * - @ref BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED 221 * - @ref BT_BAP_ASCS_RSP_CODE_CONF_REJECTED 222 * - @ref BT_BAP_ASCS_RSP_CODE_CONF_INVALID 223 * all values from @ref bt_bap_ascs_reason can be used. 224 * 225 * If the Response Code is one of the following: 226 * - @ref BT_BAP_ASCS_RSP_CODE_SUCCESS 227 * - @ref BT_BAP_ASCS_RSP_CODE_NOT_SUPPORTED 228 * - @ref BT_BAP_ASCS_RSP_CODE_INVALID_LENGTH 229 * - @ref BT_BAP_ASCS_RSP_CODE_INVALID_ASE 230 * - @ref BT_BAP_ASCS_RSP_CODE_INVALID_ASE_STATE 231 * - @ref BT_BAP_ASCS_RSP_CODE_INVALID_DIR 232 * - @ref BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED 233 * - @ref BT_BAP_ASCS_RSP_CODE_NO_MEM 234 * - @ref BT_BAP_ASCS_RSP_CODE_UNSPECIFIED 235 * only value @ref BT_BAP_ASCS_REASON_NONE shall be used. 236 */ 237 enum bt_bap_ascs_reason reason; 238 239 /** 240 * @brief Response metadata type 241 * 242 * If the Response Code is one of the following: 243 * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED 244 * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED 245 * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_INVALID 246 * the value of the Metadata Type shall be used. 247 */ 248 enum bt_audio_metadata_type metadata_type; 249 }; 250 }; 251 252 /** 253 * @brief Macro used to initialise the object storing values of ASE Control Point notification. 254 * 255 * @param c Response Code field 256 * @param r Reason field - @ref bt_bap_ascs_reason or @ref bt_audio_metadata_type (see notes in 257 * @ref bt_bap_ascs_rsp). 258 */ 259 #define BT_BAP_ASCS_RSP(c, r) (struct bt_bap_ascs_rsp) { .code = c, .reason = r } 260 261 /** @brief Abstract Audio Broadcast Source structure. */ 262 struct bt_bap_broadcast_source; 263 264 /** @brief Abstract Audio Broadcast Sink structure. */ 265 struct bt_bap_broadcast_sink; 266 267 /** @brief Abstract Audio Unicast Group structure. */ 268 struct bt_bap_unicast_group; 269 270 /** @brief Abstract Audio Endpoint structure. */ 271 struct bt_bap_ep; 272 273 /* TODO: Replace with struct bt_bap_base_subgroup */ 274 /** Struct to hold subgroup specific information for the receive state */ 275 struct bt_bap_scan_delegator_subgroup { 276 /** BIS synced bitfield */ 277 uint32_t bis_sync; 278 279 /** Length of the metadata */ 280 uint8_t metadata_len; 281 282 /** The metadata */ 283 uint8_t metadata[BT_BAP_SCAN_DELEGATOR_MAX_METADATA_LEN]; 284 }; 285 286 /** Represents the Broadcast Audio Scan Service receive state */ 287 struct bt_bap_scan_delegator_recv_state { 288 /** The source ID */ 289 uint8_t src_id; 290 291 /** The Bluetooth address */ 292 bt_addr_le_t addr; 293 294 /** The advertising set ID*/ 295 uint8_t adv_sid; 296 297 /** The periodic adverting sync state */ 298 enum bt_bap_pa_state pa_sync_state; 299 300 /** The broadcast isochronous group encryption state */ 301 enum bt_bap_big_enc_state encrypt_state; 302 303 /** The 24-bit broadcast ID */ 304 uint32_t broadcast_id; 305 306 /** @brief The bad broadcast code 307 * 308 * Only valid if encrypt_state is @ref BT_BAP_BIG_ENC_STATE_BCODE_REQ 309 */ 310 uint8_t bad_code[BT_AUDIO_BROADCAST_CODE_SIZE]; 311 312 /** Number of subgroups */ 313 uint8_t num_subgroups; 314 315 /** Subgroup specific information */ 316 struct bt_bap_scan_delegator_subgroup subgroups[BT_BAP_SCAN_DELEGATOR_MAX_SUBGROUPS]; 317 }; 318 319 struct bt_bap_scan_delegator_cb { 320 /** 321 * @brief Receive state updated 322 * 323 * @param conn Pointer to the connection to a remote device if 324 * the change was caused by it, otherwise NULL. 325 * @param recv_state Pointer to the receive state that was updated. 326 * 327 * @return 0 in case of success or negative value in case of error. 328 */ 329 void (*recv_state_updated)(struct bt_conn *conn, 330 const struct bt_bap_scan_delegator_recv_state *recv_state); 331 332 /** 333 * @brief Periodic advertising sync request 334 * 335 * Request from peer device to synchronize with the periodic advertiser 336 * denoted by the @p recv_state. To notify the Broadcast Assistant about 337 * any pending sync 338 * 339 * @param[in] conn Pointer to the connection requesting the 340 * periodic advertising sync. 341 * @param[in] recv_state Pointer to the receive state that is being 342 * requested for periodic advertising sync. 343 * @param[in] past_avail True if periodic advertising sync transfer is 344 * available. 345 * @param[in] pa_interval The periodic advertising interval. 346 * @param[out] past_sync Set to true if syncing via periodic 347 * advertising sync transfer, false otherwise. 348 * If @p past_avail is false, this value is 349 * ignored. 350 * 351 * @return 0 in case of accept, or other value to reject. 352 */ 353 int (*pa_sync_req)(struct bt_conn *conn, 354 const struct bt_bap_scan_delegator_recv_state *recv_state, 355 bool past_avail, uint16_t pa_interval); 356 357 /** 358 * @brief Periodic advertising sync termination request 359 * 360 * Request from peer device to terminate the periodic advertiser sync 361 * denoted by the @p recv_state. 362 * 363 * @param conn Pointer to the connection requesting the periodic 364 * advertising sync termination. 365 * @param recv_state Pointer to the receive state that is being 366 * requested for periodic advertising sync. 367 * 368 * @return 0 in case of success or negative value in case of error. 369 */ 370 int (*pa_sync_term_req)(struct bt_conn *conn, 371 const struct bt_bap_scan_delegator_recv_state *recv_state); 372 373 /** 374 * @brief Broadcast code received 375 * 376 * Broadcast code received from a broadcast assistant 377 * 378 * @param conn Pointer to the connection providing the 379 * broadcast code. 380 * @param recv_state Pointer to the receive state the broadcast code 381 * is being provided for. 382 * @param broadcast_code The 16-octet broadcast code 383 */ 384 void (*broadcast_code)(struct bt_conn *conn, 385 const struct bt_bap_scan_delegator_recv_state *recv_state, 386 const uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE]); 387 388 /** 389 * @brief Broadcast Isochronous Stream synchronize request 390 * 391 * Request from Broadcast Assistant device to modify the Broadcast 392 * Isochronous Stream states. The request shall be fulfilled with 393 * accordance to the @p bis_sync_req within reasonable time. The 394 * Broadcast Assistant may also request fewer, or none, indexes to 395 * be synchronized. 396 * 397 * @param[in] conn Pointer to the connection of the 398 * Broadcast Assistant requesting the sync. 399 * @param[in] recv_state Pointer to the receive state that is being 400 * requested for the sync. 401 * @param[in] bis_sync_req Array of bitfields of which BIS indexes 402 * that is requested to sync for each subgroup 403 * by the Broadcast Assistant. 404 * 405 * @return 0 in case of accept, or other value to reject. 406 */ 407 int (*bis_sync_req)(struct bt_conn *conn, 408 const struct bt_bap_scan_delegator_recv_state *recv_state, 409 const uint32_t bis_sync_req[BT_BAP_SCAN_DELEGATOR_MAX_SUBGROUPS]); 410 }; 411 412 /** Structure holding information of audio stream endpoint */ 413 struct bt_bap_ep_info { 414 /** The ID of the endpoint */ 415 uint8_t id; 416 417 /** The state of the endpoint */ 418 enum bt_bap_ep_state state; 419 420 /** Capabilities type */ 421 enum bt_audio_dir dir; 422 423 /** Pointer to paired endpoint if the endpoint is part of a bidirectional CIS, 424 * otherwise NULL 425 */ 426 struct bt_bap_ep *paired_ep; 427 }; 428 429 /** 430 * @brief Return structure holding information of audio stream endpoint 431 * 432 * @param ep The audio stream endpoint object. 433 * @param info The structure object to be filled with the info. 434 * 435 * @return 0 in case of success or negative value in case of error. 436 */ 437 int bt_bap_ep_get_info(const struct bt_bap_ep *ep, struct bt_bap_ep_info *info); 438 439 /** 440 * @brief Basic Audio Profile stream structure. 441 * 442 * Streams represents a stream configuration of a Remote Endpoint and a Local Capability. 443 * 444 * @note Streams are unidirectional but can be paired with other streams to use a bidirectional 445 * connected isochronous stream. 446 */ 447 struct bt_bap_stream { 448 /** Stream direction */ 449 enum bt_audio_dir dir; 450 451 /** Connection reference */ 452 struct bt_conn *conn; 453 454 /** Endpoint reference */ 455 struct bt_bap_ep *ep; 456 457 /** Codec Configuration */ 458 struct bt_codec *codec; 459 460 /** QoS Configuration */ 461 struct bt_codec_qos *qos; 462 463 /** Audio stream operations */ 464 struct bt_bap_stream_ops *ops; 465 466 #if defined(CONFIG_BT_BAP_UNICAST_CLIENT) 467 /** 468 * @brief Audio ISO reference 469 * 470 * This is only used for Unicast Client streams, and is handled internally. 471 */ 472 struct bt_bap_iso *bap_iso; 473 #endif /* CONFIG_BT_BAP_UNICAST_CLIENT */ 474 475 /** Unicast or Broadcast group - Used internally */ 476 void *group; 477 478 /** Stream user data */ 479 void *user_data; 480 481 /* Internally used list node */ 482 sys_snode_t _node; 483 }; 484 485 /** @brief Stream operation. */ 486 struct bt_bap_stream_ops { 487 #if defined(CONFIG_BT_BAP_UNICAST) 488 /** 489 * @brief Stream configured callback 490 * 491 * Configured callback is called whenever an Audio Stream has been configured. 492 * 493 * @param stream Stream object that has been configured. 494 * @param pref Remote QoS preferences. 495 */ 496 void (*configured)(struct bt_bap_stream *stream, const struct bt_codec_qos_pref *pref); 497 498 /** 499 * @brief Stream QoS set callback 500 * 501 * QoS set callback is called whenever an Audio Stream Quality of Service has been set or 502 * updated. 503 * 504 * @param stream Stream object that had its QoS updated. 505 */ 506 void (*qos_set)(struct bt_bap_stream *stream); 507 508 /** 509 * @brief Stream enabled callback 510 * 511 * Enabled callback is called whenever an Audio Stream has been enabled. 512 * 513 * @param stream Stream object that has been enabled. 514 */ 515 void (*enabled)(struct bt_bap_stream *stream); 516 517 /** 518 * @brief Stream metadata updated callback 519 * 520 * Metadata Updated callback is called whenever an Audio Stream's metadata has been 521 * updated. 522 * 523 * @param stream Stream object that had its metadata updated. 524 */ 525 void (*metadata_updated)(struct bt_bap_stream *stream); 526 527 /** 528 * @brief Stream disabled callback 529 * 530 * Disabled callback is called whenever an Audio Stream has been disabled. 531 * 532 * @param stream Stream object that has been disabled. 533 */ 534 void (*disabled)(struct bt_bap_stream *stream); 535 536 /** 537 * @brief Stream released callback 538 * 539 * Released callback is called whenever a Audio Stream has been released and can be 540 * deallocated. 541 * 542 * @param stream Stream object that has been released. 543 */ 544 void (*released)(struct bt_bap_stream *stream); 545 #endif /* CONFIG_BT_BAP_UNICAST */ 546 547 /** 548 * @brief Stream started callback 549 * 550 * Started callback is called whenever an Audio Stream has been started 551 * and will be usable for streaming. 552 * 553 * @param stream Stream object that has been started. 554 */ 555 void (*started)(struct bt_bap_stream *stream); 556 557 /** 558 * @brief Stream stopped callback 559 * 560 * Stopped callback is called whenever an Audio Stream has been stopped. 561 * 562 * @param stream Stream object that has been stopped. 563 * @param reason BT_HCI_ERR_* reason for the disconnection. 564 */ 565 void (*stopped)(struct bt_bap_stream *stream, uint8_t reason); 566 567 #if defined(CONFIG_BT_AUDIO_RX) 568 /** 569 * @brief Stream audio HCI receive callback. 570 * 571 * This callback is only used if the ISO data path is HCI. 572 * 573 * @param stream Stream object. 574 * @param info Pointer to the metadata for the buffer. The lifetime of the pointer is 575 * linked to the lifetime of the net_buf. Metadata such as sequence number and 576 * timestamp can be provided by the bluetooth controller. 577 * @param buf Buffer containing incoming audio data. 578 */ 579 void (*recv)(struct bt_bap_stream *stream, const struct bt_iso_recv_info *info, 580 struct net_buf *buf); 581 #endif /* CONFIG_BT_AUDIO_RX */ 582 583 #if defined(CONFIG_BT_AUDIO_TX) 584 /** 585 * @brief Stream audio HCI sent callback 586 * 587 * If this callback is provided it will be called whenever a SDU has been completely sent, 588 * or otherwise flushed due to transmission issues. 589 * 590 * This callback is only used if the ISO data path is HCI. 591 * 592 * @param chan The channel which has sent data. 593 */ 594 void (*sent)(struct bt_bap_stream *stream); 595 #endif /* CONFIG_BT_AUDIO_TX */ 596 }; 597 598 /** 599 * @brief Register Audio callbacks for a stream. 600 * 601 * Register Audio callbacks for a stream. 602 * 603 * @param stream Stream object. 604 * @param ops Stream operations structure. 605 */ 606 void bt_bap_stream_cb_register(struct bt_bap_stream *stream, struct bt_bap_stream_ops *ops); 607 608 /** 609 * @brief Configure Audio Stream 610 * 611 * This procedure is used by a client to configure a new stream using the 612 * remote endpoint, local capability and codec configuration. 613 * 614 * @param conn Connection object 615 * @param stream Stream object being configured 616 * @param ep Remote Audio Endpoint being configured 617 * @param codec Codec configuration 618 * 619 * @return Allocated Audio Stream object or NULL in case of error. 620 */ 621 int bt_bap_stream_config(struct bt_conn *conn, struct bt_bap_stream *stream, struct bt_bap_ep *ep, 622 struct bt_codec *codec); 623 624 /** 625 * @brief Reconfigure Audio Stream 626 * 627 * This procedure is used by a unicast client or unicast server to reconfigure 628 * a stream to use a different local codec configuration. 629 * 630 * This can only be done for unicast streams. 631 * 632 * @param stream Stream object being reconfigured 633 * @param codec Codec configuration 634 * 635 * @return 0 in case of success or negative value in case of error. 636 */ 637 int bt_bap_stream_reconfig(struct bt_bap_stream *stream, struct bt_codec *codec); 638 639 /** 640 * @brief Configure Audio Stream QoS 641 * 642 * This procedure is used by a client to configure the Quality of Service of streams in a unicast 643 * group. All streams in the group for the specified @p conn will have the Quality of Service 644 * configured. This shall only be used to configure unicast streams. 645 * 646 * @param conn Connection object 647 * @param group Unicast group object 648 * 649 * @return 0 in case of success or negative value in case of error. 650 */ 651 int bt_bap_stream_qos(struct bt_conn *conn, struct bt_bap_unicast_group *group); 652 653 /** 654 * @brief Enable Audio Stream 655 * 656 * This procedure is used by a client to enable a stream. 657 * 658 * This shall only be called for unicast streams, as broadcast streams will always be enabled once 659 * created. 660 * 661 * @param stream Stream object 662 * @param meta_count Number of metadata entries 663 * @param meta Metadata entries 664 * 665 * @return 0 in case of success or negative value in case of error. 666 */ 667 int bt_bap_stream_enable(struct bt_bap_stream *stream, struct bt_codec_data *meta, 668 size_t meta_count); 669 670 /** 671 * @brief Change Audio Stream Metadata 672 * 673 * This procedure is used by a unicast client or unicast server to change the metadata of a stream. 674 * 675 * @param stream Stream object 676 * @param meta_count Number of metadata entries 677 * @param meta Metadata entries 678 * 679 * @return 0 in case of success or negative value in case of error. 680 */ 681 int bt_bap_stream_metadata(struct bt_bap_stream *stream, struct bt_codec_data *meta, 682 size_t meta_count); 683 684 /** 685 * @brief Disable Audio Stream 686 * 687 * This procedure is used by a unicast client or unicast server to disable a stream. 688 * 689 * This shall only be called for unicast streams, as broadcast streams will 690 * always be enabled once created. 691 * 692 * @param stream Stream object 693 * 694 * @return 0 in case of success or negative value in case of error. 695 */ 696 int bt_bap_stream_disable(struct bt_bap_stream *stream); 697 698 /** 699 * @brief Start Audio Stream 700 * 701 * This procedure is used by a unicast client or unicast server to make a stream start streaming. 702 * 703 * For the unicast client, this will connect the CIS for the stream before 704 * sending the start command. 705 * 706 * For the unicast server, this will put a @ref BT_AUDIO_DIR_SINK stream into the streaming state if 707 * the CIS is connected (initialized by the unicast client). If the CIS is not connected yet, the 708 * stream will go into the streaming state as soon as the CIS is connected. 709 * @ref BT_AUDIO_DIR_SOURCE streams will go into the streaming state when the unicast client sends 710 * the Receiver Start Ready operation, which will trigger the @ref bt_bap_unicast_server_cb.start() 711 * callback. 712 * 713 * This shall only be called for unicast streams. 714 * 715 * Broadcast sinks will always be started once synchronized, and broadcast 716 * source streams shall be started with bt_bap_broadcast_source_start(). 717 * 718 * @param stream Stream object 719 * 720 * @return 0 in case of success or negative value in case of error. 721 */ 722 int bt_bap_stream_start(struct bt_bap_stream *stream); 723 724 /** 725 * @brief Stop Audio Stream 726 * 727 * This procedure is used by a client to make a stream stop streaming. 728 * 729 * This shall only be called for unicast streams. 730 * Broadcast sinks cannot be stopped. 731 * Broadcast sources shall be stopped with bt_bap_broadcast_source_stop(). 732 * 733 * @param stream Stream object 734 * 735 * @return 0 in case of success or negative value in case of error. 736 */ 737 int bt_bap_stream_stop(struct bt_bap_stream *stream); 738 739 /** 740 * @brief Release Audio Stream 741 * 742 * This procedure is used by a unicast client or unicast server to release a unicast stream. 743 * 744 * Broadcast sink streams cannot be released, but can be deleted by bt_bap_broadcast_sink_delete(). 745 * Broadcast source streams cannot be released, but can be deleted by 746 * bt_bap_broadcast_source_delete(). 747 * 748 * @param stream Stream object 749 * 750 * @return 0 in case of success or negative value in case of error. 751 */ 752 int bt_bap_stream_release(struct bt_bap_stream *stream); 753 754 /** 755 * @brief Send data to Audio stream 756 * 757 * Send data from buffer to the stream. 758 * 759 * @note Data will not be sent to linked streams since linking is only 760 * consider for procedures affecting the state machine. 761 * 762 * @param stream Stream object. 763 * @param buf Buffer containing data to be sent. 764 * @param seq_num Packet Sequence number. This value shall be incremented for each call to this 765 * function and at least once per SDU interval for a specific channel. 766 * @param ts Timestamp of the SDU in microseconds (us). This value can be used to transmit 767 * multiple SDUs in the same SDU interval in a CIG or BIG. Can be omitted by using 768 * @ref BT_ISO_TIMESTAMP_NONE which will simply enqueue the ISO SDU in a FIFO 769 * manner. 770 * 771 * @return Bytes sent in case of success or negative value in case of error. 772 */ 773 int bt_bap_stream_send(struct bt_bap_stream *stream, struct net_buf *buf, uint16_t seq_num, 774 uint32_t ts); 775 776 /** 777 * @defgroup bt_bap_unicast_server BAP Unicast Server APIs 778 * @ingroup bt_bap 779 * @{ 780 */ 781 782 /** Unicast Server callback structure */ 783 struct bt_bap_unicast_server_cb { 784 /** 785 * @brief Endpoint config request callback 786 * 787 * Config callback is called whenever an endpoint is requested to be 788 * configured 789 * 790 * @param[in] conn Connection object. 791 * @param[in] ep Local Audio Endpoint being configured. 792 * @param[in] dir Direction of the endpoint. 793 * @param[in] codec Codec configuration. 794 * @param[out] stream Pointer to stream that will be configured for the endpoint. 795 * @param[out] pref Pointer to a QoS preference object that shall be populated with 796 * values. Invalid values will reject the codec configuration request. 797 * @param[out] rsp Object for the ASE operation response. Only used if the return 798 * value is non-zero. 799 * 800 * @return 0 in case of success or negative value in case of error. 801 */ 802 int (*config)(struct bt_conn *conn, const struct bt_bap_ep *ep, enum bt_audio_dir dir, 803 const struct bt_codec *codec, struct bt_bap_stream **stream, 804 struct bt_codec_qos_pref *const pref, struct bt_bap_ascs_rsp *rsp); 805 806 /** 807 * @brief Stream reconfig request callback 808 * 809 * Reconfig callback is called whenever an Audio Stream needs to be 810 * reconfigured with different codec configuration. 811 * 812 * @param[in] stream Stream object being reconfigured. 813 * @param[in] dir Direction of the endpoint. 814 * @param[in] codec Codec configuration. 815 * @param[out] pref Pointer to a QoS preference object that shall be populated with 816 * values. Invalid values will reject the codec configuration request. 817 * @param[out] rsp Object for the ASE operation response. Only used if the return 818 * value is non-zero. 819 * 820 * @return 0 in case of success or negative value in case of error. 821 */ 822 int (*reconfig)(struct bt_bap_stream *stream, enum bt_audio_dir dir, 823 const struct bt_codec *codec, struct bt_codec_qos_pref *const pref, 824 struct bt_bap_ascs_rsp *rsp); 825 826 /** 827 * @brief Stream QoS request callback 828 * 829 * QoS callback is called whenever an Audio Stream Quality of 830 * Service needs to be configured. 831 * 832 * @param[in] stream Stream object being reconfigured. 833 * @param[in] qos Quality of Service configuration. 834 * @param[out] rsp Object for the ASE operation response. Only used if the return 835 * value is non-zero. 836 * 837 * @return 0 in case of success or negative value in case of error. 838 */ 839 int (*qos)(struct bt_bap_stream *stream, const struct bt_codec_qos *qos, 840 struct bt_bap_ascs_rsp *rsp); 841 842 /** 843 * @brief Stream Enable request callback 844 * 845 * Enable callback is called whenever an Audio Stream is requested to be enabled to stream. 846 * 847 * @param[in] stream Stream object being enabled. 848 * @param[in] meta Metadata entries 849 * @param[in] meta_count Number of metadata entries 850 * @param[out] rsp Object for the ASE operation response. Only used if the return 851 * value is non-zero. 852 * 853 * @return 0 in case of success or negative value in case of error. 854 */ 855 int (*enable)(struct bt_bap_stream *stream, const struct bt_codec_data *meta, 856 size_t meta_count, struct bt_bap_ascs_rsp *rsp); 857 858 /** 859 * @brief Stream Start request callback 860 * 861 * Start callback is called whenever an Audio Stream is requested to start streaming. 862 * 863 * @param[in] stream Stream object. 864 * @param[out] rsp Object for the ASE operation response. Only used if the return 865 * value is non-zero. 866 * 867 * @return 0 in case of success or negative value in case of error. 868 */ 869 int (*start)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp); 870 871 /** 872 * @brief Stream Metadata update request callback 873 * 874 * Metadata callback is called whenever an Audio Stream is requested to update its metadata. 875 * 876 * @param[in] stream Stream object. 877 * @param[in] meta Metadata entries 878 * @param[in] meta_count Number of metadata entries 879 * @param[out] rsp Object for the ASE operation response. Only used if the return 880 * value is non-zero. 881 * 882 * @return 0 in case of success or negative value in case of error. 883 */ 884 int (*metadata)(struct bt_bap_stream *stream, const struct bt_codec_data *meta, 885 size_t meta_count, struct bt_bap_ascs_rsp *rsp); 886 887 /** 888 * @brief Stream Disable request callback 889 * 890 * Disable callback is called whenever an Audio Stream is requested to disable the stream. 891 * 892 * @param[in] stream Stream object being disabled. 893 * @param[out] rsp Object for the ASE operation response. Only used if the return 894 * value is non-zero. 895 * 896 * @return 0 in case of success or negative value in case of error. 897 */ 898 int (*disable)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp); 899 900 /** 901 * @brief Stream Stop callback 902 * 903 * Stop callback is called whenever an Audio Stream is requested to stop streaming. 904 * 905 * @param[in] stream Stream object. 906 * @param[out] rsp Object for the ASE operation response. Only used if the return 907 * value is non-zero. 908 * 909 * @return 0 in case of success or negative value in case of error. 910 */ 911 int (*stop)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp); 912 913 /** 914 * @brief Stream release callback 915 * 916 * Release callback is called whenever a new Audio Stream needs to be released and thus 917 * deallocated. 918 * 919 * @param[in] stream Stream object. 920 * @param[out] rsp Object for the ASE operation response. Only used if the return 921 * value is non-zero. 922 * 923 * @return 0 in case of success or negative value in case of error. 924 */ 925 int (*release)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp); 926 }; 927 928 /** 929 * @brief Register unicast server callbacks. 930 * 931 * Only one callback structure can be registered, and attempting to 932 * registering more than one will result in an error. 933 * 934 * @param cb Unicast server callback structure. 935 * 936 * @return 0 in case of success or negative value in case of error. 937 */ 938 int bt_bap_unicast_server_register_cb(const struct bt_bap_unicast_server_cb *cb); 939 940 /** 941 * @brief Unregister unicast server callbacks. 942 * 943 * May only unregister a callback structure that has previously been 944 * registered by bt_bap_unicast_server_register_cb(). 945 * 946 * @param cb Unicast server callback structure. 947 * 948 * @return 0 in case of success or negative value in case of error. 949 */ 950 int bt_bap_unicast_server_unregister_cb(const struct bt_bap_unicast_server_cb *cb); 951 952 /** 953 * @typedef bt_bap_ep_func_t 954 * @brief The callback function called for each endpoint. 955 * 956 * @param ep The structure object with endpoint info. 957 * @param user_data Data to pass to the function. 958 */ 959 typedef void (*bt_bap_ep_func_t)(struct bt_bap_ep *ep, void *user_data); 960 961 /** 962 * @brief Iterate through all endpoints of the given connection. 963 * 964 * @param conn Connection object 965 * @param func Function to call for each endpoint. 966 * @param user_data Data to pass to the callback function. 967 */ 968 void bt_bap_unicast_server_foreach_ep(struct bt_conn *conn, bt_bap_ep_func_t func, void *user_data); 969 970 /** 971 * @brief Initialize and configure a new ASE. 972 * 973 * @param conn Connection object 974 * @param stream Configured stream object to be attached to the ASE 975 * @param codec Codec configuration 976 * @param qos_pref Audio Stream Quality of Service Preference 977 * 978 * @return 0 in case of success or negative value in case of error. 979 */ 980 int bt_bap_unicast_server_config_ase(struct bt_conn *conn, struct bt_bap_stream *stream, 981 struct bt_codec *codec, 982 const struct bt_codec_qos_pref *qos_pref); 983 984 /** @} */ /* End of group bt_bap_unicast_server */ 985 986 /** 987 * @defgroup bt_bap_unicast_client BAP Unicast Client APIs 988 * @ingroup bt_bap 989 * @{ 990 */ 991 992 /** Parameter struct for each stream in the unicast group */ 993 struct bt_bap_unicast_group_stream_param { 994 /** Pointer to a stream object. */ 995 struct bt_bap_stream *stream; 996 997 /** The QoS settings for the stream object. */ 998 struct bt_codec_qos *qos; 999 }; 1000 1001 /** @brief Parameter struct for the unicast group functions 1002 * 1003 * Parameter struct for the bt_bap_unicast_group_create() and 1004 * bt_bap_unicast_group_add_streams() functions. 1005 */ 1006 struct bt_bap_unicast_group_stream_pair_param { 1007 /** Pointer to a receiving stream parameters. */ 1008 struct bt_bap_unicast_group_stream_param *rx_param; 1009 1010 /** Pointer to a transmiting stream parameters. */ 1011 struct bt_bap_unicast_group_stream_param *tx_param; 1012 }; 1013 1014 struct bt_bap_unicast_group_param { 1015 /** The number of parameters in @p params */ 1016 size_t params_count; 1017 1018 /** Array of stream parameters */ 1019 struct bt_bap_unicast_group_stream_pair_param *params; 1020 1021 /** @brief Unicast Group packing mode. 1022 * 1023 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED. 1024 * 1025 * @note This is a recommendation to the controller, which the controller may ignore. 1026 */ 1027 uint8_t packing; 1028 }; 1029 1030 /** 1031 * @brief Create audio unicast group. 1032 * 1033 * Create a new audio unicast group with one or more audio streams as a unicast client. Streams in 1034 * a unicast group shall share the same interval, framing and latency (see @ref bt_codec_qos). 1035 * 1036 * @param[in] param The unicast group create parameters. 1037 * @param[out] unicast_group Pointer to the unicast group created. 1038 * 1039 * @return Zero on success or (negative) error code otherwise. 1040 */ 1041 int bt_bap_unicast_group_create(struct bt_bap_unicast_group_param *param, 1042 struct bt_bap_unicast_group **unicast_group); 1043 1044 /** 1045 * @brief Add streams to a unicast group as a unicast client 1046 * 1047 * This function can be used to add additional streams to a bt_bap_unicast_group. 1048 * 1049 * This can be called at any time before any of the streams in the group has been started 1050 * (see bt_bap_stream_ops.started()). 1051 * This can also be called after the streams have been stopped (see bt_bap_stream_ops.stopped()). 1052 * 1053 * Once a stream has been added to a unicast group, it cannot be removed. To remove a stream from a 1054 * group, the group must be deleted with bt_bap_unicast_group_delete(), but this will require all 1055 * streams in the group to be released first. 1056 * 1057 * @param unicast_group Pointer to the unicast group 1058 * @param params Array of stream parameters with streams being added to the group. 1059 * @param num_param Number of paramers in @p params. 1060 * 1061 * @return 0 in case of success or negative value in case of error. 1062 */ 1063 int bt_bap_unicast_group_add_streams(struct bt_bap_unicast_group *unicast_group, 1064 struct bt_bap_unicast_group_stream_pair_param params[], 1065 size_t num_param); 1066 1067 /** 1068 * @brief Delete audio unicast group. 1069 * 1070 * Delete a audio unicast group as a client. All streams in the group shall 1071 * be in the idle or configured state. 1072 * 1073 * @param unicast_group Pointer to the unicast group to delete 1074 * 1075 * @return Zero on success or (negative) error code otherwise. 1076 */ 1077 int bt_bap_unicast_group_delete(struct bt_bap_unicast_group *unicast_group); 1078 1079 /** Unicast Client callback structure */ 1080 struct bt_bap_unicast_client_cb { 1081 /** 1082 * @brief Remote Unicast Server Audio Locations 1083 * 1084 * This callback is called whenever the audio locations is read from 1085 * the server or otherwise notified to the client. 1086 * 1087 * @param conn Connection to the remote unicast server. 1088 * @param dir Direction of the location. 1089 * @param loc The location bitfield value. 1090 * 1091 * @return 0 in case of success or negative value in case of error. 1092 */ 1093 void (*location)(struct bt_conn *conn, enum bt_audio_dir dir, enum bt_audio_location loc); 1094 1095 /** 1096 * @brief Remote Unicast Server Available Contexts 1097 * 1098 * This callback is called whenever the available contexts are read 1099 * from the server or otherwise notified to the client. 1100 * 1101 * @param conn Connection to the remote unicast server. 1102 * @param snk_ctx The sink context bitfield value. 1103 * @param src_ctx The source context bitfield value. 1104 * 1105 * @return 0 in case of success or negative value in case of error. 1106 */ 1107 void (*available_contexts)(struct bt_conn *conn, enum bt_audio_context snk_ctx, 1108 enum bt_audio_context src_ctx); 1109 1110 /** 1111 * @brief Callback function for bt_bap_stream_config() and bt_bap_stream_reconfig(). 1112 * 1113 * Called when the codec configure operation is completed on the server. 1114 * 1115 * @param stream Stream the operation was performed on. 1116 * @param rsp_code Response code. 1117 * @param reason Reason code. 1118 */ 1119 void (*config)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1120 enum bt_bap_ascs_reason reason); 1121 1122 /** 1123 * @brief Callback function for bt_bap_stream_qos(). 1124 * 1125 * Called when the QoS configure operation is completed on the server. 1126 * This will be called for each stream in the group that was being QoS 1127 * configured. 1128 * 1129 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1130 * associated with the ASE ID sent by the server. 1131 * @param rsp_code Response code. 1132 * @param reason Reason code. 1133 */ 1134 void (*qos)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1135 enum bt_bap_ascs_reason reason); 1136 1137 /** 1138 * @brief Callback function for bt_bap_stream_enable(). 1139 * 1140 * Called when the enable operation is completed on the server. 1141 * 1142 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1143 * associated with the ASE ID sent by the server. 1144 * @param rsp_code Response code. 1145 * @param reason Reason code. 1146 */ 1147 void (*enable)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1148 enum bt_bap_ascs_reason reason); 1149 1150 /** 1151 * @brief Callback function for bt_bap_stream_start(). 1152 * 1153 * Called when the start operation is completed on the server. This will 1154 * only be called if the stream supplied to bt_bap_stream_start() is 1155 * for a @ref BT_AUDIO_DIR_SOURCE endpoint. 1156 * 1157 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1158 * associated with the ASE ID sent by the server. 1159 * @param rsp_code Response code. 1160 * @param reason Reason code. 1161 */ 1162 void (*start)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1163 enum bt_bap_ascs_reason reason); 1164 1165 /** 1166 * @brief Callback function for bt_bap_stream_stop(). 1167 * 1168 * Called when the stop operation is completed on the server. This will 1169 * only be called if the stream supplied to bt_bap_stream_stop() is 1170 * for a @ref BT_AUDIO_DIR_SOURCE endpoint. 1171 * 1172 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1173 * associated with the ASE ID sent by the server. 1174 * @param rsp_code Response code. 1175 * @param reason Reason code. 1176 */ 1177 void (*stop)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1178 enum bt_bap_ascs_reason reason); 1179 1180 /** 1181 * @brief Callback function for bt_bap_stream_disable(). 1182 * 1183 * Called when the disable operation is completed on the server. 1184 * 1185 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1186 * associated with the ASE ID sent by the server. 1187 * @param rsp_code Response code. 1188 * @param reason Reason code. 1189 */ 1190 void (*disable)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1191 enum bt_bap_ascs_reason reason); 1192 1193 /** 1194 * @brief Callback function for bt_bap_stream_metadata(). 1195 * 1196 * Called when the metadata operation is completed on the server. 1197 * 1198 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1199 * associated with the ASE ID sent by the server. 1200 * @param rsp_code Response code. 1201 * @param reason Reason code. 1202 */ 1203 void (*metadata)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1204 enum bt_bap_ascs_reason reason); 1205 1206 /** 1207 * @brief Callback function for bt_bap_stream_release(). 1208 * 1209 * Called when the release operation is completed on the server. 1210 * 1211 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1212 * associated with the ASE ID sent by the server. 1213 * @param rsp_code Response code. 1214 * @param reason Reason code. 1215 */ 1216 void (*release)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1217 enum bt_bap_ascs_reason reason); 1218 1219 /** 1220 * @brief Remote Published Audio Capability (PAC) record discovered 1221 * 1222 * Called when a PAC record has been discovered as part of the discovery procedure. 1223 * 1224 * The @p codec is only valid while in the callback, so the values must be stored by the 1225 * receiver if future use is wanted. 1226 * 1227 * @param conn Connection to the remote unicast server. 1228 * @param dir The type of remote endpoints and capabilities discovered. 1229 * @param codec Remote capabilities. 1230 * 1231 * If discovery procedure has complete both @p codec and @p ep are set to NULL. 1232 */ 1233 void (*pac_record)(struct bt_conn *conn, enum bt_audio_dir dir, 1234 const struct bt_codec *codec); 1235 1236 /** 1237 * @brief Remote Audio Stream Endoint (ASE) discovered 1238 * 1239 * Called when an ASE has been discovered as part of the discovery procedure. 1240 * 1241 * @param conn Connection to the remote unicast server. 1242 * @param dir The type of remote endpoints and capabilities discovered. 1243 * @param ep Remote endpoint. 1244 * 1245 * If discovery procedure has complete both @p codec and @p ep are set to NULL. 1246 */ 1247 void (*endpoint)(struct bt_conn *conn, enum bt_audio_dir dir, struct bt_bap_ep *ep); 1248 1249 /** 1250 * @brief BAP discovery callback function. 1251 * 1252 * If discovery procedure has completed @p ep is set to NULL and @p err is 0. 1253 * 1254 * @param conn Connection to the remote unicast server. 1255 * @param err Error value. 0 on success, GATT error on positive value or errno on 1256 * negative value. 1257 * @param dir The type of remote endpoints and capabilities discovered. 1258 * 1259 * If discovery procedure has complete both @p codec and @p ep are set to NULL. 1260 */ 1261 void (*discover)(struct bt_conn *conn, int err, enum bt_audio_dir dir); 1262 }; 1263 1264 /** 1265 * @brief Register unicast client callbacks. 1266 * 1267 * Only one callback structure can be registered, and attempting to 1268 * registering more than one will result in an error. 1269 * 1270 * @param cb Unicast client callback structure. 1271 * 1272 * @return 0 in case of success or negative value in case of error. 1273 */ 1274 int bt_bap_unicast_client_register_cb(const struct bt_bap_unicast_client_cb *cb); 1275 1276 /** 1277 * @brief Discover remote capabilities and endpoints 1278 * 1279 * This procedure is used by a client to discover remote capabilities and 1280 * endpoints and notifies via params callback. 1281 * 1282 * @param conn Connection object 1283 * @param dir The type of remote endpoints and capabilities to discover. 1284 */ 1285 int bt_bap_unicast_client_discover(struct bt_conn *conn, enum bt_audio_dir dir); 1286 1287 /** @} */ /* End of group bt_bap_unicast_client */ 1288 /** 1289 * @brief BAP Broadcast APIs 1290 * @defgroup bt_bap_broadcast BAP Broadcast APIs 1291 * @ingroup bt_bap 1292 * @{ 1293 */ 1294 1295 struct bt_bap_base_bis_data { 1296 /* Unique index of the BIS */ 1297 uint8_t index; 1298 #if defined(CONFIG_BT_CODEC_MAX_DATA_COUNT) 1299 /** Codec Specific Data count. 1300 * 1301 * Only valid if the data_count of struct bt_codec in the subgroup is 0 1302 */ 1303 size_t data_count; 1304 /** Codec Specific Data 1305 * 1306 * Only valid if the data_count of struct bt_codec in the subgroup is 0 1307 */ 1308 struct bt_codec_data data[CONFIG_BT_CODEC_MAX_DATA_COUNT]; 1309 #endif /* CONFIG_BT_CODEC_MAX_DATA_COUNT */ 1310 }; 1311 1312 struct bt_bap_base_subgroup { 1313 /* Number of BIS in the subgroup */ 1314 size_t bis_count; 1315 /** Codec information for the subgroup 1316 * 1317 * If the data_count of the codec is 0, then codec specific data may be 1318 * found for each BIS in the bis_data. 1319 */ 1320 struct bt_codec codec; 1321 /* Array of BIS specific data for each BIS in the subgroup */ 1322 struct bt_bap_base_bis_data bis_data[BROADCAST_SNK_STREAM_CNT]; 1323 }; 1324 1325 struct bt_bap_base { 1326 /** @brief QoS Presentation Delay in microseconds 1327 * 1328 * Value range 0 to @ref BT_AUDIO_PD_MAX. 1329 */ 1330 uint32_t pd; 1331 1332 /* Number of subgroups in the BASE */ 1333 size_t subgroup_count; 1334 1335 /* Array of subgroups in the BASE */ 1336 struct bt_bap_base_subgroup subgroups[BROADCAST_SNK_SUBGROUP_CNT]; 1337 }; 1338 1339 /** @brief Decode a Broadcast Audio Source Endpoint (BASE) from advertising data 1340 * 1341 * The BASE is sent via periodic advertising, and can be decoded into a 1342 * bt_bap_base using this function. 1343 * 1344 * @param data The periodic advertising data 1345 * @param base The output struct to put the decode BASE in 1346 * 1347 * @return 0 in case of success or negative errno value in case of error. 1348 */ 1349 int bt_bap_decode_base(struct bt_data *data, struct bt_bap_base *base); 1350 1351 /** @} */ /* End of group bt_bap_broadcast */ 1352 1353 /** 1354 * @brief BAP Broadcast Source APIs 1355 * @defgroup bt_bap_broadcast_source BAP Broadcast Source APIs 1356 * @ingroup bt_bap_broadcast 1357 * @{ 1358 */ 1359 1360 /** Broadcast Source stream parameters */ 1361 struct bt_bap_broadcast_source_stream_param { 1362 /** Audio stream */ 1363 struct bt_bap_stream *stream; 1364 1365 #if CONFIG_BT_CODEC_MAX_DATA_COUNT > 0 1366 /** 1367 * @brief The number of elements in the @p data array. 1368 * 1369 * The BIS specific data may be omitted and this set to 0. 1370 */ 1371 size_t data_count; 1372 1373 /** BIS Codec Specific Configuration */ 1374 struct bt_codec_data *data; 1375 #endif /* CONFIG_BT_CODEC_MAX_DATA_COUNT > 0 */ 1376 }; 1377 1378 /** Broadcast Source subgroup parameters*/ 1379 struct bt_bap_broadcast_source_subgroup_param { 1380 /** The number of parameters in @p stream_params */ 1381 size_t params_count; 1382 1383 /** Array of stream parameters */ 1384 struct bt_bap_broadcast_source_stream_param *params; 1385 1386 /** Subgroup Codec configuration. */ 1387 struct bt_codec *codec; 1388 }; 1389 1390 /** Broadcast Source create parameters */ 1391 struct bt_bap_broadcast_source_create_param { 1392 /** The number of parameters in @p subgroup_params */ 1393 size_t params_count; 1394 1395 /** Array of stream parameters */ 1396 struct bt_bap_broadcast_source_subgroup_param *params; 1397 1398 /** Quality of Service configuration. */ 1399 struct bt_codec_qos *qos; 1400 1401 /** 1402 * @brief Broadcast Source packing mode. 1403 * 1404 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED. 1405 * 1406 * @note This is a recommendation to the controller, which the controller may ignore. 1407 */ 1408 uint8_t packing; 1409 1410 /** Whether or not to encrypt the streams. */ 1411 bool encryption; 1412 1413 /** 1414 * @brief Broadcast code 1415 * 1416 * If the value is a string or a the value is less than 16 octets, 1417 * the remaining octets shall be 0. 1418 * 1419 * Example: 1420 * The string "Broadcast Code" shall be 1421 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 1422 */ 1423 uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE]; 1424 }; 1425 1426 /** 1427 * @brief Create audio broadcast source. 1428 * 1429 * Create a new audio broadcast source with one or more audio streams. 1430 * 1431 * The broadcast source will be visible for scanners once this has been called, 1432 * and the device will advertise audio announcements. 1433 * 1434 * No audio data can be sent until bt_bap_broadcast_source_start() has been called and no audio 1435 * information (BIGInfo) will be visible to scanners (see @ref bt_le_per_adv_sync_cb). 1436 * 1437 * @param[in] param Pointer to parameters used to create the broadcast source. 1438 * @param[out] source Pointer to the broadcast source created 1439 * 1440 * @return Zero on success or (negative) error code otherwise. 1441 */ 1442 int bt_bap_broadcast_source_create(struct bt_bap_broadcast_source_create_param *param, 1443 struct bt_bap_broadcast_source **source); 1444 1445 /** 1446 * @brief Reconfigure audio broadcast source. 1447 * 1448 * Reconfigure an audio broadcast source with a new codec and codec quality of 1449 * service parameters. This can only be done when the source is stopped. 1450 * 1451 * @param source Pointer to the broadcast source 1452 * @param codec Codec configuration. 1453 * @param qos Quality of Service configuration 1454 * 1455 * @return Zero on success or (negative) error code otherwise. 1456 */ 1457 int bt_bap_broadcast_source_reconfig(struct bt_bap_broadcast_source *source, struct bt_codec *codec, 1458 struct bt_codec_qos *qos); 1459 1460 /** 1461 * @brief Modify the metadata of an audio broadcast source. 1462 * 1463 * Modify the metadata an audio broadcast source. This can only be done when the source is started. 1464 * To update the metadata in the stopped state, use bt_bap_broadcast_source_reconfig(). 1465 * 1466 * @param source Pointer to the broadcast source. 1467 * @param meta Metadata entries. 1468 * @param meta_count Number of metadata entries. 1469 * 1470 * @return Zero on success or (negative) error code otherwise. 1471 */ 1472 int bt_bap_broadcast_source_update_metadata(struct bt_bap_broadcast_source *source, 1473 const struct bt_codec_data meta[], size_t meta_count); 1474 1475 /** 1476 * @brief Start audio broadcast source. 1477 * 1478 * Start an audio broadcast source with one or more audio streams. 1479 * The broadcast source will start advertising BIGInfo, and audio data can be streamed. 1480 * 1481 * @param source Pointer to the broadcast source 1482 * @param adv Pointer to an extended advertising set with periodic advertising configured. 1483 * 1484 * @return Zero on success or (negative) error code otherwise. 1485 */ 1486 int bt_bap_broadcast_source_start(struct bt_bap_broadcast_source *source, 1487 struct bt_le_ext_adv *adv); 1488 1489 /** 1490 * @brief Stop audio broadcast source. 1491 * 1492 * Stop an audio broadcast source. 1493 * The broadcast source will stop advertising BIGInfo, and audio data can no longer be streamed. 1494 * 1495 * @param source Pointer to the broadcast source 1496 * 1497 * @return Zero on success or (negative) error code otherwise. 1498 */ 1499 int bt_bap_broadcast_source_stop(struct bt_bap_broadcast_source *source); 1500 1501 /** 1502 * @brief Delete audio broadcast source. 1503 * 1504 * Delete an audio broadcast source. 1505 * The broadcast source will stop advertising entirely, and the source can no longer be used. 1506 * 1507 * @param source Pointer to the broadcast source 1508 * 1509 * @return Zero on success or (negative) error code otherwise. 1510 */ 1511 int bt_bap_broadcast_source_delete(struct bt_bap_broadcast_source *source); 1512 1513 /** 1514 * @brief Get the broadcast ID of a broadcast source 1515 * 1516 * This will return the 3-octet broadcast ID that should be advertised in the 1517 * extended advertising data with @ref BT_UUID_BROADCAST_AUDIO_VAL as @ref BT_DATA_SVC_DATA16. 1518 * 1519 * See table 3.14 in the Basic Audio Profile v1.0.1 for the structure. 1520 * 1521 * @param[in] source Pointer to the broadcast source. 1522 * @param[out] broadcast_id Pointer to the 3-octet broadcast ID. 1523 * 1524 * @return Zero on success or (negative) error code otherwise. 1525 */ 1526 int bt_bap_broadcast_source_get_id(const struct bt_bap_broadcast_source *source, 1527 uint32_t *const broadcast_id); 1528 1529 /** 1530 * @brief Get the Broadcast Audio Stream Endpoint of a broadcast source 1531 * 1532 * This will encode the BASE of a broadcast source into a buffer, that can be used for 1533 * advertisement. The encoded BASE will thus be encoded as little-endian. The BASE shall be put into 1534 * the periodic advertising data (see bt_le_per_adv_set_data()). 1535 * 1536 * See table 3.15 in the Basic Audio Profile v1.0.1 for the structure. 1537 * 1538 * @param source Pointer to the broadcast source. 1539 * @param base_buf Pointer to a buffer where the BASE will be inserted. 1540 * 1541 * @return Zero on success or (negative) error code otherwise. 1542 */ 1543 int bt_bap_broadcast_source_get_base(struct bt_bap_broadcast_source *source, 1544 struct net_buf_simple *base_buf); 1545 1546 /** @} */ /* End of bt_bap_broadcast_source */ 1547 1548 /** 1549 * @brief BAP Broadcast Sink APIs 1550 * @defgroup bt_bap_broadcast_sink BAP Broadcast Sink APIs 1551 * @ingroup bt_bap_broadcast 1552 * @{ 1553 */ 1554 1555 /** Broadcast Audio Sink callback structure */ 1556 struct bt_bap_broadcast_sink_cb { 1557 /** @brief Scan receive callback 1558 * 1559 * Scan receive callback is called whenever a broadcast source has been found. 1560 * 1561 * @param info Advertiser packet information. 1562 * @param ad Buffer containing advertiser data. 1563 * @param broadcast_id 24-bit broadcast ID 1564 * 1565 * @return true to sync to the broadcaster, else false. 1566 * Syncing to the broadcaster will stop the current scan. 1567 */ 1568 bool (*scan_recv)(const struct bt_le_scan_recv_info *info, struct net_buf_simple *ad, 1569 uint32_t broadcast_id); 1570 1571 /** @brief Periodic advertising sync callback 1572 * 1573 * Called when synchronized to a periodic advertising. When synchronized a 1574 * bt_bap_broadcast_sink structure is allocated for future use. 1575 * 1576 * @param sink Pointer to the allocated sink structure. 1577 * @param sync Pointer to the periodic advertising sync. 1578 * @param broadcast_id 24-bit broadcast ID previously reported by scan_recv. 1579 */ 1580 void (*pa_synced)(struct bt_bap_broadcast_sink *sink, struct bt_le_per_adv_sync *sync, 1581 uint32_t broadcast_id); 1582 1583 /** @brief Broadcast Audio Source Endpoint (BASE) received 1584 * 1585 * Callback for when we receive a BASE from a broadcaster after 1586 * syncing to the broadcaster's periodic advertising. 1587 * 1588 * @param sink Pointer to the sink structure. 1589 * @param base Broadcast Audio Source Endpoint (BASE). 1590 */ 1591 void (*base_recv)(struct bt_bap_broadcast_sink *sink, const struct bt_bap_base *base); 1592 1593 /** @brief Broadcast sink is syncable 1594 * 1595 * Called whenever a broadcast sink is not synchronized to audio, but the audio is 1596 * synchronizable. This is inferred when a BIGInfo report is received. 1597 * 1598 * Once this callback has been called, it is possible to call 1599 * bt_bap_broadcast_sink_sync() to synchronize to the audio stream(s). 1600 * 1601 * @param sink Pointer to the sink structure. 1602 * @param encrypted Whether or not the broadcast is encrypted 1603 */ 1604 void (*syncable)(struct bt_bap_broadcast_sink *sink, bool encrypted); 1605 1606 /** @brief Scan terminated callback 1607 * 1608 * Scan terminated callback is called whenever a scan started by 1609 * bt_bap_broadcast_sink_scan_start() is terminated before 1610 * bt_bap_broadcast_sink_scan_stop(). 1611 * 1612 * Typical reasons for this are that the periodic advertising has synchronized 1613 * (success criteria) or the scan timed out. It may also be called if the periodic 1614 * advertising failed to synchronize. 1615 * 1616 * @param err 0 in case of success or negative value in case of error. 1617 */ 1618 void (*scan_term)(int err); 1619 1620 /** @brief Periodic advertising synchronization lost callback 1621 * 1622 * The periodic advertising synchronization lost callback is called if the periodic 1623 * advertising sync is lost. If this happens, the sink object is deleted. To synchronize to 1624 * the broadcaster again, bt_bap_broadcast_sink_scan_start() must be called. 1625 * 1626 * @param sink Pointer to the sink structure. 1627 */ 1628 void (*pa_sync_lost)(struct bt_bap_broadcast_sink *sink); 1629 1630 /* Internally used list node */ 1631 sys_snode_t _node; 1632 }; 1633 1634 /** @brief Register Broadcast sink callbacks 1635 * * 1636 * @param cb Broadcast sink callback structure. 1637 */ 1638 int bt_bap_broadcast_sink_register_cb(struct bt_bap_broadcast_sink_cb *cb); 1639 1640 /** @brief Start scan for broadcast sources. 1641 * 1642 * Starts a scan for broadcast sources. Scan results will be received by 1643 * the scan_recv callback. 1644 * Only reports from devices advertising broadcast audio support will be sent. 1645 * Note that a broadcast source may advertise broadcast audio capabilities, 1646 * but may not be streaming. 1647 * 1648 * @param param Scan parameters. 1649 * 1650 * @return Zero on success or (negative) error code otherwise. 1651 */ 1652 int bt_bap_broadcast_sink_scan_start(const struct bt_le_scan_param *param); 1653 1654 /** 1655 * @brief Stop scan for broadcast sources. 1656 * 1657 * Stops ongoing scanning for broadcast sources. 1658 * 1659 * @return Zero on success or (negative) error code otherwise. 1660 */ 1661 int bt_bap_broadcast_sink_scan_stop(void); 1662 1663 /** @brief Create a Broadcast Sink from a periodic advertising sync 1664 * 1665 * This should only be done after verifying that the periodic advertising sync 1666 * is from a Broadcast Source. 1667 * 1668 * The created Broadcast Sink will need to be supplied to 1669 * bt_bap_broadcast_sink_sync() in order to synchronize to the broadcast 1670 * audio. 1671 * 1672 * bt_bap_broadcast_sink_cb.pa_synced() will be called with the Broadcast 1673 * Sink object created if this is successful. 1674 * 1675 * @param pa_sync Pointer to the periodic advertising sync object. 1676 * @param broadcast_id 24-bit broadcast ID. 1677 * 1678 * @return 0 in case of success or errno value in case of error. 1679 */ 1680 int bt_bap_broadcast_sink_create(struct bt_le_per_adv_sync *pa_sync, uint32_t broadcast_id); 1681 1682 /** @brief Sync to a broadcaster's audio 1683 * 1684 * @param sink Pointer to the sink object from the base_recv callback. 1685 * @param indexes_bitfield Bitfield of the BIS index to sync to. To sync to e.g. BIS index 1 and 1686 * 2, this should have the value of BIT(1) | BIT(2). 1687 * @param streams Stream object pointers to be used for the receiver. If multiple BIS 1688 * indexes shall be synchronized, multiple streams shall be provided. 1689 * @param broadcast_code The 16-octet broadcast code. Shall be supplied if the broadcast is 1690 * encrypted (see @ref bt_bap_broadcast_sink_cb.syncable). 1691 * If the value is a string or a the value is less 1692 * than 16 octets, the remaining octets shall be 0. 1693 * 1694 * Example: 1695 * The string "Broadcast Code" shall be 1696 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 1697 * 1698 * @return 0 in case of success or negative value in case of error. 1699 */ 1700 int bt_bap_broadcast_sink_sync(struct bt_bap_broadcast_sink *sink, uint32_t indexes_bitfield, 1701 struct bt_bap_stream *streams[], const uint8_t broadcast_code[16]); 1702 1703 /** @brief Stop audio broadcast sink. 1704 * 1705 * Stop an audio broadcast sink. 1706 * The broadcast sink will stop receiving BIGInfo, and audio data can no longer be streamed. 1707 * 1708 * @param sink Pointer to the broadcast sink 1709 * 1710 * @return Zero on success or (negative) error code otherwise. 1711 */ 1712 int bt_bap_broadcast_sink_stop(struct bt_bap_broadcast_sink *sink); 1713 1714 /** @brief Release a broadcast sink 1715 * 1716 * Once a broadcast sink has been allocated after the pa_synced callback, it can be deleted using 1717 * this function. If the sink has synchronized to any broadcast audio streams, these must first be 1718 * stopped using bt_bap_stream_stop. 1719 * 1720 * @param sink Pointer to the sink object to delete. 1721 * 1722 * @return 0 in case of success or negative value in case of error. 1723 */ 1724 int bt_bap_broadcast_sink_delete(struct bt_bap_broadcast_sink *sink); 1725 1726 /** @} */ /* End of group bt_bap_broadcast_sink */ 1727 1728 /** 1729 * @brief Register the callbacks for the Basic Audio Profile Scan Delegator 1730 * 1731 * @param cb Pointer to the callback struct 1732 */ 1733 void bt_bap_scan_delegator_register_cb(struct bt_bap_scan_delegator_cb *cb); 1734 1735 /** 1736 * @brief Set the periodic advertising sync state to syncing 1737 * 1738 * Set the periodic advertising sync state for a receive state to syncing, 1739 * notifying Broadcast Assistants. 1740 * 1741 * @param src_id The source id used to identify the receive state. 1742 * @param pa_state The Periodic Advertising sync state to set. 1743 * BT_BAP_PA_STATE_NOT_SYNCED and BT_BAP_PA_STATE_SYNCED is 1744 * not necessary to provide, as they are handled internally. 1745 * 1746 * @return int Error value. 0 on success, errno on fail. 1747 */ 1748 int bt_bap_scan_delegator_set_pa_state(uint8_t src_id, 1749 enum bt_bap_pa_state pa_state); 1750 1751 /** 1752 * @brief Set the sync state of a receive state in the server 1753 * 1754 * @param src_id The source id used to identify the receive state. 1755 * @param bis_synced Array of bitfields to set the BIS sync state for each 1756 * subgroup. 1757 * @return int Error value. 0 on success, ERRNO on fail. 1758 */ 1759 int bt_bap_scan_delegator_set_bis_sync_state( 1760 uint8_t src_id, 1761 uint32_t bis_synced[BT_BAP_SCAN_DELEGATOR_MAX_SUBGROUPS]); 1762 1763 struct bt_bap_scan_delegator_add_src_param { 1764 /** The periodic adverting sync */ 1765 struct bt_le_per_adv_sync *pa_sync; 1766 1767 /** The broadcast isochronous group encryption state */ 1768 enum bt_bap_big_enc_state encrypt_state; 1769 1770 /** The 24-bit broadcast ID */ 1771 uint32_t broadcast_id; 1772 1773 /** Number of subgroups */ 1774 uint8_t num_subgroups; 1775 1776 /** Subgroup specific information */ 1777 struct bt_bap_scan_delegator_subgroup subgroups[BT_BAP_SCAN_DELEGATOR_MAX_SUBGROUPS]; 1778 }; 1779 1780 /** 1781 * @brief Add a receive state source locally 1782 * 1783 * This will notify any connected clients about the new source. This allows them 1784 * to modify and even remove it. 1785 * 1786 * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink 1787 * sources are autonomously added. 1788 * 1789 * @param param The parameters for adding the new source 1790 * 1791 * @return int errno on failure, or source ID on success. 1792 */ 1793 int bt_bap_scan_delegator_add_src(const struct bt_bap_scan_delegator_add_src_param *param); 1794 1795 struct bt_bap_scan_delegator_mod_src_param { 1796 /** The periodic adverting sync */ 1797 uint8_t src_id; 1798 1799 /** The broadcast isochronous group encryption state */ 1800 enum bt_bap_big_enc_state encrypt_state; 1801 1802 /** The 24-bit broadcast ID */ 1803 uint32_t broadcast_id; 1804 1805 /** Number of subgroups */ 1806 uint8_t num_subgroups; 1807 1808 /** 1809 * @brief Subgroup specific information 1810 * 1811 * If a subgroup's metadata_len is set to 0, the existing metadata 1812 * for the subgroup will remain unchanged 1813 */ 1814 struct bt_bap_scan_delegator_subgroup subgroups[BT_BAP_SCAN_DELEGATOR_MAX_SUBGROUPS]; 1815 }; 1816 1817 /** 1818 * @brief Add a receive state source locally 1819 * 1820 * This will notify any connected clients about the new source. This allows them 1821 * to modify and even remove it. 1822 * 1823 * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink 1824 * sources are autonomously modifed. 1825 * 1826 * @param param The parameters for adding the new source 1827 * 1828 * @return int errno on failure, or source ID on success. 1829 */ 1830 int bt_bap_scan_delegator_mod_src(const struct bt_bap_scan_delegator_mod_src_param *param); 1831 1832 /** 1833 * @brief Remove a receive state source 1834 * 1835 * This will remove the receive state. If the receive state periodic advertising 1836 * is synced, bt_bap_scan_delegator_cb.pa_sync_term_req() will be called. 1837 * 1838 * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink 1839 * sources are autonomously removed. 1840 * 1841 * @param src_id The source ID to remove 1842 * 1843 * @return int Error value. 0 on success, errno on fail. 1844 */ 1845 int bt_bap_scan_delegator_rem_src(uint8_t src_id); 1846 1847 enum bt_bap_scan_delegator_iter { 1848 BT_BAP_SCAN_DELEGATOR_ITER_STOP = 0, 1849 BT_BAP_SCAN_DELEGATOR_ITER_CONTINUE, 1850 }; 1851 1852 /** Callback function for Scan Delegator receive state search functions 1853 * 1854 * @param recv_state The receive state. 1855 * @param user_data User data. 1856 * 1857 * @return @ref BT_BAP_SCAN_DELEGATOR_ITER_STOP to stop iterating or 1858 * @ref BT_BAP_SCAN_DELEGATOR_ITER_CONTINUE to continue. 1859 */ 1860 typedef enum bt_bap_scan_delegator_iter (*bt_bap_scan_delegator_state_func_t)( 1861 const struct bt_bap_scan_delegator_recv_state *recv_state, void *user_data); 1862 1863 /** @brief Iterate through all existing receive states 1864 * 1865 * @param func The callback function 1866 * @param user_data User specified data that sent to the callback function 1867 */ 1868 void bt_bap_scan_delegator_foreach_state(bt_bap_scan_delegator_state_func_t func, 1869 void *user_data); 1870 1871 /** @brief Find and return a receive state based on a compare function 1872 * 1873 * @param func The compare callback function 1874 * @param user_data User specified data that sent to the callback function 1875 * 1876 * @return The first receive state where the @p func returned true, or NULL 1877 */ 1878 const struct bt_bap_scan_delegator_recv_state *bt_bap_scan_delegator_find_state( 1879 bt_bap_scan_delegator_state_func_t func, void *user_data); 1880 1881 /******************************** CLIENT API ********************************/ 1882 1883 /** 1884 * @brief Callback function for writes. 1885 * 1886 * @param conn The connection to the peer device. 1887 * @param err Error value. 0 on success, GATT error on fail. 1888 */ 1889 typedef void (*bt_bap_broadcast_assistant_write_cb)(struct bt_conn *conn, 1890 int err); 1891 1892 struct bt_bap_broadcast_assistant_cb { 1893 /** 1894 * @brief Callback function for bt_bap_broadcast_assistant_discover. 1895 * 1896 * @param conn The connection that was used to discover 1897 * Broadcast Audio Scan Service. 1898 * @param err Error value. 0 on success, 1899 * GATT error or ERRNO on fail. 1900 * @param recv_state_count Number of receive states on the server. 1901 */ 1902 void (*discover)(struct bt_conn *conn, int err, 1903 uint8_t recv_state_count); 1904 1905 /** 1906 * @brief Callback function for Broadcast Audio Scan Service client scan results 1907 * 1908 * Called when the scanner finds an advertiser that advertises the 1909 * BT_UUID_BROADCAST_AUDIO UUID. 1910 * 1911 * @param info Advertiser information. 1912 * @param broadcast_id 24-bit broadcast ID. 1913 */ 1914 void (*scan)(const struct bt_le_scan_recv_info *info, 1915 uint32_t broadcast_id); 1916 1917 /** 1918 * @brief Callback function for when a receive state is read or updated 1919 * 1920 * Called whenever a receive state is read or updated. 1921 * 1922 * @param conn The connection to the Broadcast Audio Scan Service server. 1923 * @param err Error value. 0 on success, GATT error on fail. 1924 * @param state The receive state or NULL if the receive state is empty. 1925 */ 1926 void (*recv_state)(struct bt_conn *conn, int err, 1927 const struct bt_bap_scan_delegator_recv_state *state); 1928 1929 /** 1930 * @brief Callback function for when a receive state is removed. 1931 * 1932 * @param conn The connection to the Broadcast Audio Scan Service server. 1933 * @param err Error value. 0 on success, GATT error on fail. 1934 * @param src_id The receive state. 1935 */ 1936 void (*recv_state_removed)(struct bt_conn *conn, int err, 1937 uint8_t src_id); 1938 1939 /** 1940 * @brief Callback function for bt_bap_broadcast_assistant_scan_start(). 1941 * 1942 * @param conn The connection to the peer device. 1943 * @param err Error value. 0 on success, GATT error on fail. 1944 */ 1945 void (*scan_start)(struct bt_conn *conn, int err); 1946 1947 /** 1948 * @brief Callback function for bt_bap_broadcast_assistant_scan_stop(). 1949 * 1950 * @param conn The connection to the peer device. 1951 * @param err Error value. 0 on success, GATT error on fail. 1952 */ 1953 void (*scan_stop)(struct bt_conn *conn, int err); 1954 1955 /** 1956 * @brief Callback function for bt_bap_broadcast_assistant_add_src(). 1957 * 1958 * @param conn The connection to the peer device. 1959 * @param err Error value. 0 on success, GATT error on fail. 1960 */ 1961 void (*add_src)(struct bt_conn *conn, int err); 1962 1963 /** 1964 * @brief Callback function for bt_bap_broadcast_assistant_mod_src(). 1965 * 1966 * @param conn The connection to the peer device. 1967 * @param err Error value. 0 on success, GATT error on fail. 1968 */ 1969 void (*mod_src)(struct bt_conn *conn, int err); 1970 1971 /** 1972 * @brief Callback function for bt_bap_broadcast_assistant_broadcast_code(). 1973 * 1974 * @param conn The connection to the peer device. 1975 * @param err Error value. 0 on success, GATT error on fail. 1976 */ 1977 void (*broadcast_code)(struct bt_conn *conn, int err); 1978 1979 /** 1980 * @brief Callback function for bt_bap_broadcast_assistant_rem_src(). 1981 * 1982 * @param conn The connection to the peer device. 1983 * @param err Error value. 0 on success, GATT error on fail. 1984 */ 1985 void (*rem_src)(struct bt_conn *conn, int err); 1986 }; 1987 1988 /** 1989 * @brief Discover Broadcast Audio Scan Service on the server. 1990 * 1991 * Warning: Only one connection can be active at any time; discovering for a 1992 * new connection, will delete all previous data. 1993 * 1994 * @param conn The connection 1995 * @return int Error value. 0 on success, GATT error or ERRNO on fail. 1996 */ 1997 int bt_bap_broadcast_assistant_discover(struct bt_conn *conn); 1998 1999 /** 2000 * @brief Scan start for BISes for a remote server. 2001 * 2002 * This will let the Broadcast Audio Scan Service server know that this device 2003 * is actively scanning for broadcast sources. 2004 * The function can optionally also start scanning, if the caller does not want 2005 * to start scanning itself. 2006 * 2007 * Scan results, if @p start_scan is true, is sent to the 2008 * bt_bap_broadcast_assistant_scan_cb callback. 2009 * 2010 * @param conn Connection to the Broadcast Audio Scan Service server. 2011 * Used to let the server know that we are scanning. 2012 * @param start_scan Start scanning if true. If false, the application should 2013 * enable scan itself. 2014 * @return int Error value. 0 on success, GATT error or ERRNO on fail. 2015 */ 2016 int bt_bap_broadcast_assistant_scan_start(struct bt_conn *conn, 2017 bool start_scan); 2018 2019 /** 2020 * @brief Stop remote scanning for BISes for a server. 2021 * 2022 * @param conn Connection to the server. 2023 * @return int Error value. 0 on success, GATT error or ERRNO on fail. 2024 */ 2025 int bt_bap_broadcast_assistant_scan_stop(struct bt_conn *conn); 2026 2027 /** 2028 * @brief Registers the callbacks used by Broadcast Audio Scan Service client. 2029 */ 2030 void bt_bap_broadcast_assistant_register_cb(struct bt_bap_broadcast_assistant_cb *cb); 2031 2032 /** Parameters for adding a source to a Broadcast Audio Scan Service server */ 2033 struct bt_bap_broadcast_assistant_add_src_param { 2034 /** Address of the advertiser. */ 2035 bt_addr_le_t addr; 2036 2037 /** SID of the advertising set. */ 2038 uint8_t adv_sid; 2039 2040 /** Whether to sync to periodic advertisements. */ 2041 bool pa_sync; 2042 2043 /** 24-bit broadcast ID */ 2044 uint32_t broadcast_id; 2045 2046 /** 2047 * @brief Periodic advertising interval in milliseconds. 2048 * 2049 * BT_BAP_PA_INTERVAL_UNKNOWN if unknown. 2050 */ 2051 uint16_t pa_interval; 2052 2053 /** Number of subgroups */ 2054 uint8_t num_subgroups; 2055 2056 /** Pointer to array of subgroups */ 2057 struct bt_bap_scan_delegator_subgroup *subgroups; 2058 }; 2059 2060 /** 2061 * @brief Add a source on the server. 2062 * 2063 * @param conn Connection to the server. 2064 * @param param Parameter struct. 2065 * 2066 * @return Error value. 0 on success, GATT error or ERRNO on fail. 2067 */ 2068 int bt_bap_broadcast_assistant_add_src( 2069 struct bt_conn *conn, const struct bt_bap_broadcast_assistant_add_src_param *param); 2070 2071 /** Parameters for modifying a source */ 2072 struct bt_bap_broadcast_assistant_mod_src_param { 2073 /** Source ID of the receive state. */ 2074 uint8_t src_id; 2075 2076 /** Whether to sync to periodic advertisements. */ 2077 bool pa_sync; 2078 2079 /** 2080 * @brief Periodic advertising interval. 2081 * 2082 * BT_BAP_PA_INTERVAL_UNKNOWN if unknown. 2083 */ 2084 uint16_t pa_interval; 2085 2086 /** Number of subgroups */ 2087 uint8_t num_subgroups; 2088 2089 /** Pointer to array of subgroups */ 2090 struct bt_bap_scan_delegator_subgroup *subgroups; 2091 }; 2092 2093 /** @brief Modify a source on the server. 2094 * 2095 * @param conn Connection to the server. 2096 * @param param Parameter struct. 2097 * 2098 * @return Error value. 0 on success, GATT error or ERRNO on fail. 2099 */ 2100 int bt_bap_broadcast_assistant_mod_src( 2101 struct bt_conn *conn, const struct bt_bap_broadcast_assistant_mod_src_param *param); 2102 2103 /** @brief Set a broadcast code to the specified receive state. 2104 * 2105 * @param conn Connection to the server. 2106 * @param src_id Source ID of the receive state. 2107 * @param broadcast_code The broadcast code. 2108 * 2109 * @return Error value. 0 on success, GATT error or ERRNO on fail. 2110 */ 2111 int bt_bap_broadcast_assistant_set_broadcast_code( 2112 struct bt_conn *conn, uint8_t src_id, 2113 const uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE]); 2114 2115 /** @brief Remove a source from the server. 2116 * 2117 * @param conn Connection to the server. 2118 * @param src_id Source ID of the receive state. 2119 * 2120 * @return Error value. 0 on success, GATT error or ERRNO on fail. 2121 */ 2122 int bt_bap_broadcast_assistant_rem_src(struct bt_conn *conn, uint8_t src_id); 2123 2124 /** @brief Read the specified receive state from the server. 2125 * 2126 * @param conn Connection to the server. 2127 * @param idx The index of the receive start (0 up to the value from 2128 * bt_bap_broadcast_assistant_discover_cb) 2129 * 2130 * @return Error value. 0 on success, GATT error or ERRNO on fail. 2131 */ 2132 int bt_bap_broadcast_assistant_read_recv_state(struct bt_conn *conn, 2133 uint8_t idx); 2134 2135 /** @} */ /* end of bt_bap */ 2136 2137 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_ */ 2138
