rymanluk commented on code in PR #1619: URL: https://github.com/apache/mynewt-nimble/pull/1619#discussion_r1384498428
########## nimble/host/include/host/ble_audio_broadcast.h: ########## @@ -0,0 +1,271 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +#ifndef H_BLE_AUDIO_BROADCAST_ +#define H_BLE_AUDIO_BROADCAST_ + +#include <stdint.h> +#include "host/ble_gap.h" +#include "host/ble_iso.h" +#include "host/ble_audio_common.h" + +struct ble_broadcast_create_params { + /** BASE to broadcast */ + struct ble_audio_base *base; + + /** Parameters used to configure Extended advertising */ + struct ble_gap_ext_adv_params *extended_params; + + /** Parameters used to configure Periodic advertising */ + struct ble_gap_periodic_adv_params *periodic_params; + + /** Broadcast name - null terminated. + * Set NULL to not include in advertising + */ + const char *name; + + /** Advertising instance */ + uint8_t adv_instance; + + /** BIG parameters */ + struct ble_iso_big_params *big_params; + + /** Additional data to include in Extended Advertising */ + uint8_t *svc_data; + + /** Additional data length */ + uint16_t svc_data_len; +}; + +struct ble_broadcast_update_params { + /** Broadcast name - null terminated. + * Set NULL to not include in advertising + */ + const char *name; + + /** Advertising instance */ + uint8_t adv_instance; + + /** Additional data to include in Extended Advertising */ + uint8_t *svc_data; + + /** Additional data length */ + uint16_t svc_data_len; + + /** Broadcast ID */ + uint32_t broadcast_id; +}; + +typedef int ble_audio_broadcast_destroy_fn(struct ble_audio_base *base, + void *args); + +/** BASE configuration describing broadcast advertisement */ +struct ble_broadcast_base_config { + /** Advertising instance used by broadcast */ + uint8_t adv_instance; + + /** Pointer to BASE configuration */ + struct ble_audio_base *base; + + /** BIG parameters */ + struct ble_iso_big_params *big_params; + + /** + * Optional callback associated with broadcasting instance, called on + * destroying broadcast + */ + ble_audio_broadcast_destroy_fn *destroy_cb; + + /** Pointer to args for `destroy_cb` */ + void *args; +}; + +/** + * @brief Create Broadcast Audio Source Endpoint and configure advertising + * instance + * + * This function configures advertising instance for extended and periodic + * advertisements to be ready for broadcast with BASE configuration. + * + * @param[in] params Pointer to a `ble_broadcast_base_params` + * structure that defines BASE, extended + * advertising and periodic advertising + * configuration. + * @param[out] config_out Pointer to a `ble_broadcast_base_config` + * structure to return configuration of created + * BASE advertisement. + * @param[in] destroy_cb Optional callback to be called when BASE + * advertisement is destroyed. + * @param[in] args Optional arguments to be passed to `destroy_cb` + * @param[in] gap_cb GAP event callback to be associated with BASE + * advertisement. + * + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_broadcast_create(const struct ble_broadcast_create_params + *params, + struct ble_broadcast_base_config *config_out, + ble_audio_broadcast_destroy_fn *destroy_cb, + void *args, + ble_gap_event_fn *gap_cb); + +/** + * @brief Start advertisements for given BASE configuration + * + * This function starts BASE advertisement on by enabling extended and periodic + * advertising and creates BASE for this instance. + * + * @param[in] base_config Pointer to a `ble_broadcast_base_config` + * struct that shall be used for broadcast. + * @param[in] cb Pointer to an ISO event handler. + * @param[in] cb_arg Arguments to an ISO event handler. + * + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_broadcast_start(const struct ble_broadcast_base_config *base_config, + ble_iso_event_fn *cb, void *cb_arg); + +/** + * @brief Stop advertisements for given BASE configuration + * + * This function stops BASE advertisement by disabling extended and periodic + * advertising. Advertising instance is still configured and ready for resume. + * BASE will be terminated. + * + * @param[in] base_config Pointer to a `ble_broadcast_base_config` + * struct that broadcast shall be stopped for. + * + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_broadcast_stop(const struct ble_broadcast_base_config + *base_config); + +/** + * @brief Destroy advertisements for given BASE configuration + * + * This function terminates BASE advertisement instance. + * After return advertising instance is free and must be configured again + * for future advertisements. + * + * @param[in] base_config Pointer to a `ble_broadcast_base_config` + * struct that broadcast shall be terminated for. + * + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_broadcast_destroy(const struct ble_broadcast_base_config + *base_config); + +/** + * @brief Update advertisements for given BASE configuration + * + * This function can be used to update extended advertisements. This function + * cannot be used to update BASE configuration itself, because BIG cannot be + * changed during it's lifetime. To modify BASE configuration destroy it using + * `ble_audio_broadcast_destroy` and recreate with `ble_audio_broadcast_create` + * + * @param[in] params Pointer to structure with new advertising data + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_broadcast_update(const struct ble_broadcast_update_params + *params); + +/** BIG Subgroup parameters */ +struct ble_broadcast_subgroup_params { + /** Subgroup level Codec information */ + struct ble_audio_codec_id *codec_info; + + /** Subgroup level Codec Specific Configuration */ + uint8_t *codec_spec_config; + + /** Subgroup level Codec Specific Configuration length */ + uint8_t codec_spec_config_len; + + /** Subgroup Metadata */ + uint8_t *metadata; + + /** Subgroup Metadata length*/ + uint8_t metadata_len; +}; + +/** + * @brief Build BIG subgroup structure + * + * This is a helper function can be used to fill out `ble_broadcast_subgroup` + * structure. Created subgroup extends subgroup list in provided BASE. + * This function increases `num_subgroups` in BASE structure. + * + * @param[out] base Pointer to a `ble_audio_base` structure, + * that will be extended by the new subgroup + * @param[out] sub Pointer to a `ble_broadcast_subgroup` + * structure, that will be filled out with + * supplied configuration + * @param[in] params Pointer to a `ble_broadcast_subgroup_params` + * structure, containing information about new + * subgroup + * + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_broadcast_build_sub(struct ble_audio_base *base, + struct ble_audio_subgroup *sub, + const struct ble_broadcast_subgroup_params + *params); + +/** BIS parameters */ +struct ble_broadcast_bis_params { + /** BIS index */ + uint8_t idx; + + /** BIS level Codec Specific Configuration */ + uint8_t *codec_spec_config; + + /** BIS level Codec Specific Configuration length */ + uint8_t codec_spec_config_len; +}; + +/** + * @brief Build BIS structure + * + * This is a helper function can be used to fill out `ble_broadcast_bis` + * structure. Created BIS extends BIS list in provided subgroup. + * This function increases `bis_cnt` in subgroup structure. + * + * @param[out] sub Pointer to a `ble_broadcast_subgroup` + * structure, + * that will be extended by the new BIS + * @param[out] bis Pointer to a `ble_broadcast_bis` Review Comment: Imho, this is exactly why the `return` is the result of operation. In a case of error returned, we don't care about [out] params and its state is unknown. Current description should be good. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: commits-unsubscr...@mynewt.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
