Skip to content

Commit

Permalink
Bluetooth: Introducing the A2DP function.
Browse files Browse the repository at this point in the history 
bug: v/43699

Rootcause: Add comments to the A2DP .h file and improve function documentation.

Signed-off-by: jialu <[email protected]>
  • Loading branch information
@jialu522
jialu522 committed Jan 10, 2025
1 parent 5bf9336 commit 693dc74
Show file tree
Hide file tree
Showing 3 changed files with 426 additions and 83 deletions.
59 changes: 51 additions & 8 deletions framework/include/bt_a2dp.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,9 @@
#include "bt_addr.h"
#include "bt_device.h"

/**
* @cond
*/
/**
* @brief A2DP audio state
*/
Expand All @@ -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);
Expand Down
219 changes: 182 additions & 37 deletions framework/include/bt_a2dp_sink.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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);

Expand Down
Loading

0 comments on commit 693dc74

Please sign in to comment.