EEPW论坛

FILE NAME
    a2dp.h
   
DESCRIPTION
 Header file for the A2DP profile library.  This profile library implements
 the A2DP using the services of the GAVDP library which is hidden from the
    Client application by this library
 
 The library exposes a functional downstream API and an upstream message
 based API.
 
  CLIENT APPLICATION
   |      |
   | A2DP Library
   |      |
   | GAVDP Library
   |      |
  CONNECTION Library
          |
      BLUESTACK
 
*/
/*!
@file a2dp.h
@brief Interface to the Advanced Audio Distribution Profile library.

  Header file for the A2DP profile library.  This profile library
  implements the A2DP using the services of the GAVDP library which is
  hidden from the Client application by this library
  
  When a device wishes to start streaming audio content, the device must
  first set up a streaming connection.  During the stream setup, the
  devices select the most suitable audio streaming parameters.
  Application service capability and transport service capability are
  configured during this stream setup procedure.
  
  Once a streaming connection is established and the start streaming
  procedure as defined in the GAVDP specification is executed, audio can
  be streamed from the Source (SRC) to the Sink (SNK).
  
  This library provides the low level services to permit an audio stream
  to be configured, started, stopped and suspended.  This library
  provides the stream configuration and control.  The actual streaming of
  data is performed by the underlying firmware.  The audio stream is
  routed to the Digital Signal Processor (DSP) present on CSR BlueCore
  Multimedia devices.  The CPU intensive operation of encoding/decoding a
  media stream is performed by the DSP.
 
  The library exposes a functional downstream API and an upstream message
  based API.
*/

#ifndef A2DP_H_
#define A2DP_H_

#include <bdaddr_.h>
#include <message.h>
#include <stream.h>

#include "gavdp.h"

struct __A2DP;
/*!
 @brief The Advanced Audio Distribution Profile structure.
*/
typedef struct __A2DP A2DP;

/*!
 @brief Kalimba Resource.
*/
#define RESOURCE_KALIMBA (1)

/*!
 @brief A2DP role.
 
 The A2DP specification defines two roles, Source (SRC) and Sink (SNK). 
 
 A device is the SRC when it acts as a source of a digital audio stream that
 is delivered to a SNK on the same Piconet.
 
 A device is the SNK when it acts as a sink of a digital audio stream
 delivered from the SRC on the same Piconet.
*/
typedef enum
{
 /*!  This SEP is a sink. Register the config block dependent on the SEP
   type (a2dp_sep_type). */
 a2dp_sink,    
 /*! The SEP is an AV source with an USB input for the data. */
 a2dp_source_usb,  
 /*! The SEP is an AV source with an analogue input for the data, using the
   CSR internal codec. */
 a2dp_source_analogue, 
 /*! The SEP is an AV source with an analogue input for the data, using the
   wolfson codec. */
 a2dp_source_wolfson  
} a2dp_role;

/*!
 @brief The type of the SEP. This identifies the codec type being registered
 or used.
*/
typedef enum
{
 /*! Invalid SEP value. */
 a2dp_sep_invalid = 0, 
 /*! The SEP supports the SBC codec (support for this codec is
   mandatory). */
 a2dp_sbc,    
 /*! The SEP supports the MPEG-1,2 AUdio codec. */
 a2dp_mpeg_audio,  
 /*! The SEP supports the MPEG-2,4 AAC codec. */
 a2dp_mpeg_aac,   
 /*! The SEP supports a codec from the ATRAC family. */
 a2dp_atrac,    
 /*! The SEP supports a vendor defined codec. */
 a2dp_vendor    
} a2dp_sep_type;

/*!
 @brief Codec cppabilities specification block. This is used if the client
 wants to supply their own specific SEP capability parameters.
*/
typedef struct
{
 /*! The size of the configuration block. */
 uint16 size_service_caps; 
 /*! Capabilities block for the SEP being added. */
 uint8 *service_caps;  
} sep_config_params;

