// Copyright (c) 2007-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:

// generic framework node state machine states

// 

//

/**

 @file

 @publishedPartner

 @released

*/

#ifndef SYMBIAN_MM_ACTIVITIES_H

#define SYMBIAN_MM_ACTIVITIES_H

#include <elements/mm_node.h>

#include <elements/mm_nodepeer.h>

#include <elements/mm_activities_internal.h>

#include <elements/nm_address_internal.h>

#include <elements/nm_signatures.h>

#ifdef _DEBUG

// Panic category for "absolutely impossible!" vanilla ASSERT()-type panics from this module

// (if it could happen through user error then you should give it an explicit, documented, category + code)

_LIT(KSpecAssert_ElemMeshMachActH, "ElemMeshMachActH");

#endif

//-=========================================================

//

// MACROS

//

//-=========================================================

/**

Declare and export a node activity.

@param name  The name of the activity, which will be used to put it into the node's activity map

@see DECLARE_NODEACTIVITY

*/

#define DECLARE_EXPORT_NODEACTIVITY( name ) \

	struct name \

		{ \

		IMPORT_C static const MeshMachine::TNodeActivity& Self(); \

		IMPORT_C static const NetStateMachine::TStateTriple& FirstTriple(); \

		static const MeshMachine::TNodeActivity iSelf; \

		static const NetStateMachine::TStateTriple iData[]; \

		};

/**

Declares a node activity. A node activity is a state machine. It contains multiple nodeactivity

entries, which respresent the states, transitions and forks of the state machine.

@param name  The name of the activity, which will be used to put it into the node's activity map

@see DEFINE_NODEACTIVITY

@see NODEACTIVITY_ENTRY

*/

#define DECLARE_NODEACTIVITY( name ) \

	struct name \

		{ \

		inline static const MeshMachine::TNodeActivity& Self() {return iSelf;} \

		inline static const NetStateMachine::TStateTriple& FirstTriple() {return iData[1];} \

		static const MeshMachine::TNodeActivity iSelf; \

		static const NetStateMachine::TStateTriple iData[]; \

		};

#ifdef SYMBIAN_TRACE_ENABLE

