/*
* Copyright (c) 2007,2009 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:  Generic upnp remote rendering state machine
*
*/

#ifndef C_UPNPRENDERINGSTATEMACHINE_H
#define C_UPNPRENDERINGSTATEMACHINE_H

// INCLUDES
#include <e32base.h>
#include "upnpavrenderingsessionobserver.h" // TUPnPAVInteractOperation
#include "upnpresourceselector.h" // TUPnPSelectDefaultResource
#include "upnprenderingstatemachineconstants.h" // types
#include "upnprenderingoperationexecutor.h"

// FORWARD DECLARATIONS
class MUPnPAVRenderingSession;
class MUpnpRenderingStateMachineObserver;
class TUpnpRenderingOperation;
class CUpnpRenderingPlaytimeCalculator;
class CUpnpRenderingStateMachineStates;
class CUpnpRenderingOperationQueue;
class MUPnPResourceSelector;
class CUpnpItem;
class CPeriodic;

// CONSTANTS
const TInt KUriBuffer = 256;

/**
 * Class for handling renderer states
 *
 * @lib upnprenderingstatemachine.lib
 */
class CUpnpRenderingStateMachine
    : public CBase
    , public MUpnpRenderingOperationExecutor
    {
    
public: // construction / destruction

    /**
     * static constructor
     *
     * @param aSession session where to send volume events
     */
    IMPORT_C static CUpnpRenderingStateMachine* NewL(
        MUPnPAVRenderingSession& aSession );

    /**
     * Destructor
     */
    IMPORT_C virtual ~CUpnpRenderingStateMachine();

private: // construction, private part

    /**
     * static constructor
     */
    CUpnpRenderingStateMachine(
        MUPnPAVRenderingSession& aSession );

    /**
     * 2nd phase constructor
     */
    void ConstructL();

public: // the interface

    /**
     * sets the state machine options (future extension)
     * @param aOptions options bit mask
     */
    IMPORT_C void SetOptions( TInt aOptions );

    /**
     * returns current options
     * @return the options bitmask
     */
    IMPORT_C TInt Options() const;

    /**
     * sets the state machine observer
     * @param aObserver the observer to set
     */
    IMPORT_C void SetObserver( MUpnpRenderingStateMachineObserver& aObserver );

    /**
     * removes the current observer
     */
    IMPORT_C void RemoveObserver();

    /**
     * sets the resource selector for media to play
     * if not called, TUPnPSelectDefaultResource will be used.
     */
    IMPORT_C void SetResourceSelector( MUPnPResourceSelector& aSelector );

    /**
     * Synchronises the state machine with the remote renderer
     * (updates the state)
     * this is an aynchronous operation and calls back RendererSyncReady()
     */
    IMPORT_C void SyncL();

    /**
     * Forces the state machine off sync
     * (sets the cached state to OffSync)
     */
    IMPORT_C void SetOffSync();

    /**
     * Checks if the state machine is synchronised
     * with the remote renderer ie. in operation
     * @return ETrue if state machine is operational
     */
    IMPORT_C TBool IsInSync() const;

    /**
     * Executes a command on the renderer.
     * If a command is currently running, the command is queued.
     * see Upnp::TCommand on upnprenderingstatemachineconstants.h
     * @param aCommand the command to execute
     * @param aCommandParameter command-specific parameter
     * @param aMedia the media to be played (specific to PLAY command)
     */
    IMPORT_C void CommandL(
        Upnp::TCommand aCommand,
        TInt aCommandParameter = 0,
        const CUpnpItem* aMedia = NULL
        );

    /**
     * Checks if the state machine is busy executing a command
     * @return ETrue if the state machine is busy
     */
    IMPORT_C TBool IsBusy() const;

    /**
     * Cancels currently ongoing operation and cleans up the
     * queue of operations
     */
    IMPORT_C void Cancel();

    /**
     * returns the current renderer state
     * Note: this is not a network operation - returns a cached value
     * @return the renderer state
     */
    IMPORT_C Upnp::TState State() const;

    /**
     * returns current track duration.
     * Note: this is NOT a network operation - returns a cached value.
     * NOTE ALSO: The method only works in case ERenderingOptionAutoSyncPos
     * option is in use or ERenderingCommandSyncPos has been called to
     * synchronise the position/duration.
     * @return the current track duration, or -1 if it is not available
     */
    IMPORT_C TInt Duration() const;

    /**
     * returns current position within the track.
     * Note: this is NOT a network operation - returns the position within an
     * internal position timer. The timer can be calibrated with the renderer
     * position using ECalibrate command, after which the Position values are
     * again more accurate.
     * @return the current estimated position, or -1 if it is not available
     */
    IMPORT_C TInt Position() const;

    /**
     * Tests if this renderer has pause capability.
     * Requesting PAUSE for a renderer that does not have this capability
     * wil result into an error.
     * @return ETrue if device has volume control capability.
     */
    IMPORT_C TBool HasPauseCapability() const;

public: // methods like in MUPnPRenderingSessionObserver

    /**
     * @see MUPnPRenderiongSessionObserver
     * client of this state machine should forward the corresponding method
     * from the rendering session directly to this method
     */
    IMPORT_C void InteractOperationComplete(
        TInt aError, TUPnPAVInteractOperation aOperation );

    /**
     * @see MUPnPRenderiongSessionObserver
     * client of this state machine should forward the corresponding method
     * from the rendering session directly to this method
     */
    IMPORT_C void PositionInfoResult( 
        TInt aError, const TDesC8& aPosition, const TDesC8& aLength );

    /**
     * @see MUPnPRenderiongSessionObserver
     * client of this state machine should forward the corresponding method
     * from the rendering session directly to this method
     */
    IMPORT_C void SetURIResult( TInt aError );

    /**
     * @see MUPnPRenderiongSessionObserver
     * client of this state machine should forward the corresponding method
     * from the rendering session directly to this method
     */
    IMPORT_C void SetNextURIResult( TInt aError );

public: // internal methods for the state algorithms

    /**
     * Reports SynReady to observer
     */
    void ReportSyncReady( TInt aError,
        Upnp::TState aNewState );

    /**
     * Reports StateChanged to observers
     */
    void ReportStateChanged( TInt aError,
        Upnp::TState aNewState,
        TBool aActionResponse = ETrue,
        TInt aStateParam = 0 );

    /**
     * Reports PositionSync to observers
     */
    void ReportPositionSync( TInt aError,
        Upnp::TPositionMode aMode,
        TInt aDuration, TInt aPosition );

private: // data

    // Rendering session
    MUPnPAVRenderingSession&            iSession;

    // the observer (no ownership!)
    MUpnpRenderingStateMachineObserver* iObserver;

    // the current state
    Upnp::TState                        iState;

    // rendering state machine option flags
    TInt                                iOptions;

    // playtime calculator
    CUpnpRenderingPlaytimeCalculator*   iPlaytimeCalculator;
    
    // state when buffering started with 'set uri' request
    Upnp::TState                        iStateBeforeSetUri;

    
/**************************
 ** State machine states **
 **************************/
    
public: // Operation execution methods

    /**
     * from MUpnpRenderingOperationExecutor
     */
    TResult ExecuteOperationL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );

    /**
     * from MUpnpRenderingOperationExecutor
     */
    TResult ProcessOperationL(
        const TUpnpRenderingOperation& aOperation, TInt aEvent,
        TInt aError, const TAny* aParam1, const TAny* aParam2 );

    /**
     * from MUpnpRenderingOperationExecutor
     */
    void HandleAsyncError(
        const TUpnpRenderingOperation& aOperation, TInt aError );

    /**
     * processing events
     * used in context of the operation queue
     */
    enum TOperationEvents
        {
        EInteractOperationComplete,
        EPositionInfo,
        ESetUriResult,
        ETimeout
        };
    