/*!
 @brief A2DP SEP (Stream End Point) configuration parameters.

 Before a SEP can be used for streaming it must be registered with the A2DP
 library. These parameters are used to determine the SEP type to register
 and configure it correctly.

 If the params pointer is set to null then the default parameters stored in
 the library are used to configure the SEP. If however the client wishes to
 supply their own, specific, set of parameters then they must provide a
 valid sep_config_params configuration. Note that the SEP config block
 provided must either be a pointer to constant data or the client must
 allocate and manage the memory for it as the a2dp library will copy the
 pointer but will not take ownership of that memory. It is recommended that
 the config parameters are passed in as a constant block of data.
*/
typedef struct
{
 a2dp_sep_type  sep_type;
 sep_config_params *params;
} a2dp_sep_config;

/*!
 @brief Audio stream channel mode.
 
 The specification defines the following channel modes. The SNK must support
 all modes. It is mandatory for the SRC to support mono and at least one of
 the remaining three modes.
*/
typedef enum
{
 a2dp_mono,
 a2dp_dual_channel,
 a2dp_stereo,
 a2dp_joint_stereo
} a2dp_channel_mode;

/*!
 @brief The Status codes are returned to indicate to the Client application
 the status of a requested operation.
*/
typedef enum
{
 /*! Operation was successful. */
 a2dp_success = (0),    
 /*! Operation failed. */
  a2dp_fail,      
 /*! Not enough resources. */
 a2dp_no_resource,    
 /*! Request is not supported in the current state. */
 a2dp_bad_state,     
 /*! Operation timed out before completion. */
 a2dp_timeout,     
 /*! Service capabilities passed to library are bad or incomplete. */
 a2dp_service_caps_error,  
 /*! Local and remote service capabilities are incompatible. */
 a2dp_service_caps_incompatible, 
 /*! Remote device understood but rejected the operation. */
 a2dp_rejected_by_remote_device, 
 /*! Remote device does not support the requested operation. */
 a2dp_unsupported_feature,  
 /*! SEID passed to library is unknown. */
 a2dp_unknown_seid,    
 /*! Remote device closed the stream. */
 a2dp_closed_by_remote_device, 
 /*! Local or remote abort due to signalling breakdown. */
 a2dp_aborted,       
 /*! Device specified is not connected. */
 a2dp_device_not_connected,  
 /*! The operation is already in progress. */
 a2dp_busy,      
    /*! Connection disconnected due to link loss. */
    a2dp_disconnect_link_loss,
 /*! The A2DP library has received an unrecognised error from the GAVDP
   library. */
 a2dp_unhandled_error,   
 /*! The requested codec does not have a decode DSP file in the file
   system. */
 a2dp_unsupported_codec,   
 /*! The requested sep role is unknown/ unsupported. */
 a2dp_unsupported_sep_role  
} a2dp_status_code;

/*!
 @brief A2DP configuration parameters.

    The initialisation parameters allow the client to specify whether it wants
    to configure the a2dp library as a source or a sink. The client may also
    specify a service record to register instead of the default one supplied
    with this library. If the service_record pointer is set to null then the
    default service record supplied with the a2dp library is used.
*/
typedef struct
{
 a2dp_role role;
    uint16      priority;
    uint16      size_service_record;
    uint8       *service_record;
} a2dp_init_params;

/*!
 @brief The upstream A2DP library messages.
*/
#define A2DP_MESSAGE_BASE 0x6d00

/*
 Do not document this enum.
*/
#ifndef DO_NOT_DOCUMENT
typedef enum
{
 /* Library initialisation */
 A2DP_INIT_CFM = A2DP_MESSAGE_BASE,
 
 /* Stream endpoint registration */
 A2DP_ADD_SEP_CFM,
 
 /* Stream endpoint connection */
 A2DP_OPEN_CFM,
 A2DP_OPEN_IND,
 A2DP_CLOSE_CFM,
 A2DP_CLOSE_IND,
 
 /* Stream endpoint control */
 A2DP_START_CFM,
 A2DP_START_IND,
 A2DP_SUSPEND_CFM,
 A2DP_SUSPEND_IND,
 
 /* Stream endpoint configuration */
 A2DP_CONFIGURE_CFM, /* reserved for future use */
 A2DP_CODEC_SETTINGS_IND,
 A2DP_SIGNALLING_OPEN_IND,
 A2DP_SIGNALLING_CLOSE_IND,
 
 A2DP_MESSAGE_TOP
} A2dpMessageId;
#endif

/* Upstream messages from the A2DP library */

