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

//

/**

 @file

 @publishedPartner

 @released

*/

#ifndef SYMBIAN_NM_INTERFACES_H

#define SYMBIAN_NM_INTERFACES_H

//#include <elements/nm_signals.h>

#include <elements/nm_address.h>

#include <elements/nm_log.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_ElemNodeMessIntH, "ElemNodeMessIntH");

#endif

namespace Messages

{

class MTransportSender;

class ANode;

class TSignalBase;

class TClientType

/*

TClientType defines a technology agnostic collection of enums for types and

flags describing various traits of peers. It is also a placeholder for these

values. When implementing a relation with a peer, TClientType (or its technology

specific override) can be used to collect informations about the peers.

@see RNodeInterface

*/

	{

public:

    enum TType

        {

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

        //

        // 1. Types 32bits (a client can only have one type)

        //

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

        EAll            = 0xFFFFFFFF,

        EUnknown        = 0x00000000,

        ERegistrar      = 0x00000001, //Useful general purpose role.

                                      //Used to represent simple non-standard or one-off or transient

                                      //roles which now do not need to be specially defined for these

                                      //simple and/or rare relationships.

        EWorker         = 0x00000002, //Useful general purpose role.

		/**

		@internalTechnology

		Reserved types that can change at any time and must NOT be used under any circumstances.

		Please take care when defining derived client types (do not reference ELastReservedType).

		*/

        ELastReservedType_InternalTechnology_CanBeReusedAtAnyTime_DoNotUseInCode = 0x00000080,

		};

	enum TFlags

		{

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

        //

        // 2. Flags 32bits (a client can have many flags)

        //

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

        ELeaving        = 0x00000001, //Client has been sent the final goodbye message (e.g TClientLeavingRequest)

                             //and we are awaiting the channel clear confirmation (e.g. TLeaveComplete).

                             //No further communication with this client is safe as it assumes we discard

                             //any references to it. For example it could destruct itself etc.

		EAdministrative = 0x00000002, //These clients perform some administrative tasks on our node.

		/**

		@internalTechnology

		Reserved flags that can change at any time and must NOT be used under any circumstances.

		Please take care when defining derived client flags (do not reference ELastReservedFlag).

		*/

        ELastReservedFlag_InternalTechnology_CanBeReusedAtAnyTime_DoNotUseInCode = 0x00000080

        };

public:

	IMPORT_C static const TClientType& NullType();

	TClientType()

	:	iClientType(EUnknown),

	    iClientFlags(0)

		{

		}

	TClientType(TUint aClientType, TUint aClientFlags = 0)

	:	iClientType(aClientType),

		iClientFlags(aClientFlags)

		{

		}

	TClientType(const TClientType& aClientType)

	:	iClientType(aClientType.iClientType),

		iClientFlags(aClientType.iClientFlags)

		{

		}

	TBool IsNull() const

	    {

	    return iClientType == 0 && iClientFlags == 0;

	    }

	TUint32 Type() const

	    {

	    return iClientType;

	    }

	TUint32 Flags() const

	    {

	    return iClientFlags;

	    }

	TUint32 SetFlags(TUint32 aFlags)

	    {

	    return iClientFlags |= aFlags;

	    }

	TUint32 ClearFlags(TUint32 aFlags)

	    {

	    return iClientFlags &= ~aFlags;

	    }

protected:

    TUint32 iClientType;

    TUint32 iClientFlags;

	};

//None of the specified

struct TNoMatchPolicy

	{

	inline static TBool Match(TUint32 aVal, TUint32 aMatch)

		{

        return (aVal & aMatch) == 0;

		}

	};

//Any of the specified, can be more, can be less

struct TAnyMatchPolicy

	{

	inline static TBool Match(TUint32 aVal, TUint32 aMatch)

		{

        return (aVal & aMatch) != 0;

		}

	};

//Any of the specified, both can be null, can be more, can be less

struct TExactOrAnyMatchPolicy

	{

	inline static TBool Match(TUint32 aVal, TUint32 aMatch)

		{

		return (aVal == aMatch) || (aVal & aMatch) != 0;

		}

	};

//All of the specified, can't be more, can be less

struct TSubSetMatchPolicy

	{

	inline static TBool Match(TUint32 aVal, TUint32 aMatch)

