/*

* 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 volume state machine

*

*/

#ifndef C_UPNPVOLUMESTATEMACHINE_H

#define C_UPNPVOLUMESTATEMACHINE_H

// INCLUDES

#include <e32base.h>

#include "upnprenderingstatemachineconstants.h"

// FORWARD DECLARATIONS

class MUPnPAVRenderingSession;

class MUpnpVolumeStateMachineObserver;

// CONSTANTS

const TInt KVolumeMin = 0;

const TInt KVolumeMax = 100;

const TInt KMuteOff = 0;

const TInt KMuteOn = 1;

class TUpnpVSMQueueItem

    {

public:

    enum TPropertyType

        {

        EVolume,

        EMute

        };

public:

    TUpnpVSMQueueItem( const TUpnpVSMQueueItem::TPropertyType aProperty, 

        const TInt aValue );

public:

    TUpnpVSMQueueItem::TPropertyType Property() const;

    TInt Value() const;

private:

    const TUpnpVSMQueueItem::TPropertyType iProperty;

    const TInt iValue;

    };

/**

 * Class for handling renderer volume

 *

 * @lib upnpavcontrollerhelper.lib

 * @since S60 v3.2

 */

class CUpnpVolumeStateMachine 

    : public CBase

    {

public: // construction / destruction

    /**

     * static constructor

     *

     * @since Series 60 3.2

     * @param aSession session where to send volume events

     */

    IMPORT_C static CUpnpVolumeStateMachine* NewL(

        MUPnPAVRenderingSession& aSession );

    /**

     * Destructor

     *

     * @since Series 60 3.1

     */

    IMPORT_C virtual ~CUpnpVolumeStateMachine();

private: // construction, private part

    /**

     * static constructor

     */

    CUpnpVolumeStateMachine(

        MUPnPAVRenderingSession& aSession );

    void HandleVolumeResultInSyncState(

            TInt aError, TInt aVolumeLevel, TBool aActionResponse );

    void HandleUnsolicitedMuteEvent(

        TInt aError, TBool aMute, TBool aActionResponse );

    void HandleUnsolicitedMuteEventInIdle(

        TInt aError, TBool aMute, TBool aActionResponse );

    void NotifyObserver(TBool aMute);

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( MUpnpVolumeStateMachineObserver& aObserver );

    /**

     * removes the current observer

     */

    IMPORT_C void RemoveObserver();

    /**

     * Synchronises the state machine with the remote renderer

     * (updates cached volume and mute levels)

     * this is an aynchronous operation and calls back VolumeSyncReady()

     */

    IMPORT_C void SyncL();

    /**

     * Forces the state machine off sync

     * (clears cached volume and mute levels)

     */

    IMPORT_C void SetOffSync();

    /**

     * Checks if the state machine is synchronised

     * with the remote renderer

     */

    IMPORT_C TBool IsInSync() const;

    /**

     * Sets volume on the renderer.

     * This method is thread-safe, and checks limits automatically.

     * If trying to adjust volume when session is busy,

     * method will leave with KErrInUse.

     * If trying to adjust volume to an existing value,

     * method will call back immediately with KErrNone.

     * Example for increasing volume:

     *   v->SetVolumeL( v->Volume() + KDefaultVolumeResolution );

     * @param aVolume volume to set

     */

    IMPORT_C void SetVolumeL( TInt aVolume );

    /**

     * returns the current renderer volume level.

     * Note: this is not a network operation - returns a cached value

     * @return volume level

     */

    IMPORT_C TInt Volume() const;

    /**

     * Sets or unsets renderer mute state.

     * If trying to adjust volume when session is busy,

     * method will leave with KErrInUse.

     * If trying to adjust mute to a state to an existing state,

     * method will call back immediately with KErrNone.

     * example of toggling mute state:

     *    v->SetMuteL( !v->Mute() );

     * @param aMuteState either ETrue of EFalse to set mute on or off

     */

    IMPORT_C void SetMuteL( TBool aMuteState );

    /**

     * returns the current renderer muted state.

     * Note: this is not a network operation - returns a cached value

     * @return mute state

     */

    IMPORT_C TBool Mute() const;

    /**

     * Checks if the state machine is busy doing something.

     * If not, new requests can be put in.

     */

    IMPORT_C TBool IsBusy() const;

    /**

     * Tests if this renderer has volume and mute capability.

     * Calling volume handling methods 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 HasVolumeCapability() const;

    /**

     * Cancels any ongoing operation

     */

    IMPORT_C void Cancel();

    /**

     * Copies cached values from another instance

     */

    IMPORT_C void CopyValues( const CUpnpVolumeStateMachine& aOther );

public: // methods like in MUPnPRenderiongSessionObserver

    /**

     * @see MUPnPRenderiongSessionObserver

     * client of this state machine should forward the corresponding method

     * from the rendering session directly to this method

     */

    IMPORT_C void VolumeResult(

        TInt aError, TInt aVolumeLevel, TBool aActionResponse );

    /**

     * @see MUPnPRenderiongSessionObserver

     * client of this state machine should forward the corresponding method

     * from the rendering session directly to this method

     */

    IMPORT_C void MuteResult(

        TInt aError, TBool aMute, TBool aActionResponse );

private:

    void PushIntoQueueL( const TUpnpVSMQueueItem::TPropertyType aPropery,

        const TInt aValue);

    void CompressQueue();

    void ProcessNextQueuedProperty();

private: // data

    // Rendering session

    MUPnPAVRenderingSession&            iSession;

    // the observer (no ownership!)

    MUpnpVolumeStateMachineObserver*    iObserver;

    // volume state machine option flags

    TInt                                iOptions;

    // operation types

    enum TState

        {

        EOffSync,             // not synchronised

        ESyncing,             // synchronising the state machine

        EIdle,                // doing nothing

        EAdjustingVolume,     // adjusting volume

        EAdjustingMute,       // setting/unsetting mute

        EAdjustingVolumeToZero, // setting to mute due to volume==0

        EAdjustingVolumeFromZero, // adjusting volume up from muted state

        ECancelled            // operation being cancelled

        };

    //currently ongoing operation

    TState                              iState;

    // current renderer volume level

    TInt                                iCurrentVolume;

    // volume requested by client during mute state

    TInt                                iVolumeToSetAfterMute;

    // current renderer mute state

    TInt                                iCurrentMute;

    // in case mute is on, this flag is set if mute was by client request

    TBool                               iMuteRequestedByClient;

    // volume capability

    TBool                               iVolumeCapability;

    // mute capability (only used internally)

    TBool                               iMuteCapability;

    RArray<TUpnpVSMQueueItem>           iQueue; 

    // last changed volume level

    TInt                                iCachedVolume;

    // last changed mute

    TInt                                iCachedMute;

    };

#endif // C_UPNPVOLUMESTATEMACHINE_H