/*!
 @brief This message returns the result of a call to A2dpInit. 
*/
typedef struct
{
 /*! Pointer to A2DP profile instance that was initialised.*/
    A2DP    *a2dp;  
 /*! The current A2DP status. */
 a2dp_status_code status;  
} A2DP_INIT_CFM_T;

/*!
 @brief This message returns the result of a call to A2dpAddSep.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP    *a2dp;  
 /*! The current A2DP status. */
 a2dp_status_code status;  
 /*! Type of codec being registered for this SEP. */ 
 a2dp_sep_type  sep_type; 
} A2DP_ADD_SEP_CFM_T;

/*!
 @brief This message returns the result of a call to A2dpOpen.

 On success, contains sink for the AV streams and SEP type in use.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP    *a2dp;    
 /*! The current A2DP status. */
 a2dp_status_code result;    
 /*! Type of codec being used. This is for informational purposes only */
 a2dp_sep_type  sep_type;   
 /*! Sink for the media transport channel. */
 Sink     media_sink;   
 /*! Not currently supported. */
 Sink     recovery_sink;  
 /*! Not currently supported. */ 
 Sink     reporting_sink;  
} A2DP_OPEN_CFM_T;

/*!
 @brief This message informs the application that a remote device has opened
 a local Stream End Point.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP  *a2dp;  
    /*! Type of codec being used. This is for informational purposes only */
 a2dp_sep_type  sep_type;
 /*! Sink for the media transport channel. */
  Sink   media_sink;   
 /*! Not currently supported. */
 Sink   recovery_sink;  
 /*! Not currently supported. */ 
 Sink   reporting_sink;  
} A2DP_OPEN_IND_T;

/*!
 @brief This message is generated as the result of a call to A2dpClose.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP    *a2dp;    
 /*! The current A2DP status. */
 a2dp_status_code result;    
 /*! Sink identifying the AV stream. */ 
    Sink    media_sink;   
} A2DP_CLOSE_CFM_T;

/*!
 @brief This message informs the application that the connection has been
 closed.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP    *a2dp;    
 /*! The current A2DP status. */
 a2dp_status_code result;    
 /*! Sink identifying the AV stream. */ 
 Sink    media_sink;   
} A2DP_CLOSE_IND_T;

/*!
 @brief This message is generated as the result of a call to A2dpStart.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP    *a2dp;    
 /*! The current A2DP status. */
 a2dp_status_code result;    
 /*! Sink identifying the AV stream. */ 
    Sink    media_sink;   
} A2DP_START_CFM_T;

/*!
 @brief The message informs the application that the remote device has
 started streaming media.
*/
typedef struct
{
    A2DP  *a2dp;    /*!< Pointer to A2DP profile instance. */
   Sink  media_sink;   /*!< Sink identifying the AV stream. */ 
} A2DP_START_IND_T;

/*!
 @briefThis message returns the result of an A2dpSuspend request.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP    *a2dp;   
 /*! The current A2DP status. */
 a2dp_status_code result;   
 /*! Sink identifying the AV stream. */ 
    Sink    media_sink;  
} A2DP_SUSPEND_CFM_T;

/*!
 @brief This message informs the application that the media streaming has
 been suspended.
*/
typedef struct
{
    A2DP  *a2dp;   /*!< Pointer to A2DP profile instance. */
    Sink  media_sink;  /*!< Sink identifying the AV stream. */ 
} A2DP_SUSPEND_IND_T;

/*!
 @brief This message indicates what the app should configure the local
 codec.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP    *a2dp;    
 /*! The sampling rate for the PCM hardware. */
 uint32        rate;    
 /*! The channel mode for the audio being streamed. */
 a2dp_channel_mode channel_mode;  
 /*! Type of codec being used. This is for informational purposes only */
 a2dp_sep_type  sep_type;   
} A2DP_CODEC_SETTINGS_IND_T;

/*!
 @brief This message indicates to the client that the a2dp signalling
    channel has been opened.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP   *a2dp; 
 /*! Sink identifying the A2DP signalling channel. */
 Sink  sink;
} A2DP_SIGNALLING_OPEN_IND_T;

/*!
 @brief This message indicates to the client that the a2dp signalling
    channel has been closed.
*/
typedef struct
{
 /*! Pointer to A2DP profile instance. */
    A2DP   *a2dp; 
 /*! Sink identifying the A2DP signalling channel. */
 Sink  sink;
 /*! The current A2DP status. */
 a2dp_status_code result;
} A2DP_SIGNALLING_CLOSE_IND_T;