/**

Define and export a custom node activity.

@param id        Identifier for the activity

@param name      The name of the activity

@param msgtype   Message which will kickoff this activity

@param ctor      Constructor for the custom activity class

@see DEFINE_CUSTOM_NODEACTIVITY

*/

	#define DEFINE_EXPORT_CUSTOM_NODEACTIVITY( id, name, msgtype, ctor ) \

		EXPORT_C const MeshMachine::TNodeActivity& name :: Self() {return iSelf;} \

		EXPORT_C const NetStateMachine::TStateTriple& name :: FirstTriple() {return iData[1];} \

		const MeshMachine::TNodeActivity name :: iSelf = {id, msgtype::EId, msgtype::ERealm, name :: iData[1], &ctor, _S8(#name)}; \

		DEFINE_TRIPLES_TABLE( name :: iData )

/**

Define a custom node activity. A custom node activity is a node activity which defines its own

node activity class. This is used, for example, if the activity wishes to share some custom context

information between the states and transition in the activity.

Node activity class must derive from CNodeActivityBase.

@param id        Identifier for the activity

@param name      The name of the activity

@param msgtype   Message which will kickoff this activity

@param ctor      Constructor for the custom activity class

@see DEFINE_NODEACTIVITY

@see CNodeActivityBase

*/

	#define DEFINE_CUSTOM_NODEACTIVITY( id, name, msgtype, ctor ) \

		const MeshMachine::TNodeActivity name :: iSelf = {id, msgtype::EId, msgtype::ERealm, name :: iData[1], &ctor, _S8(#name)}; \

		DEFINE_TRIPLES_TABLE( name :: iData )

#else

/**

Define and export a custom node activity.

@param id        Identifier for the activity

@param name      The name of the activity

@param msgtype   Message which will kickoff this activity

@param ctor      Constructor for the custom activity class

@see DEFINE_CUSTOM_NODEACTIVITY

*/

	#define DEFINE_EXPORT_CUSTOM_NODEACTIVITY( id, name, msgtype, ctor ) \

		EXPORT_C const MeshMachine::TNodeActivity& name :: Self() {return iSelf;} \

		EXPORT_C const NetStateMachine::TStateTriple& name :: FirstTriple() {return iData[1];} \

		const MeshMachine::TNodeActivity name :: iSelf = {id, msgtype::EId, msgtype::ERealm, name :: iData[1], &ctor, NULL}; \

		DEFINE_TRIPLES_TABLE( name :: iData )

/**

Define a custom node activity. A custom node activity is a node activity which defines its own

node activity class. This is used, for example, if the activity wishes to share some custom context

information between the states and transition in the activity.

Node activity class must derive from CNodeActivityBase.

@param id        Identifier for the activity

@param name      The name of the activity

@param msgtype   Message which will kickoff this activity

@param ctor      Constructor for the custom activity class

@see DEFINE_NODEACTIVITY

@see CNodeActivityBase

*/

	#define DEFINE_CUSTOM_NODEACTIVITY( id, name, msgtype, ctor ) \

		const MeshMachine::TNodeActivity name :: iSelf = {id, msgtype::EId, msgtype::ERealm, name :: iData[1], &ctor, NULL}; \

		DEFINE_TRIPLES_TABLE( name :: iData )

#endif

/**

Define and declare a custom node activity

@param id        Identifier for the activity

@param name      The name of the activity

@param msgtype   Message which will kickoff this activity

@param ctor      Constructor for the custom activity class

@see DEFINE_CUSTOM_NODEACTIVITY

*/

#define DECLARE_DEFINE_CUSTOM_NODEACTIVITY( id, name, msgtype, ctor ) \

	DECLARE_NODEACTIVITY( name ) \

	DEFINE_CUSTOM_NODEACTIVITY( id, name, msgtype, ctor )

/**

Define and export node activity

@param id        Identifier for the activity

@param name      The name of the activity

@param msgtype   Message which will kickoff this activity

@see DEFINE_NODEACTIVITY

*/

#define DEFINE_EXPORT_NODEACTIVITY( id, name, msgtype ) \

	DEFINE_EXPORT_CUSTOM_NODEACTIVITY( id, name, msgtype, MeshMachine::CNodeActivityBase::NewL )

/**

Define the start of a node activity. There must be a matching @c NODEACTIVITY_END to close the

node activity.

The @c id is a unique identifier for the activity. It allows activities to be overridden in an

activity map. When deriving from an activity map, if you specify a node activity in your map

whose id is the same as one in the parent map, the one in the parent map with be overriden.

The @c name of the activity is used to add it to the activity map.

The @c msgtype is the type of message which will initiate this activity. This can be left as the

null message, in which case it will be the first state which decides whether to start the activity

or not.

@code

namespace ExampleActivity {

DEFINE_NODEACTIVITY(EFoobarActivity, SimpleFoobarActivity, TFoobar)

    FIRST_NODEACTIVITY_ENTRY(TAwaitingFoobar, TDoOneThingOrAnother)

	NODEACTIVITY_ENTRY(KDoOneThing, TDoTheThing, TAwaitingResponseToThing, TNoTag)

	NODEACTIVITY_ENTRY(KAnother, TDoTheOtherThing, TAwaitingResponseToThing, TNoTag)

	LAST_NODEACTIVITY_ENTRY(KNoTag, TDoFinalThing)

NODEACTIVITY_END()

} // end namespace ExampleActivity

@endcode

A node activity must start with either a @c FIRST_NODEACTIVITY_ENTRY or a @c SINGLE_NODEACTIVITY_ENTRY. In

the latter case there should be no other entries in the node activity.

The activity object (@c CNodeActivityBase) is only created once the second @c NODEACTIVITY_ENTRY is entered.

@param id        Identifier for the activity

@param name      The name of the activity

@param msgtype   Message which will kickoff this activity

@see DEFINE_ACTIVITY_MAP

*/

#define DEFINE_NODEACTIVITY( id, name, msgtype ) \

	DEFINE_CUSTOM_NODEACTIVITY( id, name, msgtype, MeshMachine::CNodeActivityBase::NewL )

/**

Define and declare a node activity

@param id        Identifier for the activity

@param name      The name of the activity

@param msgtype   Message which will kickoff this activity

@see DEFINE_ACTIVITY_MAP

*/

#define DECLARE_DEFINE_NODEACTIVITY( id, name, msgtype ) \

	DECLARE_DEFINE_CUSTOM_NODEACTIVITY( id, name, msgtype, MeshMachine::CNodeActivityBase::NewL )

/**

Define an entry in a node activity.

@param transitionTag     Condition on which the entry is entered

@param stateTransition   Transition to be executed

@param state             State to enter after

@param stateFork         Fork to decide which entry to enter next

@see DEFINE_NODEACTIVITY

*/

#define NODEACTIVITY_ENTRY( transitionTag, stateTransition, state, stateFork ) \

	STATE_TRIPLE_ENTRY( transitionTag, stateTransition, state, stateFork )

/**

Define the first entry in a node activity

@param firstState       Initial state of the activity

@param firstStateFork   Fork to decide which entry to enter next

@see DEFINE_NODEACTIVITY

*/

#define FIRST_NODEACTIVITY_ENTRY( firstState, firstStateFork ) \

	FIRST_TRIPLE_ENTRY( firstState, firstStateFork )

/**

Define a through entry. Through entries execute a transition but do not

enter a state. Instead they move onto the next entry in the node activity

using the @c stateFork to decide which entry this is.

@param transitionTag   Condition on which the entry is entered

@param stateTransition Transition to be executed

@param stateFork       Fork to decide which entry to enter next

*/

#define THROUGH_NODEACTIVITY_ENTRY( transitionTag, stateTransition, stateFork ) \

	THROUGH_TRIPLE_ENTRY( transitionTag, stateTransition, stateFork )

/**

Define the final entry in a node activity.

@param transitionTag  Condition on which the entry is entered

@param lastTransition Final transition to be executed

@see DEFINE_NODEACTIVITY

*/

#define LAST_NODEACTIVITY_ENTRY( transitionTag, lastTransition ) \

	LAST_TRIPLE_ENTRY( transitionTag, lastTransition )

/**

Define a single node activity entry. This is the first and last entry in any

node activity in which it is used.

@param state             Initial state of the activity

@param stateTransition   Transition to execute once the state is fulfilled

@see DEFINE_NODEACTIVITY

*/

#define SINGLE_NODEACTIVITY_ENTRY( stateTransition, state ) \

	STATE_TRIPLE_ENTRY( MeshMachine::KNoTag, stateTransition, state, MeshMachine::TNoTag )

/**

Define a routing node activity entry. Routing entries neither execute any

transition, nor wait in any state. These are useful only for redirecting the

path of execution in the state machine.

@param transitionTag  Condition on which the entry is entered

@param stateFork      Fork to decide the next transition to enter

*/

#define ROUTING_NODEACTIVITY_ENTRY( transitionTag, stateFork ) \

	THROUGH_TRIPLE_ENTRY( transitionTag, MeshMachine::TDoNothing, stateFork )

/**

Marks the end of a node activity.

@see DEFINE_NODEACTIVITY

*/

#define NODEACTIVITY_END() \

	TRIPLES_TABLE_END()

/**

Declare and export an activity map

@param map Name of the activity map

@see DECLARE_ACTIVITY_MAP

*/

#define DECLARE_EXPORT_ACTIVITY_MAP( map ) \

	struct map \

		{ \

		IMPORT_C static const MeshMachine::TNodeActivityMap& Self(); \

		static const MeshMachine::TNodeActivityMap iSelf; \

		static const MeshMachine::TNodeActivityMap::TStaticNodeActivity iData[]; \

		};

/**

Define and export the activity map

@param map Name of the activity map

@see DEFINE_ACTIVITY_MAP

*/

#define DEFINE_EXPORT_ACTIVITY_MAP( map ) \

	EXPORT_C const MeshMachine::TNodeActivityMap& map :: Self() {return iSelf;} \

	const MeshMachine::TNodeActivityMap map :: iSelf = {map :: iData[0]}; \

	const MeshMachine::TNodeActivityMap::TStaticNodeActivity map :: iData[] = {

/**

Declare an activity map.

For example,

@code

DECLARE_ACTIVITY_MAP(MyNodeActivityMap)

@endcode

This can then be passed into the constructor of a mesh machine node as follows.

@code

CMyMeshNode::CMyMeshNode(CConnectionProviderFactoryBase& aFactory)

    : CCoreConnectionProvider(aFactory, MyNodeActivityMap::Self())

	{

	...

@endcode

@param map Name of the activity map

*/

#define DECLARE_ACTIVITY_MAP( map ) \

	struct map \

		{ \

		inline static const MeshMachine::TNodeActivityMap& Self() {return iSelf;} \

		static const MeshMachine::TNodeActivityMap iSelf; \

		static const MeshMachine::TNodeActivityMap::TStaticNodeActivity iData[]; \

		}; \

/**

Define an activity map. An activity map is a collection of node activities. The activity map can be

based on another activity map or this macro can be used to define a standalone activity map.

Once defined an activity map can be passed into the constructor of a node, to define

what activities that node is capable of executing.

@code

DECLARE_DEFINE_ACTIVITY_MAP(MyNodeActivityMap)

	ACTIVITY_MAP_ENTRY(MyNodeActivities, MyFirstActivity)

	ACTIVITY_MAP_ENTRY(MyNodeActivities, MySecondActivity)

ACTIVITY_MAP_END_BASE(BaseActivities, BaseActivityMap)

@endcode

@param map Name of the activity map

@see ACTIVITY_MAP_END_BASE

@see ACTIVITY_MAP_END

*/

#define DEFINE_ACTIVITY_MAP( map ) \

	const MeshMachine::TNodeActivityMap map :: iSelf = {map :: iData[0]}; \

	const MeshMachine::TNodeActivityMap::TStaticNodeActivity map :: iData[] = {

/**

Define and declare an activity map.

@param map Name of the activity map

@see DEFINE_ACTIVITY_MAP

*/

#define DECLARE_DEFINE_ACTIVITY_MAP( map ) \

	DECLARE_ACTIVITY_MAP(map) \

	DEFINE_ACTIVITY_MAP(map)

/**

Create an entry in an activity map.

@param name_space Namespace of the activity

@param name       Name of the activity

@see DEFINE_ACTIVITY_MAP

*/

#define ACTIVITY_MAP_ENTRY( name_space, name ) &name_space::name::Self,

/**

Mark the end of an activity map. This macro should be used for standalone activity

maps.

@see DEFINE_ACTIVITY_MAP

*/

#define ACTIVITY_MAP_END() \

	NULL, \

	NULL \

	};

/**

Mark the end of an activity map. This macro should be used for an activity map based

on other activity maps.

@param name_space The namespace of the base map

@param base_map   The name of the base map

@see DEFINE_ACTIVITY_MAP

*/

#define ACTIVITY_MAP_END_BASE( name_space, base_map ) \

	NULL, \

	(MeshMachine::TNodeActivityMap::TStaticNodeActivity)&name_space::base_map::Self \

	};

namespace MeshMachine

{

/**

Base class for all node activity objects. Non custom node activities will use this by default.

**/

class CNodeActivityBase : public CBase,

                          public NetInterfaces::AApiExtBase,

                          protected NetStateMachine::ACore,

                          protected NetInterfaces::TInterfaceControl

	{

    friend class AMMNodeBase;

    friend class AContextStore; //to be able access NetStateMachine::ACore

    friend class AActivitySemaphore; //to be able access NetStateMachine::ACore

public:

	/**

	   Create a new activity. This should never be called by user code.

	   @param aActivitySig Context information about how the activity is to be started

	   @param aNode        The node to which this activity will belong.

	   @return A pointer to the new Activity base object. Ownership is transferred.

	*/

    IMPORT_C static CNodeActivityBase* NewL( const TNodeActivity& aActivitySig, AMMNodeBase& aNode );

	/**

	Get the @c id of the activity.

	   @return The activity id of the activity

	*/

	IMPORT_C virtual TUint16 ActivityId() const;

	/**

	   Remove an originator from the originator list.

	   @param aIndex Index of originator to remove

	*/

	IMPORT_C void RemoveOriginator(TInt aIndex);

	/**

	Check if the activity is running.

	   @return ETrue if the activity is still running, otherwise EFalse.

	*/

	IMPORT_C virtual TBool IsIdle() const;

	/**

	   Put the activity into the idle state. This stops the activity running and notifies the mesh machine that

	   it's ok to delete this activity.

	*/

	IMPORT_C virtual void SetIdle();

	/**

	   Return the activity signature id of the activity. This may not necessarily be the same as the activity id

	   in the case of parallel activities, where the activity id will be [8 bit unique id|8 bit activity sig]

	   @return The activity signature id

	*/

    TUint ActivitySigId() const

   		{

  		return iActivitySig.iId;

   		}

	/**

	Get the current error state for the activity.

	   @return The activity's current error state. @c KErrNone indicates there is no error.

	*/

	TInt Error() const

		{

		return iError;

		}

	/**

	   Set the error state of the activity.

	   @param aError error code to set

	*/

	void SetError(TInt aError)

		{

		if (iError == KErrNone || aError == KErrNone)

    		{

    		iError = aError;

    		};

		}

	/**

	Get the id of the node that the last request from this activity was sent to.

	   @return Node id of the last node the activity has posted a request to

	*/

	const Messages::TNodeId PostedToId() const

		{

		return iPostedToId;

		}

	/**

	Get the id of the message that started this activity.

	   @return Message id of message that kicked off this activity

	*/

	const Messages::TNodeSignal::TMessageId KickOffMessageId() const