/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:    Provides functionality for DTMF digit encoding and sending.

*

*/

#ifndef CDTMFPAYLOADFORMATWRITE_H

#define CDTMFPAYLOADFORMATWRITE_H

//  INCLUDES

#include <e32base.h>

#include <mmf/server/mmfformat.h>

#include "rtpheader.h"

#include "mmccevents.h"

#include "dtmfpayloadformatdefs.h"

#include "mccinternalcodecs.h"

#include "dtmfencstatemachine.h"

#include "formatstatemachine.h"

// FORWARD DECLARATIONS

class CDTMFPayloadEncoder;

class MMccRtpDataSink;

class CMccRtpMediaClock;

class CDtmfHighResTimer;

// CLASS DECLARATION

/**

 * Handles DTMF encoding and passing to the RTP data sink.

 * Supported DTMF payload format is telephone-event payload.

 *

 * @lib mmccdtmfplformat.dll

 * @since Series 60 3.2

 */

class CDTMFPayloadFormatWrite : public CPayloadFormatWrite,

                                public MDtmfEncClient

    {

    public: // Constructors and destructor

        /**

         * Two-phased constructor.

         */

        static CDTMFPayloadFormatWrite* NewL( MDataSink* aSink );

        /**

         * Destructor.

         */

        virtual ~CDTMFPayloadFormatWrite();

    public: // New functions

        /**

         * Used to dispatch timer events from the timer to the class instance

         * being interested in receiving them.

         *

         * @since   Series 60 3.2

         * @param   aObjectPtr Pointer to object that wants 

         *          to receive timer events

         * @return  Non-zero value if current task is ongoing

         */

        static TInt HandleTimerEventL( TAny* aObjectPtr );

        /**

         * Start to packetize DTMF digit to the RTP packets and send them.

         *

         * @since   Series 60 3.2

         * @param   aTone           Digit user has pressed at UI

         */

        virtual void StartDTMFToneL( const TChar aTone );

        /**

         * Stop DTMF digit packetizing and sending.

         *

         * @since   Series 60 3.2

         */

        virtual void StopDTMFToneL();

        /**

         * Starts sending of passed DTMF string incrementally.

         *

         * @since   Series 60 3.2

         * @param   aTones          DTMF string to send

         */        

        virtual void SendDTMFTonesL( const TDesC8& aTones );

        /**

         * Start/Stop notify about stops ('w' char) in a DTMF string.

         *

         * @since   Series 60 3.2

         * @param   aFlag   ETrue to enable, EFalse to disable notify service

         */

        virtual void NotifyStopInDTMFString( TBool aFlag );

        /**

         * Continue DTMF string sending after stop in a string has been

         * encountered.

         *

         * @since   Series 60 3.2

         * @param   aContinue   Whether to continue string sending

         * @return  KErrNone

         */

        virtual TInt ContinueDTMFStringSending( TBool aContinue );

        /**

         * Cancel DTMF string sending.

         *

         * @since   Series 60 3.2

         */

        virtual void CancelDTMFStringSending();

        /**

         * Returns payload format used in DTMF encoding.

         *

         * @since   Series 60 3.2

         * @return  Payload format used in DTMF encoding

         */ 

        virtual TDTMFPayloadFormat PayloadFormat() const;

        /**

         * Sets payload format to be used in DTMF encoding.

         *

         * @since   Series 60 3.2

         * @param   aPayloadFormat Payload format to be used

         * @return  System wide error code

         */ 

        virtual TInt SetPayloadFormat( TDTMFPayloadFormat aPayloadFormat );

        /**

         * From MDtmfEncClient. Called when it's time to handle next digit

         * in sequence while sending DTMF string.

         *

         * @since   Series 60 3.2

         */

        void EncodeNextDigitL();

        /**

         * From MDtmfEncClient. Does actions belonging to tone on state.

         * Actions include DTMF event update packets sending.

         *

         * @since   Series 60 3.2

         * @param   aEntryToState  Indicates is this transition to state

         */

        void DoToneOnActionsL( TBool aEntryToState );

        /**

         * From MDtmfEncClient. Does actions belonging to tone off state.

         * Actions include DTMF event final packet sending and 

         * retransmissions. During DTMF string sending this state implements

         * wait activity before proceeding to send next digit in a string.

         *

         * @since   Series 60 3.2

         * @param   aEntryToState   Indicates is this transition to state

         * @return  void

         */

        void DoToneOffActionsL( TBool aEntryToState );

    public: // Functions from CMMFFormatEncode

        /**

         * From CMMFFormatEncode. Gets the time interval for one frame.

         *

         * @since   Series 60 3.2

         * @param   aMediaType      The media type ID

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

         */

        TTimeIntervalMicroSeconds FrameTimeInterval(

            TMediaId aMediaType ) const;

        /**

         * From CMMFFormatEncode. Gets the duration of the sink clip for the

         * specified media ID.

         *

         * @since   Series 60 3.2

         * @param   aMediaType      The media type ID

         * @return  Duration of the sink clip

         */

        TTimeIntervalMicroSeconds Duration( TMediaId aMediaType ) const;

        /**

         * From CMMFFormatEncode. Empty the given source buffer.

         *

         * @since   Series 60 3.2

         * @param   aBuffer    data buffer containing DTMF payload

         * @param   aSupplier  data source pointer

         * @param   aMediaId   contains the media type KUidMediaTypeAudio or

         *                     KUidMediaTypeVideo

         */

        void EmptyBufferL( CMMFBuffer* aBuffer, MDataSource* aSupplier,

            TMediaId aMediaId );

        /**

         * From CMMFFormatEncode. Called by the clip to indicate data has been

         * processed.

         *

         * @since   Series 60 3.2

         * @param   aBuffer    The emptied buffer.

         */

        void BufferEmptiedL( CMMFBuffer* aBuffer );

        /**

         * From CMMFFormatEncode. DTMF payload format write doesn't support

         * sink buffer creation.

         *

         * @since   Series 60 3.2

         * @return  EFalse

         */        

        TBool CanCreateSinkBuffer();

        /**

         * From CMMFFormatEncode. DTMF payload format write doesn't support

         * sink buffer creation.

         *

         * @since   Series 60 3.2

         * @param   aMediaId    contains the media type KUidMediaTypeAudio or

         *                      KUidMediaTypeVideo 

         * @param   aReference  value of False is returned to caller if sink 

         *                      buffer is created

         * @return  NULL

         */

        CMMFBuffer* CreateSinkBufferL( TMediaId aMediaId, TBool &aReference );

    public:     // Functions from MDataSink

        /**

         * From MDataSink. Passes prime transition to the RTP data sink.

         *

         * @since   Series 60 3.2

         */

        void SinkPrimeL();

        /**

         * From MDataSink. Passes play transition to the RTP data sink.

         *

         * @since   Series 60 3.2

         */

        void SinkPlayL();

        /**

         * From MDataSink. Passes pause transition to the RTP data sink.

         *

         * @since   Series 60 3.2

         */

        void SinkPauseL();

        /**

         * From MDataSink. Passes stop transition to the RTP data sink.

         *

         * @since   Series 60 3.2

         */

        void SinkStopL();

        /**

         * Log in to the sink thread - this funtion merely passes the

         * command to its sink clip data source object. The sink clip

         * object will handle the thread log on procedures.

         *

         * @since   Series 60 3.2

         * @param   aEventHandler   address of event handler

         * @return  error code returned by source clip

         */

        TInt SinkThreadLogon( MAsyncEventHandler& aEventHandler );

        /**

         * Log out of the sink thread - this funtion merely passes the command

         * to its sink clip data source object. The sink clip object will

         * handle the thread log off procedures.

         *

         * @since   Series 60 3.2

         */

        void SinkThreadLogoff();

        /**

         * Return the sink four CC code for the given media

         *

         * @since   Series 60 3.2

         * @param   aMediaId     contains the media type KUidMediaTypeAudio or

         *                       KUidMediaTypeVideo

         * @return  FourCC code for the mediaId

         */

        TFourCC SinkDataTypeCode( TMediaId aMediaId );

        /**

         * Set the sink data type to given four CC code for the given media

         *

         * @since   Series 60 3.2

         * @param   aSinkFourCC fourCC code

         * @param   aMediaId    contains the media type KUidMediaTypeAudio or

         *                      KUidMediaTypeVideo

         * @return  error code KErrNotSupported if invalid media ID, else

         *          return KErrNone

         */

        TInt SetSinkDataTypeCode( TFourCC aSinkFourCC, TMediaId aMediaId );

        /**

         * Sets the sink's priority settings.

         *

         * @since   Series 60 3.2

         * @param   aPrioritySettings    Sink priority settings.

         */

        void SetSinkPrioritySettings( const TMMFPrioritySettings& 

                                                        aPrioritySettings );

    public:    

        /**

         * Configures payload format with format spesific parameters and

         * sets RTP Media clock with which to synchronize DTMF sending.

         * Leaves with KErrArgument if parameters are invalid.

         *

         * @since   Series 60 3.2

         * @param   aConfigParams   Configuration parameters

         * @param   aRtpMediaClock  RTP media clock

         */

        virtual void ConfigurePayloadFormatL( const TDesC8& aConfigParams,

                                              CMccRtpMediaClock& aClock );

    protected:

        /**

         * Called when specified time interval has elapsed.

         *

         * @since   Series 60 3.2

         * @return  Non-zero value if current task is ongoing

         */

        TInt DoHandleTimerEventL();

    private:

        /**

         * C++ default constructor.

         */

        CDTMFPayloadFormatWrite();

        /**

         * By default Symbian 2nd phase constructor is private.

         */

        void ConstructL( MDataSink* aSink );

        /**

         * Prepare packet header and deliver the packet to the datasink.

         *

         * @since   Series 60 3.2

         * @param   aPayload    Payload to deliver to the datasink.

         * @param   aMarkerBit  Marker bit on/off status

         */ 

        void DeliverPacketL( CMMFDataBuffer& aPayload, TBool aMarkerBit );

        /**

         * Check that digits are valid DTMF.

         *

         * @since   Series 60 3.2

         * @param   aDigits     DTMF string to be checked

         * @return  ETrue if valid, otherwise EFalse

         */

        TBool IsValidDigits( const TDesC8& aDigits ) const;

        /**

         * Takes care of handling 'p' and 'w' chars in a DTMF string.

         *

         * @since   Series 60 3.2

         * @param   aChar       Control char to handle

         */        

        void HandleControlChar( const TChar& aChar );

        /**

         * Signaling about events to the client.

         *

         * @since   Series 60 3.2

         * @param   aEventType  Type of the event to send to a client

         */ 

        void SendEventSignalToClient( TMccDtmfEventType aEventType ) const;

        /**

         * Checks that digit is valid DTMF.

         *

         * @since   Series 60 3.2

         * @param   aDigit      Digit to check

         * @return  ETrue if valid, otherwise EFalse

         */

        TBool IsValidDigit( const TChar& aDigit ) const;

    private: // Data

        class TSendBufferElement

            {

        public:

            TSendBufferElement( const TChar& aDtmfTone, TUint32 aStartTime )

                :

                iTone( aDtmfTone ),

                iStartTimeInMs( aStartTime ),

                iStopTimeInMs( 0 )

                {

                }

            const TChar& Tone() const

                {

                return iTone;

                }

            TUint32 StartTime() const

                {

                return iStartTimeInMs;

                }

            TUint32 StopTime() const

                {

                return iStopTimeInMs;

                }

            void SetStopTime( TUint32 aStopTime )

                {

                iStopTimeInMs = aStopTime;

                }

            TUint Duration() const

                {

                if ( iStopTimeInMs < iStartTimeInMs )

                    {

                    // wrap around situation

                    const TUint32 KMaxUintValue( 0xFFFFFFFF );

                    return ( ( KMaxUintValue - iStartTimeInMs ) + iStopTimeInMs );

                    }

                else

                    {

                    return ( iStopTimeInMs - iStartTimeInMs );

                    }

                }

        private:

            TChar iTone;

            TUint32 iStartTimeInMs;

            TUint32 iStopTimeInMs;    

            };

        enum TDTMFSendingMode

            {

            EModeNotDefined = 0,

            EModeManual     = 1,

            EModeAutomatic  = 2

            };

        /**

         * The FourCC code for DTMF PayloadFormatWrite

         */ 

        TFourCC iFourCC;

        /**

         * Pointer to sink buffer that holds encoded DTMF / RTP payload

         * Own.

         */        

        CMMFDataBuffer* iSinkBuffer;

        /**

         * Pointer to formatter class for encoding of RTP payload

         * Own.

         */        

        CDTMFPayloadEncoder* iPayloadEncoder;

        /**

         * Timer used for event updates and incremental DTMF string send.

         * Own.

         */

        CDtmfHighResTimer* iSendTimer;

        /**

         * RTP header used for sending RTP packet

         */        

        TRtpSendHeader iRtpSendHeader;

        /**

         * Contains current duration of tone

         */        

        TUint16 iToneDuration;

        /**

         * Payload format used for encoding

         */        

        TDTMFPayloadFormat iPayloadFormat;

        /**

         * Send buffer for timed DTMF sending

         */

        RArray<TSendBufferElement> iSendBuffer;

        /**

         * Indicates is DTMF generated inbandly or outbandly

         */        

        TInt iGenerationMode;

        /**

         * Pointer to asynchronous event handler

         * Not own.

         */        

        MAsyncEventHandler* iEventHandler;

        /**

         * Boolean indicating is NotifyStopInDTMFString() request in force

         */        

        TBool iNotifyStopReq;

        /**

         * Contains valid DTMF digits

         */        

        RArray<TChar> iValidDigits;

        /**

         * Parameters relating to RTP data encoding

         */        

        TMccCodecInfo iCInfo;