1 /*

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

    15 *

    16 */

    17 

    18 

    19 #ifndef C_UPNPVOLUMESTATEMACHINE_H

    20 #define C_UPNPVOLUMESTATEMACHINE_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 

    25 #include "upnprenderingstatemachineconstants.h"

    26 

    27 // FORWARD DECLARATIONS

    28 class MUPnPAVRenderingSession;

    29 class MUpnpVolumeStateMachineObserver;

    30 

    31 // CONSTANTS

    32 const TInt KVolumeMin = 0;

    33 const TInt KVolumeMax = 100;

    34 const TInt KMuteOff = 0;

    35 const TInt KMuteOn = 1;

    36 

    37 

    38 class TUpnpVSMQueueItem

    39     {

    40     

    41 public:

    42     

    43     enum TPropertyType

    44         {

    45         EVolume,

    46         EMute

    47         };

    48     

    49 public:

    50     

    51     TUpnpVSMQueueItem( const TUpnpVSMQueueItem::TPropertyType aProperty, 

    52         const TInt aValue );

    53     

    54 public:

    55     

    56     TUpnpVSMQueueItem::TPropertyType Property() const;

    57     

    58     TInt Value() const;

    59     

    60 private:

    61     

    62     const TUpnpVSMQueueItem::TPropertyType iProperty;

    63           

    64     const TInt iValue;

    65     

    66     };

    67 

    68 

    69 /**

    70  * Class for handling renderer volume

    71  *

    72  * @lib upnpavcontrollerhelper.lib

    73  * @since S60 v3.2

    74  */

    75 class CUpnpVolumeStateMachine 

    76     : public CBase

    77     {

    78     

    79 public: // construction / destruction

    80 

    81     /**

    82      * static constructor

    83      *

    84      * @since Series 60 3.2

    85      * @param aSession session where to send volume events

    86      */

    87     IMPORT_C static CUpnpVolumeStateMachine* NewL(

    88         MUPnPAVRenderingSession& aSession );

    89 

    90     /**

    91      * Destructor

    92      *

    93      * @since Series 60 3.1

    94      */

    95     IMPORT_C virtual ~CUpnpVolumeStateMachine();

    96 

    97 private: // construction, private part

    98 

    99     /**

   100      * static constructor

   101      */

   102     CUpnpVolumeStateMachine(

   103         MUPnPAVRenderingSession& aSession );

   104     

   105     void HandleVolumeResultInSyncState(

   106             TInt aError, TInt aVolumeLevel, TBool aActionResponse );

   107     

   108     void HandleUnsolicitedMuteEvent(

   109         TInt aError, TBool aMute, TBool aActionResponse );

   110     

   111     void HandleUnsolicitedMuteEventInIdle(

   112         TInt aError, TBool aMute, TBool aActionResponse );

   113 

   114     void NotifyObserver(TBool aMute);

   115     

   116 

   117 public: // the interface

   118 

   119     /**

   120      * sets the state machine options (future extension)

   121      * @param aOptions options bit mask

   122      */

   123     IMPORT_C void SetOptions( TInt aOptions );

   124 

   125     /**

   126      * returns current options

   127      * @return the options bitmask

   128      */

   129     IMPORT_C TInt Options() const;

   130 

   131     /**

   132      * sets the state machine observer

   133      * @param aObserver the observer to set

   134      */

   135     IMPORT_C void SetObserver( MUpnpVolumeStateMachineObserver& aObserver );

   136 

   137     /**

   138      * removes the current observer

   139      */

   140     IMPORT_C void RemoveObserver();

   141 

   142     /**

   143      * Synchronises the state machine with the remote renderer

   144      * (updates cached volume and mute levels)

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

   146      */

   147     IMPORT_C void SyncL();

   148 

   149     /**

   150      * Forces the state machine off sync

   151      * (clears cached volume and mute levels)

   152      */

   153     IMPORT_C void SetOffSync();

   154 

   155     /**

   156      * Checks if the state machine is synchronised

   157      * with the remote renderer

   158      */

   159     IMPORT_C TBool IsInSync() const;

   160 

   161     /**

   162      * Sets volume on the renderer.

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

   164      * If trying to adjust volume when session is busy,

   165      * method will leave with KErrInUse.

   166      * If trying to adjust volume to an existing value,

   167      * method will call back immediately with KErrNone.

   168      * Example for increasing volume:

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

   170      * @param aVolume volume to set

   171      */

   172     IMPORT_C void SetVolumeL( TInt aVolume );

   173 

   174     /**

   175      * returns the current renderer volume level.

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

   177      * @return volume level

   178      */

   179     IMPORT_C TInt Volume() const;

   180 

   181     /**

   182      * Sets or unsets renderer mute state.

   183      * If trying to adjust volume when session is busy,

   184      * method will leave with KErrInUse.

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

   186      * method will call back immediately with KErrNone.

   187      * example of toggling mute state:

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

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

   190      */

   191     IMPORT_C void SetMuteL( TBool aMuteState );

   192 

   193     /**

   194      * returns the current renderer muted state.

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

   196      * @return mute state

   197      */

   198     IMPORT_C TBool Mute() const;

   199 

   200     /**

   201      * Checks if the state machine is busy doing something.

   202      * If not, new requests can be put in.

   203      */

   204     IMPORT_C TBool IsBusy() const;

   205 

   206     /**

   207      * Tests if this renderer has volume and mute capability.

   208      * Calling volume handling methods for a renderer that does not have

   209      * this capability wil result into an error.

   210      * @return ETrue if device has volume control capability.

   211      */

   212     IMPORT_C TBool HasVolumeCapability() const;

   213 

   214     /**

   215      * Cancels any ongoing operation

   216      */

   217     IMPORT_C void Cancel();

   218     

   219     /**

   220      * Copies cached values from another instance

   221      */

   222     IMPORT_C void CopyValues( const CUpnpVolumeStateMachine& aOther );

   223 

   224 public: // methods like in MUPnPRenderiongSessionObserver

   225 

   226     /**

   227      * @see MUPnPRenderiongSessionObserver

   228      * client of this state machine should forward the corresponding method

   229      * from the rendering session directly to this method

   230      */

   231     IMPORT_C void VolumeResult(

   232         TInt aError, TInt aVolumeLevel, TBool aActionResponse );

   233 

   234     /**

   235      * @see MUPnPRenderiongSessionObserver

   236      * client of this state machine should forward the corresponding method

   237      * from the rendering session directly to this method

   238      */

   239     IMPORT_C void MuteResult(

   240         TInt aError, TBool aMute, TBool aActionResponse );

   241 

   242 private:

   243     

   244     void PushIntoQueueL( const TUpnpVSMQueueItem::TPropertyType aPropery,

   245         const TInt aValue);

   246     

   247     void CompressQueue();

   248     

   249     void ProcessNextQueuedProperty();

   250 

   251 private: // data

   252 

   253     // Rendering session

   254     MUPnPAVRenderingSession&            iSession;

   255 

   256     // the observer (no ownership!)

   257     MUpnpVolumeStateMachineObserver*    iObserver;

   258 

   259     // volume state machine option flags

   260     TInt                                iOptions;

   261 

   262     // operation types

   263     enum TState

   264         {

   265         EOffSync,             // not synchronised

   266         ESyncing,             // synchronising the state machine

   267         EIdle,                // doing nothing

   268         EAdjustingVolume,     // adjusting volume

   269         EAdjustingMute,       // setting/unsetting mute

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

   271         EAdjustingVolumeFromZero, // adjusting volume up from muted state

   272         ECancelled            // operation being cancelled

   273         };

   274 

   275     //currently ongoing operation

   276     TState                              iState;

   277 

   278     // current renderer volume level

   279     TInt                                iCurrentVolume;

   280 

   281     // volume requested by client during mute state

   282     TInt                                iVolumeToSetAfterMute;

   283 

   284     // current renderer mute state

   285     TInt                                iCurrentMute;

   286 

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

   288     TBool                               iMuteRequestedByClient;

   289 

   290     // volume capability

   291     TBool                               iVolumeCapability;

   292 

   293     // mute capability (only used internally)

   294     TBool                               iMuteCapability;

   295     

   296     RArray<TUpnpVSMQueueItem>           iQueue; 

   297 

   298     // last changed volume level

   299     TInt                                iCachedVolume;

   300     

   301     // last changed mute

   302     TInt                                iCachedMute;

   303     };

   304 

   305 

   306 #endif // C_UPNPVOLUMESTATEMACHINE_H

   307