// 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, MeshMachine::TNodeActivity::ENodeCtor, msgtype::EId, msgtype::ERealm, name :: iData[1], (TAny*)&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, MeshMachine::TNodeActivity::ENodeCtor, msgtype::EId, msgtype::ERealm, name :: iData[1], (TAny*)&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, MeshMachine::TNodeActivity::ENodeCtor, msgtype::EId, msgtype::ERealm, name :: iData[1], (TAny*)&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, MeshMachine::TNodeActivity::ENodeCtor, msgtype::EId, msgtype::ERealm, name :: iData[1], (TAny*)&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 \

	};

/**

RESERVED MACROS NOT TO BE USED.

The following are new macro definitions allowing the context to be passed as a parameter rather than the node.

In time the ability to pass context rather than node will be placed in the original macros. For the meantime,

only critical commsFw activities which must have the context passed instead of the node should use these macros.

All other activities should continue to use original macros declared above.

*/

/**

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_RESERVED_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_RESERVED_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 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_RESERVED_NODEACTIVITY

@see CNodeActivityBase

*/

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

		const MeshMachine::TNodeActivity name :: iSelf = {id, MeshMachine::TNodeActivity::EContextCtor, msgtype::EId, msgtype::ERealm, name :: iData[1], (TAny*)&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_RESERVED_CUSTOM_NODEACTIVITY

*/

	#define DEFINE_RESERVED_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, MeshMachine::TNodeActivity::EContextCtor, msgtype::EId, msgtype::ERealm, name :: iData[1], (TAny*)&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.