1 /*

     2 * Copyright (c) 2006-2007 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:    Provides functionality for DTMF decoding and playing.

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef __CDTMFPAYLOADFORMATREAD_H__

    22 #define __CDTMFPAYLOADFORMATREAD_H__

    23 

    24 //  INCLUDES

    25 #include <e32base.h>

    26 #include <mdaaudiotoneplayer.h>

    27 #include "rtpheader.h"

    28 #include "formatstatemachine.h"

    29 #include "dtmfpayloadformatdefs.h"

    30 #include "mccinternalcodecs.h"

    31 

    32 // FORWARD DECLARATIONS

    33 class MDataSource;

    34 class CDTMFPayloadDecoder;

    35 class TDTMFEventPayloadInfo;

    36 class TDTMFTonePayloadInfo;

    37 

    38 

    39 // CLASS DECLARATION

    40 

    41 /**

    42  *  Handles DTMF reading from RTP payload and playing out DTMFs.

    43  *  Supported DTMF payload format is telephone-event payload.

    44  *

    45  *  @lib mmccdtmfplformat.dll

    46  *  @since Series 60 3.2

    47  */

    48 class CDTMFPayloadFormatRead : public CPayloadFormatRead, 

    49                                public MPayloadFormatRead, 

    50                                public MMdaAudioToneObserver

    51     {

    52     public: // Constructors and destructor

    53         

    54         /**

    55          * Two-phased constructor.

    56          */

    57         static CDTMFPayloadFormatRead* NewL( MDataSource* aSource );

    58         

    59         /**

    60          * Destructor.

    61          */

    62         virtual ~CDTMFPayloadFormatRead();

    63 

    64     public: // New functions

    65         

    66         /**

    67          * Sets payload format to be used in DTMF decoding.

    68          *

    69          * @since   Series 60 3.2

    70          * @param   aPayloadFormat  Payload format assumed in RTP payload

    71          * @return  System wide error code

    72          */ 

    73         virtual TInt SetPayloadFormat( TDTMFPayloadFormat aPayloadFormat );

    74         

    75         /**

    76          * Indicates the RTP data source has filled the buffer.

    77          *

    78          * @since   Series 60 3.2

    79          * @param   aBuffer        The filled buffer

    80          * @param   aRtpHeader     RTP header relating to passed buffer

    81          */

    82         virtual void DataBufferFilledL( CMMFBuffer* aBuffer, 

    83                                     const TRtpRecvHeader& aRtpHeader );

    84 

    85     public: // Functions from CMMFFormatDecode

    86 

    87         /**

    88          * From CMMFFormatDecode. Tests whether a source

    89          * buffer can be created.

    90          *

    91          * @since   Series 60 3.2

    92          * @return  ETrue if a source buffer can be

    93          *          created. EFalse otherwise.

    94          */

    95         TBool CanCreateSourceBuffer();

    96 

    97         /**

    98          * From CMMFFormatDecode. Not applicable for DTMF payload formatter.

    99          *

   100          * @since   Series 60 3.2

   101          * @param   aMediaType  The UID of the media type

   102          * @return  The number of streams

   103          */

   104         TUint Streams( TUid aMediaType ) const;

   105 

   106         /**

   107          * From CMMFFormatDecode. Not applicable for DTMF payload format read.

   108          *

   109          * @since   Series 60 3.2

   110          * @param   aMediaType  The media type ID.

   111          * @return  The time interval for one frame, in microseconds.

   112          */

   113         TTimeIntervalMicroSeconds FrameTimeInterval( 

   114             TMediaId aMediaType ) const;

   115 

   116         /**

   117          * From CMMFFormatDecode. Not applicable for DTMF payload format read.

   118          *

   119          * @since   Series 60 3.2

   120          * @param   aMediaType  Media type ID.

   121          * @return  Duration of the sink clip.

   122          */

   123         TTimeIntervalMicroSeconds Duration( TMediaId aMediaType ) const;

   124 

   125         /**

   126          * From CMMFFormatDecode. Not used, because there is no need for data

   127          * exchange with DataPath. DTMF receiving and processing cycle is

   128          * managed by SourcePrimeL(), SourcePlayL(), SourcePauseL(),

   129          * SourceStopL() -methods.

   130          *

   131          * @since   Series 60 3.2

   132          * @param   aBuffer

   133          * @param   aConsumer

   134          * @param   aMediaId

   135          */

   136         void FillBufferL( CMMFBuffer* aBuffer,

   137                           MDataSink* aConsumer, 

   138                           TMediaId aMediaId );

   139 

   140         /**

   141          * From CMMFFormatDecode. Not used.

   142          *

   143          * @since   Series 60 3.2

   144          * @param   aMediaId

   145          * @param   aReference

   146          * @return  NULL or KErrNotSupported

   147          */

   148         CMMFBuffer* CreateSourceBufferL( TMediaId aMediaId, 

   149                                          TBool& aReference );

   150 

   151         /**

   152          * From CMMFFormatDecode. Gets the FourCC code for the 

   153          * specified media ID.

   154          *

   155          * @since   Series 60 3.2

   156          * @param   aMediaId     Media ID

   157          * @return  The source data type code.

   158          */

   159         TFourCC SourceDataTypeCode( TMediaId aMediaId );

   160         

   161         /**

   162          * Gets the data type code for the sink specified by the media ID.

   163          * Format decode may act in role of MDataSink.

   164          *

   165          * @since   Series 60 3.2

   166          * @param   aMediaId    Media ID

   167          * @return  The data sink type code

   168          */

   169         TFourCC SinkDataTypeCode( TMediaId aMediaId );        

   170         

   171         /**

   172          * Sets the source's priority settings.

   173          *

   174          * @since   Series 60 3.2

   175          * @param   aPrioritySettings   Source priority settings.

   176          */        

   177         void SetSourcePrioritySettings( 

   178             const TMMFPrioritySettings &aPrioritySettings );

   179 

   180     public:    

   181 

   182         /**

   183          * Configures payload format with format spesific parameters.

   184          * Leaves with KErrArgument if parameters are invalid.

   185          *

   186          * @since   Series 60 3.2

   187          * @param   aConfigParams   Configuration parameters

   188          */

   189         virtual void ConfigurePayloadFormatL( const TDesC8& aConfigParams );

   190         

   191     public: // From MDataSource

   192     

   193         /**

   194          * From MDataSource. Primes the source.

   195          *

   196          * @since   Series 60 3.2

   197          */

   198         void SourcePrimeL();

   199         

   200         /**

   201          * From MDataSource. Plays the source.

   202          *

   203          * @since   Series 60 3.2

   204          */        

   205         void SourcePlayL();

   206         

   207         /**

   208          * From MDataSource. Pauses the source.

   209          *

   210          * @since   Series 60 3.2

   211          */   

   212         void SourcePauseL();

   213         

   214         /**

   215          * From MDataSource. Stops the source.

   216          *

   217          * @since   Series 60 3.2

   218          */

   219         void SourceStopL();

   220         

   221         /**

   222          * From MDataSource. Logs on the source thread.

   223          *

   224          * @since   Series 60 3.2

   225          * @param   aEventHandler   Used to send events back to the data path

   226          */

   227         TInt SourceThreadLogon( MAsyncEventHandler& aEventHandler );

   228         

   229         /**

   230          * From MDataSource. Logs off from the source thread.

   231          *

   232          * @since   Series 60 3.2

   233          */

   234         void SourceThreadLogoff( );

   235         

   236     public: // MPayloadFormatRead

   237         

   238         /**

   239          * Send decoded Events or Tones to further processing.

   240          * Called by the state machine.

   241          *

   242          * @since   Series 60 3.2

   243          */   

   244         void SendDataToSinkL();

   245         

   246         /**

   247          * Fill the sink buffer by decoding the RTP payload into

   248          * DTMF events or Tones. Called by the state machine.

   249          *

   250          * @since   Series 60 3.2

   251          */    

   252         void FillSinkBufferL();

   253         

   254         /**

   255          * Request the RTP source to fill the source buffer with RTP payload.

   256          * Source buffer is decided by the RTP source.

   257          * Called by the state machine.

   258          *

   259          * @since   Series 60 3.2

   260          */    

   261         void FillSourceBufferL();

   262 

   263         /**

   264          * From MPayloadFormatRead. Error notification if one of the

   265          * statechange callbacks leaved.

   266          *

   267          * @since   Series 60 3.2

   268          * @param   aError     Leave error code

   269          * @param   aState     State that caused the leave

   270          * @return  TInt       System wide error code from error handling

   271          */

   272         TInt HandleError( TInt aError, TFormatDecodeState aState );

   273 

   274     public: // From MMdaAudioToneObserver

   275     

   276         /**

   277          * From MMdaAudioToneObserver

   278          */

   279         void MatoPrepareComplete( TInt aError );

   280         

   281         /**

   282          * From MMdaAudioToneObserver

   283          */        

   284         void MatoPlayComplete( TInt aError );

   285 

   286     private:

   287 

   288         /**

   289          * C++ default constructor.

   290          */

   291         CDTMFPayloadFormatRead();

   292 

   293         /**

   294          * By default Symbian 2nd phase constructor is private.

   295          */

   296         void ConstructL( MDataSource* aSource );

   297         

   298         /**

   299          * Handle and play events using DevSound API.

   300          *

   301          * @since   Series 60 3.2

   302          */

   303         void HandleDTMFEventsL();

   304         

   305         /**

   306          * Handle and play tones using DevSound API.

   307          *

   308          * @since   Series 60 3.2

   309          */

   310         void HandleDTMFTones();

   311         

   312         /**

   313          * Creates a buffer used in data transfer between format read and

   314          * its datasource.

   315          *

   316          * @since    Series 60 3.2 

   317          * @return   void

   318          */

   319         void CreateClipBufferL();

   320         

   321         /**

   322          * Compares received RTP header to last received when marker bits are

   323          * set. Function returns ETrue if headers match so that only sequence

   324          * number is incremented in aRtpheader.

   325          *

   326          * @since S60 v3.2

   327          * @param aRtpheader RTP header to compare.

   328          * @return TBool ETrue if headers match.

   329          */

   330         TBool CompareFirstPacketRtpHeaders( const TRtpRecvHeader& aRtpheader );

   331 

   332     private: // Data

   333         

   334         /**

   335          * Pointer to format decoding state machine

   336          * Own.

   337          */        

   338         CFormatDecodeStateMachine* iStateMachine;

   339 

   340 // *** Relating to decoding functionality  *** //

   341         

   342         /**

   343          * Pointer to payload decoder

   344          * Own.

   345          */        

   346         CDTMFPayloadDecoder* iPayloadDecoder;

   347         

   348         /**

   349          * Pointer to buffer to hold payload got from data source

   350          */

   351         CMMFDataBuffer* iSourceBuffer;

   352         

   353         // Indicates whether payload read has ownership of source buffer

   354         TBool iSourceBufOwnership;

   355         

   356         /**

   357          * Indicates do we have payload buffer from data source

   358          */        

   359         TBool iBufferToReadExists;

   360         

   361         /**

   362          * Array containing Event Payload field values

   363          */        

   364         RArray<TDTMFEventPayloadInfo> iEventPayloadInfo;

   365         

   366         /**

   367          * Array containing Tone Payload field values

   368          */        

   369         RArray<TDTMFTonePayloadInfo> iTonePayloadInfo;

   370         

   371         /**

   372          * Current event ongoing. Needed for final packet loss detection.

   373          */

   374         TChar iCurrentEvent;

   375         

   376         /**

   377          * Info about is M(arker) bit set in a RTP packet

   378          */        

   379         TBool iFirstPacket;

   380         

   381         /**

   382          * Time stamp of previous event

   383          */        

   384         TTimeIntervalMicroSeconds32 iTimeStampOfPrevEvent;

   385         

   386         /**

   387          * Payload format (Event, Tone) used in RTP packets

   388          */        

   389         TDTMFPayloadFormat iPayloadFormat;

   390                 

   391 // *** Relating to DTMF playback *** //

   392 

   393         /**

   394          * Pointer to tone player for local/inband DTMF playing

   395          * Own.

   396          */        

   397         CMdaAudioToneUtility* iTonePlayer;

   398 

   399         /**

   400          * Parameters relating to RTP data encoding

   401          */        

   402         TMccCodecInfo iCInfo;

   403         

   404         /**

   405          * Receive header from previous packet.

   406          */

   407         TRtpRecvHeader iReceivedHeader;

   408 

   409     private: // Friend classes

   410         

   411         #ifdef TEST_EUNIT

   412             friend class UT_CDTMFPayloadFormatRead;

   413         #endif

   414 

   415     };

   416 

   417 #endif      // __CDTMFPAYLOADFORMATREAD_H__

   418 

   419 // End of File