		{

        return (aVal & aMatch) == aVal;

		}

	};

//Any of the specified, can be more, can't be less

struct TSuperSetMatchPolicy

	{

	inline static TBool Match(TUint32 aVal, TUint32 aMatch)

		{

        return (aVal & aMatch) == aMatch;

		}

	};

//All of the specified, can't be less, can't be more

struct TExactMatchPolicy

	{

	inline static TBool Match(TUint32 aVal, TUint32 aMatch)

		{

		return aVal == aMatch;

		}

	};

template <typename TTYPEMATCHPOLICY = TSubSetMatchPolicy, typename TFLAGSMATCHPOLICY = TSuperSetMatchPolicy>

struct TMatchPolicy

	{

	inline static TBool Match(const TClientType& aType, const TClientType& aMatch)

		{

		return TTYPEMATCHPOLICY::Match(aType.Type(),aMatch.Type())

			&& TFLAGSMATCHPOLICY::Match(aType.Flags(),aMatch.Flags());

		}

	};

template <typename TINCMATCHPOLICY = TMatchPolicy<TSubSetMatchPolicy,TSuperSetMatchPolicy>, typename TEXCMATCHPOLICY = TMatchPolicy<TExactMatchPolicy,TExactMatchPolicy> >

struct TTypeMatchPolicy

	{

	inline static TBool Match(const TClientType& aType, const TClientType& aInclude, const TClientType& aExclude)

		{

		TBool inc = TINCMATCHPOLICY::Match(aType, aInclude);

		TBool exc = aExclude.IsNull() || !TEXCMATCHPOLICY::Match(aType, aExclude);

		return inc && exc;

		}

	};

//We could be using partially specialised typedefs here,

//if they only were supported by C++ at the time of writing this code...

//                         INCType   |     Type                  Flag              EXCType    |      Type               Flag

//                       ----------------------------------------------           -------------------------------------------------

typedef TTypeMatchPolicy<TMatchPolicy<TSubSetMatchPolicy,  TSuperSetMatchPolicy>, TMatchPolicy<TSuperSetMatchPolicy,TAnyMatchPolicy> > TDefaultClientMatchPolicy;

typedef TTypeMatchPolicy<TMatchPolicy<TSuperSetMatchPolicy,TSuperSetMatchPolicy>, TMatchPolicy<TSuperSetMatchPolicy,TAnyMatchPolicy> > TFlagsOnlyClientMatchPolicy;

typedef TTypeMatchPolicy<TMatchPolicy<TSubSetMatchPolicy,  TNoMatchPolicy>,       TMatchPolicy<TSuperSetMatchPolicy,TAnyMatchPolicy> > TExcludeTypeAndFlagClientMatchPolicy;

typedef TTypeMatchPolicy<TMatchPolicy<TSubSetMatchPolicy, TExactOrAnyMatchPolicy>, TMatchPolicy<TSuperSetMatchPolicy,TAnyMatchPolicy> > TExactOrAnyIncludeFlagsClientMatchPolicy;

class RClientInterface

/*

Represents an opaque recipient of messages with no assumptions about its

type (i.e.: it's not necesserilly a node and the only thing known about it, is its

TRuntimeCtxId). Relations with such recipients should be implemented by declaring

RClientInterface as members.

@see RNodeInterface

*/

	{

public:

	IMPORT_C RClientInterface();

	IMPORT_C virtual ~RClientInterface(); //Derived types may be used via base ptrs

	IMPORT_C void Open(const TRuntimeCtxId& aPostTo, MTransportSender* aSender = NULL);

	IMPORT_C void Close(); // stomp members

	IMPORT_C TBool operator==(const TRuntimeCtxId& aRHS) const;

	IMPORT_C TBool operator==(const RClientInterface& aRHS) const;

	IMPORT_C TBool IsOpen() const;

	inline const TRuntimeCtxId& RecipientId() const

		{

		return *reinterpret_cast<const TRuntimeCtxId*>(iRecipientAddress);

		}

	IMPORT_C static void OpenPostMessageClose(const TRuntimeCtxId& aPostFrom, const TRuntimeCtxId& aPostTo, const TSignalBase& aMessage);

	IMPORT_C void PostMessage(const TRuntimeCtxId& aPostFrom, const TSignalBase& aMessage) const;

protected:

	void PostMessage(const TRuntimeCtxId& aPostFrom, const TRuntimeCtxId& aPostTo, const TSignalBase& aMessage) const;

	inline TRuntimeCtxId& RecipientRef()

		{

		return *reinterpret_cast<TRuntimeCtxId*>(iRecipientAddress);

		}

	inline const TRuntimeCtxId& RecipientRef() const

		{

		return *reinterpret_cast<const TRuntimeCtxId*>(iRecipientAddress);

		}

private:

	MTransportSender* iTransportSender;

	TUint8 iRecipientAddress[__Align8(TRuntimeCtxId::KMaxInlineAddressSize)];

	};

class RNodeInterface : public RClientInterface

/*

RNodeInterface represents a relation with a node (ANode). It does so by:

- storing the node's address (TNodeId)

- collecting informations about the node (::Type & ::Flags).

Classes (typically nodes) should implement relations with another nodes

by declaring RNodeInterface as members.

@see TClientType

*/

