1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This class implements the audio data sending behaviour 

    15 *                that is common to all codecs. 

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef __BTAUDIOSTREAMSENDER_H__

    22 #define __BTAUDIOSTREAMSENDER_H__

    23 

    24 #include <bluetooth/a2dpoptimisation.h>

    25 #include <bluetooth/a2dpoptimisationparams.h>

    26  

    27 #include "btaudiostreamer.h" 

    28 

    29 /**

    30  *  This class handles the sending of RTP frames on general level. 

    31  *

    32  *  This class takes care of all the operations related to an RTP frame that are 

    33  *  common to all formats. Such operations are e.g. timestamp handling and 

    34  *  frame sending. 

    35  *  

    36  *  The child classes of this are used for handling the encoder specific 

    37  *  frame handling. This class specifies and calls pure virtual methods that 

    38  *  must be implemented by an encoder specific child class. 

    39  *

    40  *  @lib btaudiostreamer.lib

    41  *  @since S60 v3.1 

    42  */

    43 NONSHARABLE_CLASS(CBTAudioStreamSender) : public CActive

    44     {

    45     public:

    46     static CBTAudioStreamSender* NewL(MBTAudioStreamSenderObserver& aObserver, RRtpSession& aSession);

    47     ~CBTAudioStreamSender();

    48 

    49     /**

    50      * A callback for registering with RTP API 

    51      *

    52      * @since S60 v3.1

    53      * @param aPtr  An pointer to an instance that handles the callback. 

    54      * @param aEvent Handle to the event that occurred. 

    55      * @return void. 

    56      */

    57     static void PacketSent(CBTAudioStreamSender* aPtr, const TRtpEvent& aEvent);

    58     /**

    59      * A callback for registering with RTP API 

    60      *

    61      * @since S60 v3.1

    62      * @param aPtr  An instance who handles the callback. 

    63      * @param aEvent Handle to the event that occurred. 

    64      * @return void. 

    65      */

    66     static void SendError(CBTAudioStreamSender* aPtr, const TRtpEvent& aEvent);

    67 

    68     /**

    69      * Method for actually handling the RTP API callbacks for sent packets. 

    70      *

    71      * @since S60 v3.1

    72      * @return void. 

    73      */

    74     virtual void DoPacketSent();

    75 

    76     /**

    77      * Method for actually handling the RTP API callback for send errors. 

    78      *

    79      * @since S60 v3.1

    80      * @return void. 

    81      */

    82     virtual void DoSendError();

    83 

    84     virtual TInt SetNewFrameLength(TUint aOutboundMTUSize, const TUint aFrameLength, const TUint aTargetBitrate);

    85 

    86     /**

    87      * This method prepares the Stream Sender for incoming audio buffers. 

    88      *

    89      * @since S60 v3.1

    90      * @param aOutboundMTUSize The MTU size for outgoing L2CAP link. 

    91      * @param aFrameLength  The length of one audio data frame. 

    92      * @return void. 

    93      */

    94     virtual void StartL(TUint aOutboundMTUSize, const TUint aFrameLength, const TUint aTargetBitrate);

    95 

    96     /**

    97      * This method contains the code for closing the RTP API and cleaning up. 

    98      *

    99      * @since S60 v3.1

   100      * @return void. 

   101      */

   102     virtual void Stop();

   103 

   104     /**

   105      * An implementation of the buffer handling method. 

   106      *

   107      * @since S60 v3.1

   108      * @param aBuffer contains the audio data frames. 

   109      * @param aTimestamp The timestamp of the audio data frames. 

   110      * @return a Symbian OS wide error code. 

   111      */

   112     virtual TInt SendThisBuffer(const TDesC8& aBuffer, TTimeIntervalMicroSeconds aTimestamp);

   113 

   114     protected: 

   115     void ConstructL();

   116     CBTAudioStreamSender(MBTAudioStreamSenderObserver& aObserver, RRtpSession& aSession);

   117 

   118     void RunL();

   119     void DoCancel();

   120 

   121     /**

   122      * A pure virtual method that must be implemented by the encoder specific child class. 

   123      * This method moves the audio frames from buffer to SendPacket in encoder specific way. 

   124      *

   125      * @since S60 v3.1

   126      * @param aBuffer contains the audio data frames. 

   127      * @return a Symbian OS wide error code. 

   128      */

   129     virtual TInt AddBufferToSendPacket(const TDesC8& aBuffer) = 0; 

   130 

   131     /**

   132      * A pure virtual method that must be implemented by the encoder specific child class. 

   133      * This method places a header to SendPacket in encoder specific way. 

   134      *

   135      * @since S60 v3.1

   136      * @param void. 

   137      * @return a Symbian OS wide error code. 

   138      */

   139     virtual TInt AddHeaderToSendPacket(TPtr8& aPayloadDesC) = 0; 

   140 

   141     /**

   142      * A pure virtual method that must be implemented by the encoder specific child class. 

   143      * This method handles the encoder specific operations that should be done after the packet 

   144      * has been sent. 

   145      *

   146      * @since S60 v3.1

   147      * @param void. 

   148      * @return a Symbian OS wide error code. 

   149      */

   150     virtual TInt PacketSendingCompleted(TPtr8& aPayloadDesC) = 0; 

   151 

   152     /**

   153      * A pure virtual method that must be implemented by the encoder specific child class. 

   154      * This method handles the encoder specific packet length calculation.  

   155      *

   156      * @since S60 v3.1

   157      * @param aOutboundMTUSize The MTU size for outgoing L2CAP link. 

   158      * @param aFrameLength  The length of one audio data frame. 

   159      * @return a Symbian OS wide error code. 

   160      */

   161     virtual TInt CalculatePacketLength(TUint aOutboundMTUSize, const TUint aFrameLength) = 0; 

   162 

   163     /**

   164      * A pure virtual method that must be implemented by the encoder specific child class. 

   165      * This method returns the maximum number of frames in one outgoing packet.  

   166      *

   167      * @since S60 Timebox 9.2

   168      * @return number of frames in one send packet. 

   169      */

   170     virtual TUint MaxFramesPerPacket() = 0; 

   171 

   172     /**

   173      * 

   174      * This method calculates the playing time of one frame in microseconds.

   175      * The result is encoder specific. 

   176      *

   177      * @since S60 Timebox 9.2

   178      * @param void. 

   179      * @return a duration of one frame. 

   180      */

   181     virtual TUint CalculateFrameDuration(const TUint aFrameLength, const TUint aTargetBitrate) = 0; 

   182 

   183 

   184     /**

   185      * A pure virtual method that must be implemented by the encoder specific child class. 

   186      * This method handles the encoder specific initialisation.  

   187      *

   188      * @since S60 v3.1

   189      * @param void. 

   190      * @return void. 

   191      */

   192     virtual TInt InitSender(RRtpSendPacket& aSendPacket, TPtr8& aPayloadDesC, const TUint aTargetBitrate) = 0; 

   193 

   194     /**

   195      * A pure virtual method that must be implemented by the encoder specific child class. 

   196      * This method adjusts the incoming timestamp if buffers don't fill the SendPacket exactly.  

   197      *

   198      * @since S60 v5.0

   199      * @param aTimestamp A 64 bit representation of the timestamp to adjust. This will change during the call. 

   200      * @return void. 

   201      */

   202 	virtual void AdjustTimestamp(TInt64 &aTimestamp) = 0; 

   203 

   204 

   205     private: 

   206     /**

   207      * An inline method that empties the received buffer. 

   208      * This method uses encoder specific inherited class to handles the encoder specific data.  

   209      * and then decides whether to send the data out or request for more data. 

   210      *

   211      * @since S60 v3.1

   212      * @param void. 

   213      * @return void. 

   214      */

   215     inline void ConsumeBuffer(); 

   216 

   217     /**

   218      * An inline method that switches to new sendpacket when the length of frame has changed. 

   219      * This method also initializes the sender to use the new packet. 

   220      *

   221      * @since S60 v3.1

   222      * @param void. 

   223      * @return void. 

   224      */

   225 		inline void SwitchToNewSendPacket(); 

   226 

   227     /**

   228      * An inline method that self completes this active object. 

   229      * The purpose of this is to set the data provider thread free 

   230      * and continue execution in this thread's context.  

   231      *

   232      * @since S60 v3.1

   233      * @param void. 

   234      * @return void. 

   235      */

   236     inline void ProceedToPacketSending(); 

   237 

   238     

   239     private: 

   240 

   241     /**

   242      * The possible states of the Streamer. 

   243      */

   244     enum TStreamerState

   245         {

   246         EStopped, 

   247         EBuffering,

   248         ESending, 

   249         EErrorSending 

   250         };

   251 

   252     /**

   253     * A2DP optimiser object that is needed for prioritising A2DP audio over other data. 

   254     */

   255    RA2dpOptimiser iA2DPOptimiser; 

   256 

   257    /**

   258     * This stores a reference to the observer of this class. 

   259     */

   260    MBTAudioStreamSenderObserver&    iObserver;

   261 

   262    /**

   263     * RTP session reference, needed for creating the SendSource. 

   264     */

   265    RRtpSession&    iRtpSession;

   266 

   267    /**

   268     * RRtpSendSoure is needed for SendPacket management. 

   269     */

   270    RRtpSendSource    iSendSrc;

   271 

   272    /**

   273     * This stores the timestamp which we must place in the header. 

   274     */

   275    TInt64 iTimestamp; 

   276 

   277     /**

   278      * This stores the timestamp which we must place in the header. 

   279      */

   280     TInt64 iAdjustedTimestamp; 

   281 

   282 

   283    /**

   284     * This stores the current state of the streamer. 

   285     */

   286    TStreamerState     iStreamerState; 

   287 

   288    /**

   289     * This stores a reference to the buffer until it has 

   290     * been emptied and can be given back to the audio adaptation. 

   291     */

   292    const TDesC8 *iBuffer; 

   293 

   294    /**

   295     * These assist with creating RTP payloads with proper header and content. 

   296     */

   297    RRtpSendPacket*   iCurrentSendPacket; 

   298    RRtpSendPacket*   iSpareSendPacket; 

   299    

   300    /**

   301     * A pointer to the send packet's contents. 

   302     * It is used to abstract away the container of the data. 

   303     */

   304     TPtr8            iPayloadDesC;

   305 

   306    /**

   307     * An instance of our thread. This is needed for self completing 

   308     * the requests, which forces the ActiveScheduler to call our RunL. 

   309     */

   310    RThread iThread; 

   311 

   312     /**

   313      * This stores the new framelength when the streaming parameters are changing. 

   314      */

   315     TInt iNewFrameLength; 

   316 

   317     /**

   318      * This stores the target bitrate. The reason for this is that it is not applied 

   319      * immediately, but after the current packet is sent. 

   320      */

   321     TUint iTargetBitrate; 

   322 

   323     /**

   324      * This tells if the frame length is changing. If it is, then we won't put 

   325      * frames of new length into the same packet with the old frames. 

   326      * After sending the old frames a new sendpacket is taken into use.   

   327      */

   328     TBool iChangingFrameLength; 

   329 		

   330     /**

   331      * This tells whether we should keep the previous timestamp or overwrite 

   332      * it with the most recent one. 

   333      */

   334     TBool     iKeepPreviousTimestamp; 

   335 

   336     /**

   337      * This tells whether we should keep moving data from buffer to an incoming frame. 

   338      * The value is set to ETrue when new frame arrives and when the buffer was completely consumed 

   339      * and sent, this value is set to EFalse. 

   340      */

   341     TBool     iNonprocessedDataInBuffer; 

   342 

   343     /**

   344      * This tells if the streaming optimiser service is available. 

   345      */

   346     TBool     iLinkOptimiserAvailable; 

   347 

   348     };

   349 

   350 #endif // __BTAUDIOSTREAMSENDER_H__