/*
* Copyright (c) 2008 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:      Class for retrieving and selecting media renderers
*
*/






#ifndef C_UPNPVALUESTATEMACHINE_H
#define C_UPNPVALUESTATEMACHINE_H

// INCLUDES
#include <e32base.h>
#include <mpxplaybackframeworkdefs.h>

// FORWARD DECLARATIONS
class CUPnPMusicPlayer;
class MUPnPAVRenderingSession;



/**
 * Class for handling playback state machine functionality
 *
 * @lib upnpmusicplugins.lib
 * @since S60 v3.1
 */
class CUPnPValueStateMachine : public CBase
    {

public: // construction / destruction

    /**
     * Static 1st phase constructor
     *
     * @since Series 60 3.1
     * @param aParent the parent plugin instance
     * @param aRenderingSession for playback commands
     */
    static CUPnPValueStateMachine* NewL( 
        CUPnPMusicPlayer& aParent,
        MUPnPAVRenderingSession& aRenderingSession );

    /**
     * Destructor
     *
     * @since Series 60 3.1
     */
    virtual ~CUPnPValueStateMachine();

public: // datatypes used in this class
   
    /**
     * current type of operation
     */
    enum TOperationType
        {
        EOperationNone,     // no operation going on
        EOperationValue,    // value get
        EOperationSet,      // value set
        EOperationDurationQuery, // internal duration query
        EOperationPositionQuery, // internal position query
        EOperationVolumeQuery, // internal volume query
        EOperationMute // internal mute
        };

    /**
     * An internal operation class
     */
    class TOperation
        {
        public:
        /** construction */
        TOperation( TOperationType aType )
            : iType( aType ) {}
        TOperation( TOperationType aType, TInt aValue )
            : iType( aType )
            , iValue( aValue ) {}
        TOperation( TMPXPlaybackProperty aProperty, TInt aValue )
            : iType( EOperationSet )
            , iProperty( aProperty )
            , iValue( aValue ) {}
        TOperation( TMPXPlaybackProperty aProperty )
            : iType( EOperationValue )
            , iProperty( aProperty ) {}

        /** setters */
        void operator=( TOperationType aType )
            {
            iType = aType;
            }
        void Set( TMPXPlaybackProperty aProperty, TInt aValue )
            {
            iType = EOperationSet;
            iProperty = aProperty;
            iValue = aValue;
            }
        void Set( TMPXPlaybackProperty aProperty )
            {
            iType = EOperationValue;
            iProperty = aProperty;
            }
        void Reset()
            {
            iType = EOperationNone;
            }
        /** comparision */
        TBool operator==( TOperationType aType )
            {
            return ( iType == aType );
            }
        TBool Compare( TOperationType aType, TMPXPlaybackProperty aProperty )
            {
            return ( iType == aType && iProperty == aProperty );
            }
        TBool None()
            {
            return ( iType == EOperationNone );
            }
        /** identifies the operation type */
        TOperationType iType;
        /** playback property, if op == Value or Set */
        TMPXPlaybackProperty iProperty;
        /** playback property value, if op == Set */
        TInt iValue;
        };

    /**
     * A result of validation query.
     * Indicates what to do with a Value- or a Set- call
     */
    enum TValidationResult
        {
        EHandle, // handle the call in value state machine
        EHandleStatic, // handle the call statically in v.s.m.
        EErrorNotReady, // async error (KErrNotReady)
        EErrorNotSupported, // async error (KErrNotSupported)
        EIgnore // do absolutely nothing
        };

public: // services
    
   /**
    * A method to copy some static renderer-specific values from
    * another instance of a state machine. Note that one instance is
    * track specific, so track specific cached values are NOT copied,
    * (track duration etc.) but renderer specific values are copied
    * (volume etc)
    * @param aOther another instance to copy values from
    */
    void CopyValues( const CUPnPValueStateMachine& aOther );

   /**
    * See CMPXPlaybackPlugin
    */
    void SetL( TMPXPlaybackProperty aProperty, TInt aValue );

   /**
    * See CMPXPlaybackPlugin
    */
    void ValueL( TMPXPlaybackProperty aProperty );
    
   /**
    * See MUPnPRenderiongSessionObserver
    */
    void VolumeResult( TInt aError, TInt aVolumeLevel,
        TBool aActionResponse );
    
   /**
    * See MUPnPRenderiongSessionObserver
    */
    void MuteResult( TInt aError, TBool aMute, TBool aActionResponse );
    
   /**
    * See MUPnPRenderiongSessionObserver
    */
    void PositionInfoResult( TInt aStatus, const TDesC8& aTrackPosition,
        const TDesC8& aTrackLength );

    /**
     * Initiates a duration request, which will be reported to
     * the plugin observer as a change event
     */
    void DurationQueryL();
    
    /**
     * Initiates a position request
     */
    void PositionQueryL();

    /**
     * Initiates a volume request, which will be reported to
     * the plugin observer as a change event
     */
    void VolumeQueryL();

    /**
     * Initiates an internal mute request, which will not be reported.
     * @param aMute if other than zero, mute will be activated
     */
    void MuteRequestL( TInt aMute );

    /**
     * Validates a Value- or Set- call with given property in given
     * player state. There will be a result indicating what to do with
     * the call.
     * @param aProperty the property to be either get or set
     * @param aSetting true if setting the value, false if getting
     * @param aPlayerState state of the player plugin
     * @param aIsReady is remote device to gíve playback information
     * @return result of validation
     */
    static TValidationResult ValidatePropertyInState(
        TMPXPlaybackProperty aProperty,
        TBool aSetting,
        TInt aPlayerState,
        TBool aIsReady );

    /**
     * A static version of Value query - this one is capable of handling
     * some fixed Value queries that do not need network resources
     */
    static void ValueStatic(
         TMPXPlaybackProperty aProperty,
         MMPXPlaybackPluginObserver& aPlaybackObs );

    /**
     * Cancels any ongoing operation
     * (actually it just resets the state so the result will be ignored
     * and not reported)
     */
    void Cancel();

private:

    /**
     * Private default constructor
     *
     * @since Series 60 3.1
     * @param aParent the parent plugin instance
     * @param aRenderingSession for playback commands
     */
    CUPnPValueStateMachine( 
        CUPnPMusicPlayer& aParent,
        MUPnPAVRenderingSession& aRenderingSession );

    /**
     * Checks if operations are in the queue, and executes
     */
    void CheckOperationInQueueL();
    
    /**
     * Check if given property are in queue
     * @param aProperty property to be searched
     * @return Etrue if found
     */
    TBool FoundFromQueue( TMPXPlaybackProperty aProperty );

private: // data
        
    /**
     * Parent plugin instance
     */ 
    CUPnPMusicPlayer&                   iParent;
    
    /**
     * Rendering session
     */ 
    MUPnPAVRenderingSession&            iRendererSession;
    
    /**
     * currently ongoing operation
     */
    TOperation                          iCurrentOperation;

    /**
     * queue of operations pending
     */
    RArray<TOperation>                  iOperationQueue;

    /**
     * current renderer volume level.
     * cached internally to avoid unnecessary message traffic.
     */
    TInt                                iRendererVolume;

    /**
     * current renderer muted state (1 = muted, 0 = normal)
     * cached internally to avoid unnecessary message traffic.
     */
    TInt                                iRendererMuted;

    };


#endif // C_UPNPVALUESTATEMACHINE_H