	{

	friend class TClientIterBase;

public:

	IMPORT_C void Open(TNodeId aPostTo, const TClientType& aClientType = TClientType::NullType(), MTransportSender* aSender = NULL);

	IMPORT_C void Close();

	IMPORT_C TBool operator==(const RNodeInterface& aRHS) const;

	inline TBool operator==(const TRuntimeCtxId& aRHS) const

		{

		return RClientInterface::operator==(aRHS);

		}

	IMPORT_C void PostMessage(const TRuntimeCtxId& aPostFrom, const TNodeId::TRemainder& aPostTo, const TSignalBase& aMessage) const;

	inline void PostMessage(const TRuntimeCtxId& aPostFrom, const TSignalBase& aMessage) const

		{

		#ifdef SYMBIAN_TRACE_ENABLE

			if(Flags() & TClientType::ELeaving)

				{

				NM_LOG_START_BLOCK(KNodeMessagesSubTag, _L8("ERROR: Post while node is leaving"));

				NM_LOG_ADDRESS_EXT(KNodeMessagesSubTag, aPostFrom, _L8("From:"));

				NM_LOG_ADDRESS_EXT(KNodeMessagesSubTag, RecipientId(), _L8("To:"));

				NM_LOG_MESSAGE_EXT(KNodeMessagesSubTag, aMessage, _L8("Msg:"));

				NM_LOG_END_BLOCK(KNodeMessagesSubTag, KNullDesC8);

				}

		#endif

		__ASSERT_DEBUG(!(Flags() & TClientType::ELeaving), User::Panic(KSpecAssert_ElemNodeMessIntH, 1)); //OOOOOPS! What are you doing??

		RClientInterface::PostMessage(aPostFrom, aMessage);

		}

	inline const TNodeId& RecipientId() const

		{

		return address_cast<TNodeId>(RClientInterface::RecipientId());

		}

	TClientType& ClientType()

		{

		return iClientType;

		}

	TUint32 Type() const

	    {

	    return iClientType.Type();

	    }

	TUint32 Flags() const

	    {

	    return iClientType.Flags();

	    }

	TUint32 SetFlags(TUint32 aFlags)

	    {

#if defined(_DEBUG) && defined(NM_LOG_FLAG_SETTINGS)

	    // Note that this generates quite alot of logging, hence is not turned on by default.

	    // Note also that (a minority of) flag setting may also take place in TNodePeerId.  

	    const TUint32 oldFlags = Flags();

	    const TUint32 newFlags = iClientType.SetFlags(aFlags);

	    if (oldFlags != newFlags)

	    	{

	    	NM_LOG((KNodeMessagesSubTag, _L8("RNI::SetFlags(%x) ANode=%08x, %x->%x"), aFlags, &RecipientId().Node(), oldFlags, newFlags));

	    	}

	    return newFlags;

#else

	    return iClientType.SetFlags(aFlags);

#endif

	    }

	TUint32 ClearFlags(TUint32 aFlags)

	    {

#if defined(_DEBUG) && defined(NM_LOG_FLAG_SETTINGS)

	    const TUint32 oldFlags = Flags();

	    const TUint32 newFlags = iClientType.ClearFlags(aFlags);

	    if (oldFlags != newFlags)

	    	{

	    	NM_LOG((KNodeMessagesSubTag, _L8("RNI::ClearFlags(%x) ANode=%08x, %x->%x"), aFlags, &RecipientId().Node(), oldFlags, newFlags));

	    	}

	    return newFlags;

#else

	    return iClientType.ClearFlags(aFlags);

#endif

	    }

protected:

	TClientType iClientType;

	};

class RRequestOriginator

/*

RRequestOriginator is a helper class that ackowledges the very common scenario

where an activity running at a remote node sends a request and that request

needs to be replied to. RRequestOriginator is associated with a node (holds

a reference to RNodeInterface) as well as stores the TNodeId::TReminder of

the address in order to identify the activity running at that node.

*/

