1 /*

     2 * Copyright (c) 2008 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:  Base class for application states.

    15 *

    16 */

    17 

    18 

    19 #ifndef T_LCVTSTATEBASE_H

    20 #define T_LCVTSTATEBASE_H

    21 

    22 #include <e32base.h>

    23 #include <mvtengsessioninfo.h>

    24 #include "mlcvtstatecontext.h"

    25 #include "mlcvtshutterobserver.h"

    26 #include "tlcvtstates.h"

    27 

    28 /**

    29 * Base class for application states related to application startup, normal

    30 * operation and shutdown. AppUi delegates decision making by forwarding

    31 * events/commands it receives to current state.

    32 * Not all event handlers declared by the base class are applicable in

    33 * all concrete states. All methods returning TEventResponse imply that it may

    34 * consume the event completely and caller should not process it further.

    35 *

    36 * It should be kept in mind that as new functionality is added to application,

    37 * state classes may need changes if e.g. handling of specific event should be

    38 * allowed in appUi. By default event handler in specific state may consume all

    39 * events. Note that in this context e.g. HandleCommandL is considered as an

    40 * event handler.

    41 *

    42 * @since S60 v3.2

    43 */

    44 class TLcVtStateBase : public MLcVtShutterObserver

    45     {

    46 public: // new functions

    47 

    48     /**

    49     * Return value from state's event handlers.

    50     */

    51     enum TEventResponse

    52         {

    53         /** Event was handled by a state and should

    54          *  not be further processed by caller.

    55          */

    56         EEventHandled,

    57         /** Event can be handled by caller. */

    58         EEventNotHandled

    59     };

    60 

    61     /**

    62     * Performs state dependent actions when phase 1 of

    63     * startup is completed.

    64     */

    65     virtual void LcVtStartupPhase1DoneL();

    66 

    67     /**

    68     * Performs state dependent actions when startup fails.

    69     */

    70     virtual void LcVtStartupFailedL();

    71 

    72     /**

    73     * Performs state dependent actions when phase 2 of

    74     * startup is completed.

    75     */

    76     virtual void LcVtStartupPhase2DoneL();

    77 

    78     /**

    79     * Handles completion of shutdown.

    80     */

    81     virtual void ShutdownDoneL();

    82 

    83     /**

    84     * Handles completion of an VT engine command.

    85     * @param aCommand completed command

    86     * @param aError error

    87     * @return event response, is caller allowed to handle event

    88     */

    89     virtual TEventResponse HandleVTCommandPerformedL(

    90         const TVtEngCommandId aCommand,

    91         const TInt aError );

    92 

    93     /**

    94     * Handles event from the engine.

    95     * @param aEvent

    96     * @return event response, is caller allowed to handle event

    97     */

    98     virtual TEventResponse HandleVtEventL( const TInt aEvent );

    99 

   100     /**

   101     * Handles command from the user (or application framework).

   102     * @param aCommand

   103     * @return event response, is caller allowed to handle event

   104     */

   105     virtual TEventResponse HandleCommandL( const TInt aCommand );

   106 

   107     /**

   108     * Performs state dependent actions for foreground change event.

   109     * @param aIsForeground foreground status passed from UI framework

   110     * @return ETrue if application should behave as in foreground

   111     */

   112     virtual TBool HandleForegroundChangedL( const TBool aIsForeground ) = 0;

   113 

   114     /**

   115     * Performs state dependent previous actions for foreground change event.

   116     * @param aIsForeground foreground status passed from UI framework

   117     * @return ETrue if application should behave as in foreground

   118     */

   119     virtual TBool PreHandleForegroundChangedL( const TBool aIsForeground ) = 0;

   120     

   121     /**

   122     * Performs state dependent actions for layout change.

   123     */

   124     //virtual void HandleLayoutChangedL();    

   125     

   126     /**

   127     * Sends DTMF tone if allowed by current state.

   128     * @param aTone DTMF tone to send

   129     */

   130     //virtual void StartDtmfTone( const TChar& aTone );

   131 

   132     /**

   133     * Stops DTMF tone if allowed by current state.

   134     */

   135     //virtual void StopDtmfTone();

   136 

   137     /**

   138     * Sets initial application state.

   139     * @param aCtx state context providing services to states

   140     * @param aUiStates ui states

   141     */

   142     static void SetInitialStateL(

   143         MLcVtStateContext& aCtx,

   144         TLcVtStates& aUiStates);

   145 

   146 public: // from MLcVtShutterObserver

   147 

   148     /**

   149     * Handles 'shutdown ready' event.

   150     */

   151     virtual void HandleShutdownReady();

   152     

   153 

   154 protected: // for concrete state classes

   155 

   156     /**

   157     * Destructor, for cleanup.

   158     */

   159     virtual ~TLcVtStateBase();

   160 

   161     /**

   162     * Performs entry action for a state.

   163     */

   164     virtual void OpenL() = 0;

   165 

   166     /**

   167     * Performs exit action for a state and deletes that state.

   168     */

   169     virtual void Close() = 0;

   170 

   171     /**

   172     * Sets current state.

   173     */

   174     void ChangeStateL( TLcVtStateBase& aNewState );

   175 

   176     /**

   177     * Sets transition to resetting state as cleanup item.

   178     */

   179     void CleanupResetPushL();

   180 

   181     /**

   182     * Starts shutdown when leave occurred.

   183     */

   184     static void TransitionToReset( TAny* aAny );

   185 

   186 

   187     /**

   188     * Ends the call if necessary and starts shutdown.

   189     * @return ETrue if shutdown started.

   190     */

   191     TBool CheckEndActiveCallL();

   192 

   193     /**

   194     * Returns engine session state.

   195     * @param aUpdate is state forced to update

   196     * @return session state

   197     */

   198     MVtEngSessionInfo::TSessionState SessionState(

   199         const TBool aUpdate ) const;

   200 

   201     /**

   202     * Delegates engine command execution to the state context.

   203     */

   204     template < typename T >

   205     inline void ExecuteEngineCommand(

   206         TInt aCommand, T& aParam );

   207 

   208     /**

   209     * Sets execution state.

   210     */

   211     void SetExecState( const TLcVtStates::TLcVtExecState aState );

   212 

   213 protected: // constructor

   214 

   215     // c++ constructor

   216     TLcVtStateBase( MLcVtStateContext& aCtx, TLcVtStates& aUiStates );

   217 

   218 

   219 private: // new functions

   220 

   221     /**

   222     * Updates applications lock state and sends to background if

   223     * the device is locked.

   224     */

   225     void HandleDeviceLockEventL( const TBool aDeviceIsLocked );

   226 

   227 protected: // data members

   228 

   229     // Context providing services to states

   230     MLcVtStateContext&  iCtx;

   231 

   232     // Various application specific state information

   233     TLcVtStates&        iUiStates;

   234 

   235     /** Prevents sending end call command to call handling if ETrue.

   236      *  It is not allowed when call clearing is network originated.

   237      */

   238     

   239     /**

   240      * shutdown request received

   241      */

   242     static TBool iShutdownRequested;

   243     

   244     };

   245 

   246 #include "tlcvtstatebase.inl"

   247 

   248 #endif // T_LCVTSTATEBASE_H