1 /*

     2 * Copyright (c) 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:

    15 *

    16 */

    17 #ifndef CXESTATEMACHINEBASE_H

    18 #define CXESTATEMACHINEBASE_H

    19 

    20 #include <QHash>

    21 #include <QString>

    22 #include "cxeerror.h"

    23 

    24 class CxeState;

    25 

    26 /**

    27 * CxeStateMachineBase is used as the base class for all finite state machines in the

    28 * engine. It's not a fully functional state machine in the sense that it does not provide any

    29 * mechanism for handling events that would trigged state changes. Instead,

    30 * it relies on the derived class to call setState() whenever the state

    31 * should change. The derived class should also provide a list of states

    32 * and allowed transitions so that CxeStateMachineBase can verify that each state

    33 * change is valid. A pure virtual function, handleStateChanged() should be

    34 * implemented by derived classes to handle notifing other interested objects about

    35 * the state change. This class cannot emit the signals itself, because it does not

    36 * derived from QObject and it handles all state IDs as plain integers instead of the

    37 * preferred class specific enumerations.

    38 *

    39 * CxeStateMachineBase does not derive from QObject to make easier for the engine

    40 * control implementation classes to derive from it. Additionally we avoid the overhead

    41 * brought by QObject.

    42 *

    43 * CxeStateMachineBase class is to be used for unit testing. Engine class should derive

    44 * from CxeStateMachine class.

    45 */

    46 

    47 class CxeStateMachineBase

    48 {

    49 public:

    50     /**

    51     * CxeStateMachine constructor.

    52     * @sa addState setInitialState

    53     * @param stateMachineName  Name for this state machine (used for debug prints)

    54     */

    55     CxeStateMachineBase(const char* stateMachineName);

    56     virtual ~CxeStateMachineBase();

    57 

    58 protected:

    59     /**

    60      * Add a new state to the machine. Takes ownership of state.

    61      *

    62      * @param state A CxeState object defining a name, ID, and allowed transitions for the

    63      * new state. The CxeState ID must be unique and not to contain overlapping bits with other

    64      * state ids, since bitwise AND operator is used for the state ids.

    65      * @return False if adding failed due to incorrect id.

    66      */

    67     virtual bool addState(CxeState *state);

    68 

    69     /**

    70      * Initiate a state transition from current state to a given state ID. In cases that

    71      * current state is same as the new state, method returns without doing anything. If the state

    72      * transition is invalid, this function return false.

    73      *

    74      * @param stateId State ID of the new state

    75      * @param error   Optional error code to be associated with the transition

    76      * @return False if state change fails. True if changing is allowed, or the current state is same

    77      * as the new state.

    78      */

    79     virtual bool setState(int stateId, int error = 0);

    80 

    81     /**

    82      * Set the initial state of the state machine. Can be called only once.

    83      * This method will panic, if initial state is unknown, or initial state has already

    84      * been set.

    85      *

    86      * @param stateId State ID for the initial state.

    87      * @return False if state to be set intial state is not known, or initial

    88      * state has already been set.

    89      */

    90     virtual bool setInitialState(int stateId);

    91 

    92     /**

    93      * Pure virtual function to be implemented by derived classes. Called when state changes.

    94      * The implementation should emit a signal informing interested parties of a state change.

    95      *

    96      * @param newStateId State ID for the new state

    97      * @param error      An error code associated with the state transition

    98      */

    99     virtual void handleStateChanged(int newStateId, CxeError::Id error) = 0;

   100 

   101     /**

   102      * Get current state ID. It is recommended for derived classes to create

   103      * a new method (typically called state()) which returns the current state ID

   104      * typecasted into a class specific enumeration.

   105      * @return Current state ID

   106      */

   107     int stateId() const;

   108 

   109     /**

   110      * Verify if a state transition is possible.

   111      * @param newStateId  State ID of the new state.

   112      * @return Whether state transition is possible.

   113      */

   114     bool verifyStateChange(int newStateId);

   115 

   116 private:

   117 

   118     //! Hash table of all states. stateId as key

   119     QHash<int, CxeState*> mStates;

   120 

   121     //! Current state

   122     int mStateId;

   123 

   124     //! Name of this state machine (for debug prints)

   125     QString mName;

   126 

   127 };

   128 

   129 #endif // CXESTATEMACHINEBASE_H

   130 

   131