accessoryservices/pluggeddisplay/pluggeddisplayengine/inc/multifinitestatemachine.h
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/accessoryservices/pluggeddisplay/pluggeddisplayengine/inc/multifinitestatemachine.h Tue Feb 02 00:53:00 2010 +0200
@@ -0,0 +1,364 @@
+/*
+* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: M class definitions for Finite State Machine's (FSM's)
+* body, fsm (subautomaton) and state.
+*
+*/
+
+#ifndef M_MULTIFINITESTATEMACHINE_H
+#define M_MULTIFINITESTATEMACHINE_H
+
+
+#include <e32def.h>
+#include <e32cmn.h>
+#include <e32des8.h>
+
+
+/**
+ * Data type for FSM's states. Each implemented FSM has an enumeration
+ * for state identifiers and enum value is assigned to a variable of
+ * this type so that FSM framework can handle value transparently.
+ */
+typedef TInt TFSMState;
+
+/**
+ * Data type for FSM's identifications. Each implemented FSM body has an enumeration
+ * for included FSMs and enum value is assigned to a variable of this type so that
+ * FSM framework can handle value transparently.
+ */
+typedef TInt TFSMId;
+
+
+/**
+ * Data type for Interface identifications. Every interface used by a FSM Body has to have
+ * an unique identifier i.e enumeration constant of which value is assigned to a variable
+ * of this type so that FSM framework can handle value transparently.
+ */
+typedef TInt TFSMInterfaceId;
+
+/**
+ * Data type for Interface's event identifications. Every interface has to have unique
+ * identifiers for its events i.e enumeration constant of which value is assigned to a variable
+ * of this type so that FSM framework can handle value transparently.
+ */
+typedef TInt TFSMEventId;
+
+/**
+ * Data type for FSM's main- and substate. Each implemented FSM has an enumeration
+ * for main- an substate identifiers and enum values are assigned to a variable of
+ * this type so that FSM framework can handle values transparently.
+ */
+class TFSMMainAndSubState
+ {
+public:
+ inline TFSMMainAndSubState(): iMainState(0),iSubstate(0){};
+ TFSMState iMainState;
+ TFSMState iSubstate;
+ };
+
+// FORWARD DECLARATIONS
+class MFSMState;
+class MFSMForBody;
+
+
+// CLASS DECLARATION
+
+/**
+ * Finite State Machine's body interface for its owner. Body can include 1 to n
+ * state machines.
+ *
+ * This callback interface has to be implemented by FSM body
+ * implementation class.
+ * @code
+ * ?good_class_usage_example(s)
+ * @endcode
+ *
+ * @lib none.
+ * @since TB 9.2
+ */
+NONSHARABLE_CLASS( MFSMBody )
+ {
+public:
+ virtual ~MFSMBody() {} // Destructor needed for ownership transfer
+
+ /**
+ * Function is called by host object to indicate that FSM can proceed to
+ * initial state and make necessary initialization actions.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return void.
+ */
+ virtual void Start() = 0;
+
+
+ /**
+ * Get the id of current state.
+ *
+ * @since TB 9.2
+ * @param aFSMId FSM identification.
+ * @return TFSMState Current state identification.
+ */
+ virtual TFSMState CurrentStateID( TFSMId aFSMId = 0 ) = 0;
+
+ /**
+ * Function is called whenever an event that might have impact
+ * on the state machine occurs.
+ *
+ * @since TB 9.2
+ * @param aFSMId FSM identification.
+ * @param aInterfaceId Interface identification.
+ * @param aEvent Event identification.
+ * @return none.
+ */
+ virtual void Input
+ (
+ TFSMId aFSMId = 0,
+ TFSMInterfaceId aInterfaceId = 0,
+ TFSMEventId aEvent = 0
+ ) = 0;
+
+ /**
+ * Get the pointer of current state object.
+ *
+ * @since TB 9.2
+ * @param aFSMId FSM identification.
+ * @return MFSMState* Current state's interface pointer.
+ */
+ virtual MFSMState* CurrentState( TFSMId aFSMId = 0 ) = 0;
+
+ /**
+ * Get the name of current state.
+ *
+ * @since TB 9.2
+ * @param aFSMId FSM identification.
+ * @return TPtrC Name of the current state.
+ */
+ virtual TPtrC CurrentStateName( TFSMId aFSMId = 0 ) = 0;
+
+ /**
+ * Get pointer of a given FSM.
+ *
+ * @since TB 9.2
+ * @param aFSMId FSM identification.
+ * @return MFSMForBody Pointer of the identified FSM.
+ */
+ virtual MFSMForBody* GetFSM( TFSMId aFSMId = 0 ) = 0;
+
+ /**
+ * Get the ids of current main and substate id.
+ *
+ * @since TB 9.2
+ * @param aFSMId FSM identification.
+ * @return TFSMMainAndSubState Current main- and substate ids.
+ * Substate id is zero if current state havent any substates.
+ */
+ virtual TFSMMainAndSubState CurrentMainAndSubstateIDs( TFSMId aFSMId = 0 ) = 0;
+ };
+
+/**
+ * FSM's interface for its (owning) Body.
+ *
+ * This callback interface has to be implemented by FSM
+ * implementation class.
+ * @code
+ * ?good_class_usage_example(s)
+ * @endcode
+ *
+ * @lib none
+ * @since TB 9.2
+ */
+class MFSMForBody
+ {
+public:
+ virtual ~MFSMForBody() {} // Destructor needed for ownership transfer
+
+ /**
+ * Function is called by host object to indicate that FSM can proceed to
+ * initial state and make necessary initialization actions.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return void.
+ */
+ virtual void Start() = 0;
+
+
+ /**
+ * Get the FSM's Id.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return TFSMId FSM identification.
+ */
+ virtual TFSMId FSMID() = 0;
+
+ /**
+ * Get the id of current state.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return TFSMState Current state identification.
+ */
+ virtual TFSMState CurrentStateID() = 0;
+
+ /**
+ * Function is called whenever an event that might have impact
+ * on the state machine occurs.
+ *
+ * @since TB 9.2
+ * @param aInterfaceId Interface identification.
+ * @param aEvent Event identification.
+ * @return none.
+ */
+ virtual void Input
+ (
+ TFSMInterfaceId aInterfaceId = 0,
+ TFSMEventId aEvent = 0
+ ) = 0;
+
+ /**
+ * Get the pointer of current state object.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return MFSMState* Current state's interface pointer.
+ */
+ virtual MFSMState* CurrentState() = 0;
+
+ /**
+ * Get the name of current state.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return TPtrC Name of the current state.
+ */
+ virtual TPtrC CurrentStateName() = 0;
+
+ /**
+ * Get the ids of current main and substate id.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return TFSMMainAndSubState Current main- and substate ids.
+ * Substate id is zero if current state havent any substates.
+ */
+ virtual TFSMMainAndSubState CurrentMainAndSubstateIDs() = 0;
+
+ };
+
+/**
+ * FSM's interface for its State.
+ *
+ * This callback interface has to be implemented by FSM
+ * implementation class.
+ * @code
+ * ?good_class_usage_example(s)
+ * @endcode
+ *
+ * @lib none
+ * @since TB 9.2
+ */
+class MFSMForState
+ {
+public:
+
+ virtual ~MFSMForState() {} // Destructor needed for ownership transfer
+
+ /**
+ * Function is called by current state to indicate that FSM has to change
+ * its state. Pervious state has performed necessary exit actions if any.
+ *
+ * @since TB 9.2
+ * @param aNextState Next state where to transit.
+ * @return TBool True is transition valid. False if nextstate value invalid.
+ */
+ virtual TBool Transit( TFSMState aNextState ) = 0;
+
+ };
+
+/**
+ * FSM's State interface.
+ *
+ * This callback interface has to be implemented by FSM state
+ * implementation class.
+ * @code
+ * ?good_class_usage_example(s)
+ * @endcode
+ *
+ * @lib none
+ * @since TB 9.2
+ */
+class MFSMState
+ {
+public:
+
+ virtual ~MFSMState() {} // Destructor needed for ownership transfer
+
+ /**
+ * Function is called when entering the state. State can perform
+ * necessary entry actions if any.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return void.
+ */
+ virtual void Enter() = 0;
+
+ /**
+ * Function is called by FSM Body whenever an event that might have
+ * impact on the state has been fired. Implementation has to found
+ * out what event has occurred and decide whether it enforces
+ * transition to another state.
+ *
+ * @since TB 9.2
+ * @param aInterfaceId Interface identification.
+ * @param aEvent Event identification.
+ * @return none.
+ */
+ virtual void Input(
+ TFSMInterfaceId aInterfaceId = 0,
+ TFSMEventId aEvent = 0
+ ) = 0;
+ /**
+ * Function returns state's identification.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return TFSMState State's identification.
+ */
+ virtual TFSMState Id() = 0;
+
+ /**
+ * Function returns state's name.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return TPtrC Name of the state.
+ */
+ virtual TPtrC Name() = 0;
+
+ /**
+ * Function returns substate's identification.
+ *
+ * @since TB 9.2
+ * @param none.
+ * @return TFSMState Substate's identification.
+ */
+ virtual TFSMState SubId() = 0;
+
+ };
+
+
+#endif // M_MULTIFINITESTATEMACHINE_H