/* Define the downstream A2DP functional API */

/*!
 @brief Initialise the A2DP library. 
 
 @param theAppTask The current application task.
 @param config A2DP configuration parameters.

 This will initialise an A2DP library and the underlying GAVDP library
 depending upon the role specified within the Configuration parameters. A
 stream endpoint as described in the configuration will be added to the
 local database.  This function also takes care of registering a service
 record for an A2DP device.

 A2DP_INIT_CFM message will be received indicating the result of the request
 to initialise the library.
 

 No further library functions should be called until the A2DP_INIT_CFM
 message has been received.
 
 The Class of Device is not configured within the A2DP library, this is left
 to the application.  This is because only the application has device wide
 knowledge.
*/
void A2dpInit(Task theAppTask, const a2dp_init_params *config);

 
/*!
 @brief Add a Stream Endpoint to the local database.
 
 @param a2dp The profile instance which will be used. 
    @param config The SEP configuration properties and the service capability
    parameters are parsed and recorded.  Providing there are resources to store
    the configuration parameters and the service capabilities are valid an
    A2DP_ADD_SEP_CFM will be sent to the specified task with a successful
    status code.
    @param codec Specifies the codec type for the SEP being registered. The
    A2DP library will check if it has a DSP decoder file for this codec and if
    it does not have one it will return an error to the application otherwise
    it will proceed with registering the SEP.

 A2DP_ADD_SEP_CFM message will be received by the application. 
*/
void A2dpAddSep(A2DP *a2dp, const a2dp_sep_config *config);

/*!
 @brief Call to initiate a media connection from a local SEP to a
 remote device.
 
 @param a2dp The profile instance which will be used.
 @param sep_type The SEP type we wish to use for this AV connection. Must be
 one of the SEPs previously registered.
 @param bd_addr The Bluetooth address of the remote device.

 A2DP_OPEN_CFM message will be received by the application.
*/
void A2dpOpen(const A2DP *a2dp, a2dp_sep_type sep_type, const bdaddr *bd_addr);

/*!
 @brief Call to CLOSE a media connection from a local SEP to a
 remote device.
 
 @param a2dp The profile instance which will be used.
 @param media_sink The sink identifying the AV stream.
 
 A2DP_CLOSE_CFM message will be received by the application. 
*/
void A2dpClose(const A2DP *a2dp, Sink media_sink);

/*!
 @brief Clean up all AV related connections to the local device.
 
 @param a2dp The profile instance which will be used.
 
 This function call is provided to allow the client to clean up all A2DP
 related connections currently established to the local device.  This means
 that all media and signalling channels currently opened will be
 disconnected.
*/
void A2dpCloseAll(const A2DP *a2dp);

/*!
 @brief Call to START streaming media from a currently OPEN or SUSPENDED
 media connection.
  
 @param a2dp The profile instance which will be used.
 @param media_sink The sink identifying the AV stream.

 A2DP_START_CFM message will be received by the application.
*/
void A2dpStart(const A2DP *a2dp, Sink media_sink);

/*!
 @brief Call to SUSPEND a streaming media connection.
 
 @param a2dp The profile instance which will be used.
 @param media_sink The sink identifying the AV stream.

 A2DP_SUSPEND_CFM message will be received by the application.
 
*/
void A2dpSuspend(const A2DP *a2dp, Sink media_sink);

/*!
 @brief Enable the audio (AV) codec.
 @param a2dp The profile instance which will be used.

 This is called by the client whenever it wants to enable the DSP and start
 encoding/ decoding the audio stream. The library will ensure the correct
 codec is loaded into the DSP and after configuring it correctly will start
 it. The codec can be disabled by calling A2dpAudioCodecDisable().
*/
void A2dpAudioCodecEnable(A2DP *a2dp, Sink media_sink);

/*!
 @brief Disable the audio (AV) codec.
 @param a2dp The profile instance which will be used.

 This is called by the client whenever it wants to disable the codec and
 stop encoding/ decoding the audio stream. The codec can be enabled by
 calling A2dpAudioCodecEnable();
*/
void A2dpAudioCodecDisable(A2DP *a2dp, Sink media_sink);

A2DP这个空结构体有什么作用