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: M class definitions for Finite State Machine's (FSM's)

    15 * body, fsm (subautomaton) and state. 

    16 *

    17 */

    18 

    19 #ifndef M_MULTIFINITESTATEMACHINE_H

    20 #define M_MULTIFINITESTATEMACHINE_H

    21 

    22 

    23 #include <e32def.h>

    24 #include <e32cmn.h> 

    25 #include <e32des8.h>

    26 

    27 

    28 /**

    29  * Data type for FSM's states. Each implemented FSM has an enumeration

    30  * for state identifiers and enum value is assigned to a variable of 

    31  * this type so that FSM framework can handle value transparently.  

    32  */

    33 typedef TInt TFSMState;

    34 

    35 /**

    36  * Data type for FSM's identifications. Each implemented FSM body has an enumeration

    37  * for included FSMs and enum value is assigned to a variable of this type so that

    38  * FSM framework can handle value transparently.  

    39  */

    40 typedef TInt TFSMId;

    41 

    42 

    43 /**

    44  * Data type for Interface identifications. Every interface used by a FSM Body has to have

    45  * an unique identifier i.e enumeration constant of which value is assigned to a variable

    46  * of this type so that FSM framework can handle value transparently.  

    47  */

    48 typedef TInt TFSMInterfaceId;

    49 

    50 /**

    51  * Data type for Interface's event identifications. Every interface has to have unique

    52  * identifiers for its events i.e enumeration constant of which value is assigned to a variable

    53  * of this type so that FSM framework can handle value transparently.  

    54  */

    55 typedef TInt TFSMEventId;

    56 

    57 /**

    58  * Data type for FSM's main- and substate. Each implemented FSM has an enumeration

    59  * for main- an substate identifiers and enum values are assigned to a variable of 

    60  * this type so that FSM framework can handle values transparently.  

    61  */

    62 class TFSMMainAndSubState

    63     {

    64 public:

    65     inline TFSMMainAndSubState(): iMainState(0),iSubstate(0){};

    66     TFSMState iMainState;

    67     TFSMState iSubstate;

    68     };

    69 

    70 // FORWARD DECLARATIONS

    71 class MFSMState;

    72 class MFSMForBody;

    73 

    74 

    75 // CLASS DECLARATION

    76 

    77 /**

    78  *  Finite State Machine's body interface for its owner. Body can include 1 to n 

    79  *  state machines.

    80  *

    81  *  This callback interface has to be implemented by FSM body

    82  *  implementation class.

    83  *  @code

    84  *   ?good_class_usage_example(s)

    85  *  @endcode

    86  *

    87  *  @lib none.

    88  *  @since TB 9.2

    89  */

    90 NONSHARABLE_CLASS( MFSMBody )

    91     {

    92 public:

    93     virtual ~MFSMBody() {} // Destructor needed for ownership transfer

    94 

    95     /**

    96      * Function is called by host object to indicate that FSM can proceed to 

    97      * initial state and make necessary initialization actions.

    98      * 

    99      * @since TB 9.2

   100      * @param none. 

   101      * @return void.

   102      */

   103     virtual void Start() = 0;

   104 

   105 

   106     /**

   107      * Get the id of current state.

   108      *

   109      * @since TB 9.2

   110      * @param aFSMId FSM identification. 

   111      * @return TFSMState Current state identification.

   112      */

   113     virtual TFSMState CurrentStateID( TFSMId aFSMId = 0 ) = 0;

   114 

   115     /**

   116      * Function is called whenever an event that might have impact 

   117      * on the state machine occurs.

   118      *

   119      * @since TB 9.2

   120      * @param aFSMId FSM identification.

   121      * @param aInterfaceId Interface identification.

   122      * @param aEvent Event identification.

   123      * @return none.

   124      */

   125     virtual void Input

   126         (

   127         TFSMId aFSMId = 0,

   128         TFSMInterfaceId aInterfaceId = 0,

   129         TFSMEventId aEvent = 0      

   130         ) = 0;

   131 

   132     /**

   133      * Get the pointer of current state object.

   134      *

   135      * @since TB 9.2

   136      * @param aFSMId FSM identification. 

   137      * @return MFSMState* Current state's interface pointer.

   138      */

   139     virtual  MFSMState* CurrentState( TFSMId aFSMId = 0 ) = 0;

   140 

   141     /**

   142      * Get the name of current state.

   143      *

   144      * @since TB 9.2

   145      * @param aFSMId FSM identification. 

   146      * @return TPtrC Name of the current state.

   147      */

   148     virtual TPtrC CurrentStateName( TFSMId aFSMId = 0 ) = 0;

   149 

   150     /**

   151      * Get pointer of a given FSM.

   152      *

   153      * @since TB 9.2

   154      * @param aFSMId FSM identification. 

   155      * @return MFSMForBody Pointer of the identified FSM.

   156      */

   157     virtual MFSMForBody* GetFSM( TFSMId aFSMId = 0 ) = 0;

   158     

   159     /**

   160      * Get the ids of current main and substate id.

   161      *

   162      * @since TB 9.2

   163      * @param aFSMId FSM identification. 

   164      * @return TFSMMainAndSubState Current main- and substate ids.

   165      *         Substate id is zero if current state havent any substates.

   166      */

   167     virtual TFSMMainAndSubState CurrentMainAndSubstateIDs( TFSMId aFSMId = 0 ) = 0;

   168     };

   169 

   170 /**

   171  *  FSM's interface for its (owning) Body. 

   172  *

   173  *  This callback interface has to be implemented by FSM

   174  *  implementation class.

   175  *  @code

   176  *   ?good_class_usage_example(s)

   177  *  @endcode

   178  *

   179  *  @lib none

   180  *  @since TB 9.2

   181  */

   182 class MFSMForBody

   183     {

   184 public:

   185     virtual ~MFSMForBody() {} // Destructor needed for ownership transfer

   186 

   187     /**

   188      * Function is called by host object to indicate that FSM can proceed to 

   189      * initial state and make necessary initialization actions.

   190      * 

   191      * @since TB 9.2

   192      * @param none. 

   193      * @return void.

   194      */

   195     virtual void Start() = 0;

   196 

   197 

   198     /**

   199      * Get the FSM's Id.

   200      *

   201      * @since TB 9.2

   202      * @param none. 

   203      * @return TFSMId FSM identification.

   204      */

   205     virtual TFSMId FSMID() = 0;

   206 

   207     /**

   208      * Get the id of current state.

   209      *

   210      * @since TB 9.2

   211      * @param none. 

   212      * @return TFSMState Current state identification.

   213      */

   214     virtual TFSMState CurrentStateID() = 0;

   215 

   216     /**

   217      * Function is called whenever an event that might have impact 

   218      * on the state machine occurs.

   219      *

   220      * @since TB 9.2

   221      * @param aInterfaceId Interface identification.

   222      * @param aEvent Event identification.

   223      * @return none.

   224      */

   225     virtual void Input

   226         (

   227         TFSMInterfaceId aInterfaceId = 0,

   228         TFSMEventId aEvent = 0      

   229         ) = 0;

   230 

   231     /**

   232      * Get the pointer of current state object.

   233      *

   234      * @since TB 9.2

   235      * @param none. 

   236      * @return MFSMState* Current state's interface pointer.

   237      */

   238     virtual  MFSMState* CurrentState() = 0;

   239 

   240     /**

   241      * Get the name of current state.

   242      *

   243      * @since TB 9.2

   244      * @param none. 

   245      * @return TPtrC Name of the current state.

   246      */

   247     virtual TPtrC CurrentStateName() = 0;

   248 

   249     /**

   250      * Get the ids of current main and substate id.

   251      *

   252      * @since TB 9.2

   253      * @param none. 

   254      * @return TFSMMainAndSubState Current main- and substate ids.

   255      *         Substate id is zero if current state havent any substates.

   256      */

   257     virtual TFSMMainAndSubState CurrentMainAndSubstateIDs() = 0;

   258 

   259     };

   260 

   261 /**

   262  *  FSM's interface for its State. 

   263  *

   264  *  This callback interface has to be implemented by FSM

   265  *  implementation class.

   266  *  @code

   267  *   ?good_class_usage_example(s)

   268  *  @endcode

   269  *

   270  *  @lib none

   271  *  @since TB 9.2

   272  */

   273 class MFSMForState

   274     {

   275 public:

   276  

   277     virtual ~MFSMForState() {} // Destructor needed for ownership transfer

   278     

   279     /**

   280      * Function is called by  current state to indicate that FSM has to change

   281      * its state. Pervious state has performed necessary exit actions if any.

   282      *

   283      * @since TB 9.2

   284      * @param aNextState Next state where to transit. 

   285      * @return TBool True is transition valid. False if nextstate value invalid.

   286      */

   287     virtual TBool Transit( TFSMState aNextState ) = 0;

   288     

   289     };

   290 

   291 /**

   292  *  FSM's State interface. 

   293  *

   294  *  This callback interface has to be implemented by FSM state

   295  *  implementation class.

   296  *  @code

   297  *   ?good_class_usage_example(s)

   298  *  @endcode

   299  *

   300  *  @lib none

   301  *  @since TB 9.2

   302  */

   303 class MFSMState

   304     {

   305 public:

   306  

   307     virtual ~MFSMState() {} // Destructor needed for ownership transfer

   308  

   309     /**

   310      * Function is called when entering the state. State can perform

   311      * necessary entry actions if any.

   312      *

   313      * @since TB 9.2

   314      * @param none. 

   315      * @return void.

   316      */

   317     virtual void Enter() = 0;

   318 

   319     /**

   320      * Function is called by FSM Body whenever an event that might have 

   321      * impact on the state has been fired. Implementation has to found

   322      * out what event has occurred and decide whether it enforces

   323      * transition to another state.

   324      *

   325      * @since TB 9.2

   326      * @param aInterfaceId Interface identification.

   327      * @param aEvent Event identification.

   328      * @return none.

   329      */

   330     virtual void Input(

   331             TFSMInterfaceId aInterfaceId = 0,

   332             TFSMEventId aEvent = 0 

   333             ) = 0;

   334     /**

   335      * Function returns state's identification.

   336      *

   337      * @since TB 9.2

   338      * @param none. 

   339      * @return TFSMState State's identification.

   340      */

   341     virtual TFSMState Id() = 0;

   342 

   343     /**

   344      * Function returns state's name.

   345      *

   346      * @since TB 9.2

   347      * @param none. 

   348      * @return TPtrC Name of the state.

   349      */

   350     virtual TPtrC Name() = 0;

   351     

   352     /**

   353      * Function returns substate's identification.

   354      *

   355      * @since TB 9.2

   356      * @param none. 

   357      * @return TFSMState Substate's identification.

   358      */

   359     virtual TFSMState SubId() = 0;

   360 

   361     };

   362 

   363 

   364 #endif // M_MULTIFINITESTATEMACHINE_H