/*
* 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