1 /*

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

    18 #ifndef CXESTATEMACHINEBASE_H

    19 #define CXESTATEMACHINEBASE_H

    20 

    21 #include <QHash>

    22 #include <QString>

    23 #include "cxeerror.h"

    24 

    25 class CxeState;

    26 

    27 /**

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

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

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

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

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

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

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

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

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

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

    38 * preferred class specific enumerations.

    39 *

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

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

    42 * brought by QObject.

    43 *

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

    45 * from CxeStateMachine class.

    46 */

    47 

    48 class CxeStateMachineBase

    49 {

    50 public:

    51     /**

    52     * CxeStateMachine constructor.

    53     * @sa addState setInitialState

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

    55     */

    56     CxeStateMachineBase(const char *stateMachineName);

    57     virtual ~CxeStateMachineBase();

    58 

    59 protected:

    60     /**

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

    62      *

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

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

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

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

    67      */

    68     virtual bool addState(CxeState *state);

    69 

    70     /**

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

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

    73      * transition is invalid, this function return false.

    74      *

    75      * @param stateId State ID of the new state

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

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

    78      * as the new state.

    79      */

    80     virtual bool setState(int stateId, CxeError::Id error = CxeError::None);

    81 

    82     /**

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

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

    85      * been set.

    86      *

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

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

    89      * state has already been set.

    90      */

    91     virtual bool setInitialState(int stateId);

    92 

    93     /**

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

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

    96      *

    97      * @param newStateId State ID for the new state

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

    99      */

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

   101 

   102     /**

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

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

   105      * typecasted into a class specific enumeration.

   106      * @return Current state ID

   107      */

   108     int stateId() const;

   109 

   110     /**

   111      * Verify if a state transition is possible.

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

   113      * @return Whether state transition is possible.

   114      */

   115     bool verifyStateChange(int newStateId);

   116 

   117 private:

   118 

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

   120     QHash<int, CxeState *> mStates;

   121 

   122     //! All states ORed together

   123     int mStateBitsUsed;

   124 

   125     //! Current state

   126     int mStateId;

   127 

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

   129     QString mName;

   130 

   131 };

   132 

   133 #endif // CXESTATEMACHINEBASE_H