diff --git a/framework/include/bt_a2dp.h b/framework/include/bt_a2dp.h index a59168f..518400f 100644 --- a/framework/include/bt_a2dp.h +++ b/framework/include/bt_a2dp.h @@ -21,6 +21,9 @@ #include "bt_addr.h" #include "bt_device.h" +/** + * @cond + */ /** * @brief A2DP audio state */ @@ -29,23 +32,63 @@ typedef enum { A2DP_AUDIO_STATE_STOPPED, A2DP_AUDIO_STATE_STARTED, } a2dp_audio_state_t; +/** + * @endcond + */ /** - * @brief A2DP connection state changed callback + * @brief Callback for A2DP connection state changed. * - * @param cookie - callback cookie. - * @param addr - address of peer A2DP device. - * @param state - connection state. + * There are four states for A2DP connection, namely DISCONNECTED, CONNECTING, + * CONNECTED, and DISCONNECTING. During the initialization phase of the A2DP, + * it is necessary to register callback functions. This callback is triggered + * when there is a change in the state of the A2DP connection. + * + * Stable States: + * DISCONNECTED: The initial state. + * CONNECTED: The A2DP connection is established. + * Transient states: + * CONNECTING: The A2DP connection is being established. + * DISCONNECTING: The A2DP connection is being terminated. + * + * @param cookie - Callback cookie. + * @param addr - The Bluetooth address of the peer device. + * @param state - A2DP profile connection state. + * + * **Example:** + * @code +static void on_connection_state_changed_cb(void* cookie, bt_address_t* addr, profile_connection_state_t state) +{ + printf("A2DP connection state is: %d", state); +} + * @endcode */ typedef void (*a2dp_connection_state_callback)(void* cookie, bt_address_t* addr, profile_connection_state_t state); /** - * @brief A2DP audio connection state changed callback + * @brief Callback for A2DP audio state changed. + * + * There are three states for A2DP audio, namely SUSPEND, STOPPED, + * and STARTED. It is important to note that a callback function + * is triggered whenever a change occurs in the audio state. + * + * Stable States: + * SUSPEND: The stream is suspended. + * STOPPED: The stream is stopped. + * STARTED: The stream is started. + * + * @param cookie - Callback cookie. + * @param addr - The Bluetooth address of the peer device. + * @param state - A2DP audio connection state. * - * @param cookie - callback cookie. - * @param addr - address of peer A2DP device. - * @param state - audio connection state. + * **Example:** + * @code +static void on_audio_state_changed_cb(void* cookie, bt_address_t* addr, a2dp_audio_state_t state) +{ + printf("A2DP audio state is: %d", state); +} + * @endcode */ typedef void (*a2dp_audio_state_callback)(void* cookie, bt_address_t* addr, a2dp_audio_state_t state); diff --git a/framework/include/bt_a2dp_sink.h b/framework/include/bt_a2dp_sink.h index e7bdae3..ad13100 100644 --- a/framework/include/bt_a2dp_sink.h +++ b/framework/include/bt_a2dp_sink.h @@ -25,15 +25,30 @@ extern "C" { #endif /** - * @brief A2DP audio sink config changed callback + * @brief Callback for A2DP audio configuration. * - * @param cookie - callback cookie. - * @param addr - address of peer A2DP source device. + * During the initialization process of the A2DP, callback functions are registered. + * This callbacks is triggered whenever a change occurs in the audio configuration + * of an A2DP connection. + * + * @param cookie - Callbacks cookie. + * @param addr - The Bluetooth address of the peer device. + * + * **Example:** + * @code +static void on_audio_config_changed_cb(void* cookie, bt_address_t* addr) +{ + printf("A2DP audio sink configuration is changed"); +} + * @endcode */ typedef void (*a2dp_audio_sink_config_callback)(void* cookie, bt_address_t* addr); /** - * @brief A2DP sink callback structure + * @cond + */ +/** + * @brief A2DP Sink callback structure * */ typedef struct { @@ -43,79 +58,209 @@ typedef struct { a2dp_audio_state_callback audio_state_cb; a2dp_audio_sink_config_callback audio_sink_config_cb; } a2dp_sink_callbacks_t; +/** + * @endcond + */ /** - * @brief Register callback functions to A2DP sink service + * @brief Register callback functions to A2DP Sink service. + * + * When initializing the A2DP Sink, an application should register callback functions + * to the A2DP Sink service, which includes a connection state callback function, an + * audio state callback function, and an audio sink configuration callback function. + * Subsequently, the A2DP Sink service will notify the application of any state + * changes via the registered callback functions. + * + * @param ins - Buetooth client instance. + * @param callbacks - A2DP Sink callback functions. + * @return void* - Callbacks cookie, if the callback is registered successfuly. NULL + * if the callback is already registered or registration fails. + * To obtain more information, refer to bt_remote_callbacks_register(). * - * @param ins - bluetooth client instance. - * @param id - A2DP sink callback functions. - * @return void* - callbacks cookie. + * **Example:** + * @code +static const a2dp_sink_callbacks_t a2dp_sink_cbs = { + sizeof(a2dp_sink_cbs), + a2dp_sink_connection_state_cb, + a2dp_sink_audio_state_cb, + a2dp_sink_audio_config_cb, +}; + +void a2dp_sink_init(void* ins) +{ + static void* sink_cbks_cookie; + + sink_cbks_cookie = bt_a2dp_sink_register_callbacks(ins, &a2dp_sink_cbs); +} + * @endcode */ void* BTSYMBOLS(bt_a2dp_sink_register_callbacks)(bt_instance_t* ins, const a2dp_sink_callbacks_t* callbacks); /** - * @brief Unregister callback functions to a2dp sink service + * @brief Unregister callback functions from A2DP Sink service. * - * @param ins - bluetooth client instance. - * @param id - callbacks cookie. - * @return true - on callback unregister success - * @return false - on callback cookie not found + * An application may use this interface to stop listening on the A2DP Sink + * callbacks and to release the associated resources. + * + * @param ins - Buetooth client instance. + * @param cookie - Callbacks cookie. + * @return true - Callback unregistration successful. + * @return false - Callback cookie not found or callback unregistration failed. + * + * **Example:** + * @code +static void* sink_cbks_cookie = bt_a2dp_sink_register_callbacks(ins, &a2dp_sink_cbs); + +void a2dp_sink_uninit(void* ins) +{ + bt_a2dp_sink_unregister_callbacks(ins, sink_cbks_cookie); +} + * @endcode */ bool BTSYMBOLS(bt_a2dp_sink_unregister_callbacks)(bt_instance_t* ins, void* cookie); /** - * @brief Check A2DP sink is connected + * @brief Check if A2DP is already connected. + * + * This function serves the purpose of verifying the connection status of A2DP. + * It is important to note that the A2DP profile is deemed connected solely when + * the A2DP Sink is either in the Opened or Started state. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP source device. - * @return true - connected. - * @return false - not connected. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. + * @return true - A2DP Sink connected. + * @return false - A2DP Sink not connected. + * + * **Example:** + * @code +void a2dp_sink_connected(void* ins, bt_address_t* addr) +{ + bool ret = bt_a2dp_sink_is_connected(ins, addr); + + printf("A2DP sink is %s", ret? "connected" : "not connected"); +} + * @endcode */ bool BTSYMBOLS(bt_a2dp_sink_is_connected)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief Check A2DP sink is playing + * @brief Check if the stream is being transmitted. + * + * This function is used to verify the streaming status of the A2DP Sink. + * The A2DP Sink can only be deemed as playing when it is in the Started + * state and the audio is also in the Started state. + * + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. + * @return true - Stream is being transmitted . + * @return false - No stream transmission. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP source device. - * @return true - playing. - * @return false - not playing. + * **Example** + * @code +void a2dp_sink_playing(void* ins, bt_address_t* addr) +{ + bool ret = bt_a2dp_sink_is_playing(ins, addr); + + printf("A2DP sink is %s", ret? "playing" : "not playing"); +} + * @endcode */ bool BTSYMBOLS(bt_a2dp_sink_is_playing)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief get A2DP sink connection state + * @brief Obtain A2DP Sink connection state. + * + * There are four states for A2DP connection, namely DISCONNECTED, CONNECTING, + * CONNECTED, and DIACONNECTED. This function is used by the application of + * the A2DP Sink to obtain the current state of the A2DP profile connection. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP source device. - * @return profile_connection_state_t - connection state. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. + * @return profile_connection_state_t - A2DP profile connection state. + * + * **Example** + * @code +int get_state_cmd(void* ins, bt_address_t* addr) +{ + int state = bt_a2dp_sink_get_connection_state(ins, addr); + + printf("A2DP sink connection state is: %d", state); + + return state; +} + * @endcode */ profile_connection_state_t BTSYMBOLS(bt_a2dp_sink_get_connection_state)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief Establish connection with peer A2DP device + * @brief Establish connection with peer A2DP device. + * + * This function is used to establish an A2DP profile connection with a designated + * peer device. Following the successful creation of the A2DP connection, the A2DP + * Sink transitions to an Opened state and subsequently notifies the application of + * its CONNECTED state. Upon reception of audio data from the A2DP Source device, + * the A2DP Sink then proceeds to forward the audio data to the Media. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP source device. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. * @return bt_status_t - BT_STATUS_SUCCESS on success, a negated errno value on failure. + * + * **Example** + * @code +int a2dp_sink_connect(void* ins, bt_address_t* addr) +{ + int ret = bt_a2dp_sink_connect(ins, addr); + + printf("A2DP sink connect %s", ret ? "failed" : "success"); + + return ret; +} + * @endcode */ bt_status_t BTSYMBOLS(bt_a2dp_sink_connect)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief Disconnect from peer A2DP device + * @brief Disconnect from peer A2DP device. + * + * This function is utilized for the purpose of disconnecting an A2DP profile connection + * with a designated peer device. Upon successful disconnection of the A2DP connection, + * the A2DP Sink transitions into an Idle state and subsequently notifies the application + * of the DISCONNECTED state. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP source device. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. * @return bt_status_t - BT_STATUS_SUCCESS on success, a negated errno value on failure. + * + * **Example** + * @code +int a2dp_sink_disconnect(void* ins, bt_address_t* addr) +{ + int ret = bt_a2dp_sink_disconnect(ins, addr); + + printf("A2DP sink disconnect %s", ret ? "failed" : "success"); + + return ret; +} + * @endcode */ bt_status_t BTSYMBOLS(bt_a2dp_sink_disconnect)(bt_instance_t* ins, bt_address_t* addr); -/** - * @brief set a peer A2DP source device as active device +/* + * @brief Set a peer A2DP Source device as active device. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP source device. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. * @return bt_status_t - BT_STATUS_SUCCESS on success, a negated errno value on failure. + * + * **Example** + * @code +int enable_source_device(void* ins, bt_address_t* addr) +{ + int ret = bt_a2dp_sink_set_active_device(ins, addr); + + return ret; +} + * @endcode */ bt_status_t BTSYMBOLS(bt_a2dp_sink_set_active_device)(bt_instance_t* ins, bt_address_t* addr); diff --git a/framework/include/bt_a2dp_source.h b/framework/include/bt_a2dp_source.h index c876382..60a0342 100644 --- a/framework/include/bt_a2dp_source.h +++ b/framework/include/bt_a2dp_source.h @@ -26,13 +26,28 @@ extern "C" { #endif /** - * @brief A2DP audio source config changed callback + * @brief Callback for A2DP audio configuration. * - * @param cookie - callback cookie. - * @param addr - address of peer A2DP sink device. + * During the initialization process of the A2DP, callback functions are registered. + * This callbacks is triggered whenever a change occurs in the audio configuration + * of an A2DP connection. + * + * @param cookie - Callback cookie. + * @param addr - The Bluetooth address of the peer device. + * + * **Example:** + * @code +static void on_audio_config_changed_cb(void* cookie, bt_address_t* addr) +{ + printf("A2DP audio source configuration is changed"); +} + * @endcode */ typedef void (*a2dp_audio_source_config_callback)(void* cookie, bt_address_t* addr); +/** + * @cond + */ /** * @brief A2DP source callback structure * @@ -44,87 +59,227 @@ typedef struct { a2dp_audio_state_callback audio_state_cb; a2dp_audio_source_config_callback audio_source_config_cb; } a2dp_source_callbacks_t; +/** + * @endcond + */ /** - * @brief Register callback functions to A2DP source service + * @brief Register callback functions to A2DP Source service. + * + * When the A2DP Source is initialized, an application registers various callback + * functions to the A2DP Source service, such as the connection state callback function, + * audio state callback function, and audio source configuration callback function. + * The A2DP Source service will notify the application of any state changes via the + * registered callback functions. + * + * @param ins - Bluetooth client instance. + * @param callbacks - A2DP Source callback functions. + * @return void* - Callbacks cookie, if the callback is registered successfuly. + * NULL if the callback is already registered or registration fails. * - * @param ins - bluetooth client instance. - * @param id - A2DP source callback functions. - * @return void* - callbacks cookie. + * **Example:** + * @code +static const a2dp_source_callbacks_t a2dp_src_cbs = { + sizeof(a2dp_src_cbs), + a2dp_src_connection_state_cb, + a2dp_src_audio_state_cb, + a2dp_src_audio_source_config_cb, +}; + +void a2dp_source_uninit(void* ins) +{ + static void* src_cbks_cookie; + + src_cbks_cookie = bt_a2dp_source_register_callbacks(ins, &a2dp_src_cbs); +} + * @endcode */ void* BTSYMBOLS(bt_a2dp_source_register_callbacks)(bt_instance_t* ins, const a2dp_source_callbacks_t* callbacks); /** - * @brief Unregister callback functions to A2DP source service + * @brief Unregister callback functions to A2DP Source service. * - * @param ins - bluetooth client instance. - * @param id - callbacks cookie. - * @return true - on callback unregister success. - * @return false - on callback cookie not found. + * An application may use this interface to stop listening on the A2DP Source + * callbacks and to release the associated resources. + * + * @param ins - Bluetooth client instance. + * @param cookie - Callbacks cookie. + * @return true - Callback unregistration successful. + * @return false - Callback cookie not found or callback unregistration failed. + * + * **Example:** + * @code +static void* src_cbks_cookie = bt_a2dp_source_register_callbacks(ins, &a2dp_src_cbs); + +void a2dp_source_uninit(void* ins) +{ + bt_a2dp_source_unregister_callbacks(ins, src_cbks_cookie); +} + * @endcode */ bool BTSYMBOLS(bt_a2dp_source_unregister_callbacks)(bt_instance_t* ins, void* cookie); + /** - * @brief Check A2DP source is connected + * @brief Check if A2DP is already connected. + * + * This function serves the purpose of verifying the connection status of A2DP. + * It is important to note that the A2DP profile is deemed connected solely when + * the A2DP Source is either in the Opened or Started state. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP sink device. - * @return true - connected. - * @return false - not connected. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. + * @return true - A2DP Source connected. + * @return false - A2DP Source not connected. + * + * **Example:** + * @code +void a2dp_source_connected(void* ins, bt_address_t* addr) +{ + bool ret = bt_a2dp_source_is_connected(ins, addr); + + printf("A2DP source is %s", ret? "connected" : "not connected"); +} + * @endcode */ bool BTSYMBOLS(bt_a2dp_source_is_connected)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief Check A2DP source is playing + * @brief Check if the stream is being transmitted. + * + * This function is used to verify the streaming status of the A2DP Source. + * The A2DP Source can only be deemed as playing when it is in the Started + * state and the audio is also in the Started state. + * + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. + * @return true - Stream is being transmitted. + * @return false - No stream transmission. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP sink device. - * @return true - playing. - * @return false - not playing. + * **Example** + * @code +void a2dp_source_playing(void* ins, bt_address_t* addr) +{ + bool ret = bt_a2dp_source_is_playing(ins, addr); + + printf("A2DP source is %s", ret? "playing" : "not playing"); +} + * @endcode */ bool BTSYMBOLS(bt_a2dp_source_is_playing)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief get A2DP source connection state + * @brief Obtain A2DP Source connection state. + * + * There are four states for A2DP connection, namely DISCONNECTED, CONNECTING, + * CONNECTED, and DIACONNECTED. This function is used by the application of + * the A2DP Source to obtain the current state of the A2DP profile connection. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP sink device. - * @return profile_connection_state_t - connection state. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. + * @return profile_connection_state_t - A2DP profile connection state. + * + * **Example** + * @code +int get_state_cmd(void* ins, bt_address_t* addr) +{ + int state = bt_a2dp_source_get_connection_state(ins, addr); + + printf("A2DP source connection state is: %d", state); + + return state; +} + * @endcode */ profile_connection_state_t BTSYMBOLS(bt_a2dp_source_get_connection_state)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief Establish connection with peer A2DP device + * @brief Establish connection with peer A2DP device. + * + * This function is used to establish an A2DP profile connection with a designated + * peer device. Upon successful establishment of the A2DP connection, the A2DP Source + * transitions to an Opened state and notifies the application of its CONNECTED status. + * Upon receipt of audio data from the media, the A2DP Source subsequently relays the + * audio data to the A2DP Sink. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP sink device. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. * @return bt_status_t - BT_STATUS_SUCCESS on success, a negated errno value on failure. + * + * **Example** + * @code +int a2dp_source_connect(void* ins, bt_address_t* addr) +{ + int ret = bt_a2dp_source_connect(ins, &addr); + + printf("A2DP source connect %s", ret ? "failed" : "success"); + + return ret; +} + * @endcode */ bt_status_t BTSYMBOLS(bt_a2dp_source_connect)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief Disconnect from peer A2DP device + * @brief Disconnect from peer A2DP device. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP sink device. + * This function is used to remove an A2DP profile connection with a specific peer device. Once + * the A2DP connection is removed, the A2DP Source turns into the Idle state and reports the + * DISCONNECTED state to the application. + * + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. * @return bt_status_t - BT_STATUS_SUCCESS on success, a negated errno value on failure. + * + * **Example** + * @code +int a2dp_source_disconnect(void* ins, bt_address_t* addr) +{ + int ret = bt_a2dp_source_disconnect(ins, addr); + + printf("A2DP source disconnect %s", ret ? "failed" : "success"); + + return ret; +} + * @endcode */ bt_status_t BTSYMBOLS(bt_a2dp_source_disconnect)(bt_instance_t* ins, bt_address_t* addr); /** - * @brief set a peer A2DP sink device as silence device + * @brief Set a peer A2DP Sink device as silence device. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP sink device. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. + * @param silence - True, switch to silence mode to keep this device inactive. * @return bt_status_t - BT_STATUS_SUCCESS on success, a negated errno value on failure. + * + * **Example** + * @code +int disable_sink_device(void* ins, bt_address_t* addr, bool silence) +{ + int ret = bt_a2dp_source_set_silence_device(ins, addr, silence); + + return ret; +} + * @endcode */ bt_status_t BTSYMBOLS(bt_a2dp_source_set_silence_device)(bt_instance_t* ins, bt_address_t* addr, bool silence); /** - * @brief set a peer A2DP sink device as active device + * @brief Set a peer A2DP Sink device as active device. * - * @param ins - bluetooth client instance. - * @param addr - address of peer A2DP sink device. + * @param ins - Bluetooth client instance. + * @param addr - The Bluetooth address of the peer device. * @return bt_status_t - BT_STATUS_SUCCESS on success, a negated errno value on failure. + * + * **Example** + * @code +int enable_sink_device(void* ins, bt_address_t* addr) +{ + int ret = bt_a2dp_source_set_active_device(ins, addr); + + return ret; +} + * @endcode */ bt_status_t BTSYMBOLS(bt_a2dp_source_set_active_device)(bt_instance_t* ins, bt_address_t* addr);