KKopyscinski commented on code in PR #1675: URL: https://github.com/apache/mynewt-nimble/pull/1675#discussion_r1505645615
########## nimble/host/include/host/ble_audio_codec.h: ########## @@ -0,0 +1,201 @@ +/* + * 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_CODEC_ +#define H_BLE_AUDIO_CODEC_ + +/** + * @file ble_audio_codec.h + * + * @brief Bluetooth LE Audio Codec + * + * This header file provides the public API for managing LE Audio Codecs + * + * @defgroup ble_audio_codec Bluetooth LE Audio Codec + * @ingroup bt_host + * @{ + * + * This API allows to create and manage list of LE Audio codecs with their capabilities and + * metadata. This list can be used by higher level services, like PACS. Memory management of + * codec entries is left to application and neither static nor dynamic allocation is enforced. + * + */ + +#include "stdint.h" +#include "ble_audio_common.h" + +#define BLE_AUDIO_CODEC_FLAG_SOURCE 0x01 +#define BLE_AUDIO_CODEC_FLAG_SINK 0x02 + +/** OP Codes for Codec events */ +enum ble_audio_codec_event_op { + /** Codec was registered */ + BLE_AUDIO_CODEC_REGISTERED_EVENT, + /** Codec was unregistered */ + BLE_AUDIO_CODEC_UNREGISTERED_EVENT +}; + +/** Codec list entry */ +struct ble_audio_codec_record { + /* Pointer to next codec list entry */ + STAILQ_ENTRY(ble_audio_codec_record) next; + + /* Codec ID */ + struct ble_audio_codec_id codec_id; + + /* Length of Codec Specific Capabilities */ + uint8_t codec_spec_caps_len; + + /* Codec Specific Capabilities data */ + const uint8_t *codec_spec_caps; + + /* Metadata length */ + uint8_t metadata_len; + + /* Metadata */ + const uint8_t *metadata; + + /* Codec entry flags. It is any combination of following flags: + * - BLE_AUDIO_CODEC_FLAG_SOURCE + * - BLE_AUDIO_CODEC_FLAG_SINK + */ + uint8_t flags; +}; + +/** Type definition codec iteration callback function. */ +typedef int ble_audio_codec_foreach_fn(const struct ble_audio_codec_record *record, void *arg); + +struct ble_audio_codec_register_params { + /* Codec ID structure */ + struct ble_audio_codec_id codec_id; + + /* Codec Specific Capabilities length */ + uint8_t codec_spec_caps_len; + + /* Codec Specific Capabilities data */ + uint8_t *codec_spec_caps; + + /* Metadata length */ + uint8_t metadata_len; + + /* Metadata */ + uint8_t *metadata; + + /* Codec entry flags. It is any combination of following flags: + * - BLE_AUDIO_CODEC_FLAG_SOURCE + * - BLE_AUDIO_CODEC_FLAG_SINK + */ + uint8_t flags; +}; + +/** + * @brief Register codec entry + * + * @param[in] params Pointer to a `ble_audio_codec_register_params` + * structure that defines Codec Specific Capabilities + * @param[in] cb Function used to parse Codec + * Specific Capabilities + * @param[in] cb_arg Optional callback argument. + * @param[out] out_record Pointer to registered codec entry. + * + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_codec_register(const struct ble_audio_codec_register_params + *params, + struct ble_audio_codec_record *out_record); +/** + * @brief Remove codec entry from register + * + * @param[in] codec_record Pointer to registered codec entry. + * + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_codec_unregister(struct ble_audio_codec_record *codec_record); + +/** + * @brief Iterate through all registered codecs and call function on every + * one of them. + * + * @param[in] cb Callback to be called on codec entries. + * @param[in] arg Optional callback argument. + * @param[in] flags Codec entry flags. It is any + * combination of following flags: + * - BLE_AUDIO_CODEC_FLAG_SOURCE + * - BLE_AUDIO_CODEC_FLAG_SINK + * This filters entries so the callback is called + * only on these that match the flag. + * + * @return 0 on success; + * A non-zero value on failure. + */ +int ble_audio_codec_foreach(uint8_t flags, ble_audio_codec_foreach_fn *cb, void *arg); + +typedef void ble_audio_codec_listener_fn(enum ble_audio_codec_event_op op, + struct ble_audio_codec_record *record, void *arg); + +/** + * Event listener structure + * + * This should be used as an opaque structure and not modified manually. + */ +struct ble_audio_codec_listener { + /** The function to call when a Codec event occurs. */ + ble_audio_codec_listener_fn *fn; + + /** An optional argument to pass to the event handler function. */ + void *arg; + + /** Singly-linked list entry. */ + SLIST_ENTRY(ble_audio_codec_listener) link; +}; + +/** + * Registers listener for Codec events + * + * On success listener structure will be initialized automatically and does not + * need to be initialized prior to calling this function. To change callback + * and/or argument unregister listener first and register it again. + * + * @param listener Listener structure + * @param fn Callback function + * @param arg Callback argument + * + * @return 0 on success + * BLE_HS_EINVAL if no callback is specified + * BLE_HS_EALREADY if listener is already registered + */ +int ble_audio_codec_listener_register(struct ble_audio_codec_listener *listener, + ble_audio_codec_listener_fn *fn, void *arg); +/** + * Unregisters listener for Codec events + * + * @param listener Listener structure + * + * @return 0 on success + * BLE_HS_ENOENT if listener was not registered + */ +int ble_audio_codec_listener_unregister(struct ble_audio_codec_listener *listener); Review Comment: Ok, #1708 looks like being close to merge so I'll just use that listener. -- 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