private: // internal state machinery

    // these are all called from the operation queue.
    // in all below methods, aOperation is the currently ongoing operation.

    // executes an operation
    TResult ExecuteOperationSyncL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );
    TResult ExecuteOperationPlayL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );
    TResult ExecuteOperationStopL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );
    TResult ExecuteOperationPauseL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );
    TResult ExecuteOperationResumeL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );
    TResult ExecuteOperationRestartL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );
    TResult ExecuteOperationSeekL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );
    TResult ExecuteOperationCalibrateL(
        const TUpnpRenderingOperation& aOperation,
        const TUpnpRenderingOperation& aCurrent );
    TResult ExecuteOperationSetUriL(
            const TUpnpRenderingOperation& aOperation,
            const TUpnpRenderingOperation& aCurrent );

    // handles network events
    TResult ProcessPositionInfo(
        const TUpnpRenderingOperation& aOperation,
        TInt aError, const TDesC8& aPosition, const TDesC8& aLength );
    TResult ProcessSetURIResultL(
        const TUpnpRenderingOperation& aOperation, TInt aError );
    TResult ProcessAVEvents( 
            const TUpnpRenderingOperation& aOperation, 
            const TUPnPAVInteractOperation aIntOp,
            TInt aError );
    
protected: // internal

    // retrieves a resource from given media using the media selector
    const CUpnpElement& ResourceFromL( const CUpnpItem& aMedia );
    

    // user-defined resource selector (NOT OWNED!)
    MUPnPResourceSelector*              iSelector;

    // the default resource selector (used if not explicitly set by user)
    TUPnPSelectDefaultResource          iDefaultSelector;

    // currently playing HTTP URI
    TBuf8<KUriBuffer>                   iCurrentUri;
    
    