    {

public:

	IMPORT_C TInt Open(RNodeInterface& aNode, const TRuntimeCtxId& aRequestOriginator);

	IMPORT_C void Open(RRequestOriginator& aOriginalRequest);

	IMPORT_C void Close();

	IMPORT_C TBool operator==(const RRequestOriginator& aRHS) const;

	IMPORT_C TBool operator==(const TRuntimeCtxId& aRHS) const;

	IMPORT_C TBool IsOpen() const;

	Messages::RNodeInterface& Node()

		{

		__ASSERT_DEBUG(IsOpen(), User::Panic(Messages::KMessagesPanic,Messages::EClientNotValidPanic));

		return *iNode;

		}

	const Messages::RNodeInterface& Node() const

		{

		__ASSERT_DEBUG(IsOpen(), User::Panic(Messages::KMessagesPanic,Messages::EClientNotValidPanic));

		return *iNode;

		}

	Messages::TNodeId::TRemainder& Remainder()

		{

		Node(); //Make sure 'this' is openned

		return iRemainder;

		}

	const Messages::TNodeId::TRemainder& Remainder() const

		{

		Node(); //Make sure 'this' is openned

		return iRemainder;

		}

	IMPORT_C void PostMessage(const TRuntimeCtxId& aPostFrom, const TSignalBase& aMessage) const;

	IMPORT_C void ReplyTo(const TRuntimeCtxId& aReplyFrom, const TSignalBase& aMessage);

private:

	Messages::TNodeId::TRemainder iRemainder;

	Messages::RNodeInterface* 	  iNode;

    };

//

// TClientIterBase

class TClientIterBase

	{

public:

	typedef RPointerArray<RNodeInterface> TClientArray;

public:

	inline RNodeInterface* operator++(TInt /*aInd*/) //-postfix

	    {

	    RNodeInterface* cli = Find(iIndex, +1, 1);

	    iIndex++;

	    return cli;

	    }

	inline RNodeInterface* operator++()              //-prefix

	    {

	    ++iIndex;

	    return Find(iIndex, +1, 1);

	    }

	inline RNodeInterface* operator--(TInt /*aInd*/) //-postfix

	    {

	    RNodeInterface* cli = Find(iIndex, -1, 1);

	    iIndex--;

	    return cli;

	    }

	IMPORT_C RNodeInterface* operator[](TInt aInd);

	inline RNodeInterface* operator*()

		{

		return Find(iIndex, +1, 0);

		}

    void SetToLast()

        {

        iIndex = iClients.Count() - 1;

        }

	void Reset()

		{

		iIndex = 0;

		}

protected:

	virtual TBool TypeMatch(RNodeInterface& aClient) const = 0;

	explicit TClientIterBase(const RPointerArray<RNodeInterface>& aClients)

    :	iClients(aClients),

    	iIndex(0)

    	{

		}

    IMPORT_C RNodeInterface* Find(TInt& aInd, TInt aDir, TInt aCount);

    const RPointerArray<RNodeInterface>& iClients;

    TInt iIndex;

	};

//

// TClientIter

template<class TTYPEMATCHPOLICY = TDefaultClientMatchPolicy>

class TClientIter : public TClientIterBase

	{

public:

	explicit TClientIter(const RPointerArray<RNodeInterface>& aClients, const TClientType& aInclude, const TClientType& aExclude = TClientType::NullType())

	:	TClientIterBase(aClients), iInclude(aInclude), iExclude(aExclude) {};

private:

	virtual TBool TypeMatch(RNodeInterface& aClient) const

		{

		return TTYPEMATCHPOLICY::Match(aClient.ClientType(), iInclude, iExclude);

		}

	TClientType iInclude;

	TClientType iExclude;

	};

} //namespace Messages

#endif

//SYMBIAN_NM_INTERFACES_H