/***********
 ** Queue **
 ***********/
public: // methods

    /**
     * Count of operations in the queue
     * @return count of operations in the queue
     */
    TInt Size() const;

    /**
     * Checks if the queue is free for new operations
     * @return ETrue if new operation can be run immediately
     */
    TBool IsFree() const;

    /**
     * push operation to queue.
     * Don't even try to execute it at this stage.
     * @param aOperation the operation to be added
     */
    void PushL(
        const TUpnpRenderingOperation& aOperation );

    /**
     * push operation to queue and execute
     * @param aOperation the operation to be added
     */
    void PushAndExecuteL(
        const TUpnpRenderingOperation& aOperation );

    /**
     * executes the first operation in the queue
     * note: non-leaving version.
     * if the operation completes, continues recursively to next
     * until queue is empty
     */
    void Execute();

    /**
     * Processes an item in the queue with given data
     * if the operation completes, continues recursively to next
     * until queue is empty
     */
    void Process( TInt aEvent,
        TInt aError=0, const TAny* aParam1=NULL, const TAny* aParam2=NULL );
    
    /**
     * Finds and removes deprecated commands from queue.
     * E.g. If the last command is stop, then all other except the current 
     * (ongoing) and the stop command are removed.
     */
    void CompressQueueL();
    
    /**
     * removes all dup. commands but not the latest one and ongoing
     * 
     * @param aCommand commands to be removed from queue
     */
    void RemoveAllDublicateCommands( Upnp::TCommand aCommand );

public: // own methods

    /**
     * Returns currently ongoing operation. ENone, if queue empty
     * @return operation at first position
     */
    TUpnpRenderingOperation Current() const;


    /**
     * executes the current operation recursively
     * if the operation completes, continues recursively to next
     * until queue is empty
     */
    void ExecuteRecursivelyL();

    /**
     * executes an operation parallel to an ongoing operation
     */
    void ExecuteParallelL(
        const TUpnpRenderingOperation& aOperation );
    
private:
    
    void SetUriL( const TUpnpRenderingOperation& aOperation );
    
private:
    
    // the array that implements the queue
    RArray<TUpnpRenderingOperation>  iQueue;
    
    // Seek position to be used for playbacktimecalculator 
    // when seek is completed 
    TInt                             iSeekPostion;

    // Start timestamp for getting position; it is used to add 
    // half of the delay when get position request is made and 
    // when the response is received to avoid lag with the renderer  
    TTime                            iGetPositionStartMark;
    
    };


#endif // C_UPNPRENDERINGSTATEMACHINE_H