--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/commsfwsupport/commselements/nodemessages/inc/nm_address.h	Thu Dec 17 09:22:25 2009 +0200
@@ -0,0 +1,429 @@
+// 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:
+//
+
+/**
+ @file
+ @publishedPartner
+ @released since 9.5
+*/
+
+#ifndef SYMBIAN_NM_ADDRESS_H
+#define SYMBIAN_NM_ADDRESS_H
+
+#include <elements/nm_common.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_ElemNodeMessAdrH, "ElemNodeMessAdrH");
+#endif
+
+class TChipReceiver;
+
+namespace Messages
+{
+
+class ANode;
+class RClientInterface;
+class RNodeInterface;
+class TRuntimeCtxIdOp;
+class TNodeIdOp;
+class TSignalBase;
+class TNodePeerId;
+
+
+class TRuntimeCtxId
+/**
+TRuntimeCtxId is the baseclass intended for addressing message
+(TSignalBase) destinations, i.e.: As implied by the respective API,
+the sender of a TSignalBase must supply a TRuntimeCtxId object.
+
+TRuntimeCtxId defines the maximum size of the addressing structure
+and its bedrock composition  (namely: the destination thread of execution).
+
+@ref TSignalBase
+@publishedPartner
+@released
+*/
+	{
+	friend class TRuntimeCtxIdOp;
+	friend class RNodeInterface;     //to directly access TRuntimeCtxId::KIsNullMask8 and avoid a bit costier TRuntimeCtxIdOp
+	friend class TChipReceiver;      //to speed up iThread Id swap on dispatch
+
+public:
+	/** The space required for reconstructing the address object.
+	It is imagineable that a context within a node context would be required.
+	Plus one additional sizeof(TInt) to be on the safe side.
+	Size protected by __ASSERT_COMPILE lower down where the
+	sizeof(TNodeCtxId) is known.
+	*/
+	enum { KMaxInlineAddressSize = 20 }; //sizeof(TNodeCtxId) + sizeof(TInt);
+	/**
+    If this mask is not present in the size of a runtime context id, then the runtime context id is a null address
+	and should not be used.
+	 */
+	enum { KIsNullMask8 = 0x80 };
+
+public:
+	/**
+	@return the null instance of TRuntimeContextId
+	 */
+	IMPORT_C static const TRuntimeCtxId& NullId();
+	IMPORT_C explicit TRuntimeCtxId();
+	/**
+	Copy constructor
+	@param aRuntimeCtxId runtime context id to copy
+	 */
+	IMPORT_C TRuntimeCtxId(const TRuntimeCtxId& aRuntimeCtxId); //Copy ctor can not be explicit (?!?)
+
+	/**
+	Assignment operator. Copies contents of the passed in runtime context id into this runtime context id.
+	@param aRHS runtime ctx id to copy
+	*/
+	IMPORT_C const TRuntimeCtxId& operator=(const TRuntimeCtxId& aRHS);
+
+	/**
+	Compare the contents of this runtime context id to the contents of another.
+	Only iSize bytes are compared, so if aRHS is bigger than the runtime context id it is being compared to
+	any byte greater than iSize will not be compared.
+
+	@param aRHS runtime context id to compare against
+	@return ETrue is the contents of both runtime contexts are the same. EFalse otherwise
+	*/
+	IMPORT_C TBool operator==(const TRuntimeCtxId& aRHS) const;
+
+	/**
+	@see operator==
+
+	@return EFalse if the contents of both runtime context ids are the same, ETrue otherwise
+	*/
+	inline TBool operator!=(const TRuntimeCtxId& aRHS) const
+		{
+		return !operator==(aRHS);
+		};
+
+	/**
+	Compare the first aSize bytes of this runtime context id with aRHS
+	@param aRHS runtime context id to compare against
+	@param aSize number of bytes to compare
+	@return ETrue if the comparison matches, EFalse otherwise
+	*/
+	IMPORT_C TBool ComparePart(const TRuntimeCtxId& aRHS, TUint8 aSize) const;
+
+	/**
+	Serialise into a descriptor
+	@param aDes descriptor to serialise into
+	@return KErrNone if successful, KErrOverflow if the descriptor is not big enough.
+	*/
+	IMPORT_C TInt Store(TDes8& aDes) const;
+
+	/**
+	@return the size, in bytes, of the id
+	*/
+	inline TUint8 Size() const {return iSize & ~KIsNullMask8;}
+	/**
+	@return ETrue if this is a null id, EFalse otherwise
+	*/
+	inline TBool IsNull() const {return ~iSize & KIsNullMask8;}
+	/**
+	Make this id a null id
+	*/
+	inline void SetNull() {iSize &= ~KIsNullMask8;}	//Only one setter allowed by design
+
+	/**
+	@return Salt used to prevent reuse of the id
+	*/
+	inline TUint8 Salt() const {return iSalt;}
+	/**
+	@return The scope of the address, currently unused
+	*/
+	inline TUint32 Scope() const {return iScope;}
+	/**
+	@return thread in which the addressed object was created
+	*/
+	inline TUint16 Thread() const {return iThread;}
+
+	/**
+	Post a message to the addressed object.
+	@param aPostFrom address of sender
+	@param aMessage message to send
+	*/
+	IMPORT_C void PostTo(const TRuntimeCtxId& aPostFrom, const TSignalBase& aMessage) const;
+
+protected:
+	/**
+	@param aSize size in bytes of the new id
+	*/
+	IMPORT_C explicit TRuntimeCtxId(TUint8 aSize);
+
+private:
+	TUint8 iSize;
+	TUint8 iSalt;	//Reuse protection
+
+	TUint16 iThread;
+	TUint32 iScope;
+	};
+
+class TNodeIdRemainder;
+class TNodeId : public TRuntimeCtxId
+/**
+TNodeId enriches TRuntimeCtxId to enable addressing an object (ANode) 'present'
+in the destination thread of execution. The Distributed Object Model (i.e.: this component)
+defines a scheme whereby objects (MNodes) running in different runtime contexts can
+communicate. It is assumed that an object only ever runs in a single runtime context and
+hence its code isn't reentrant. If it were, the object would have potentially as many
+identities as there are threads executing the object's code.
+
+@publishedPartner
+@released
+*/
+	{
+	friend class TNodeIdOp;
+public:
+	typedef TNodeIdRemainder TRemainder;
+
+	/**
+	@return the null instance of TNodeId
+	*/
+	IMPORT_C static const TNodeId& NullId();
+	IMPORT_C explicit TNodeId();
+
+	/**
+	Copy constructor.
+	@param aNodeId node id to copy
+	*/
+	IMPORT_C TNodeId(const TNodeId& aNodeId); //Copy ctor can not be explicit (?!?)
+
+	/**
+	Assignment operator. Copies contents of the passed in node id to this node id. aRHS is passed in as a TRuntimeCtxId. The size of this object
+	must be greater or equal to the size of the target node id. Otherwise as panic will occur.
+
+	@param aRHS node id to copy
+	*/
+	IMPORT_C const TNodeId& operator=(const TRuntimeCtxId& aRHS);
+
+	/**
+	Is not equal to operator.
+
+	@param aRHS node id to compare to
+	@return ETrue if this node id is different to aRHS. EFalse otherwise
+	*/
+	inline TBool operator!=(const TNodeId& aRHS) const
+		{
+		return TRuntimeCtxId::operator!=(aRHS);
+		}
+
+	/**
+	@return the pointer member of this node id
+	*/
+	inline TAny* Ptr() const {return iPtr;}
+
+	/**
+	@return the node this node id addresses
+	*/
+	inline ANode& Node() const
+		{
+		__ASSERT_DEBUG(iPtr, User::Panic(KSpecAssert_ElemNodeMessAdrH, 1));
+		return *reinterpret_cast<ANode*>(iPtr);
+		}
+
+protected:
+	IMPORT_C explicit TNodeId(TUint8 aSize);
+
+private:
+	TAny* iPtr;
+	};
+
+class TNodeIdRemainder
+/*
+TNodeIdRemainder represents the reminder of TRuntimeCtxId beyond TNodeId.
+The split at this level is meaningful through its usefullness. NodeMessages (this component)
+defines the concept of a Node (ANode), but also recognizes entities of finer
+granularity need representing.
+*/
+	{
+	friend class RNodeInterface;
+public:
+	/**
+	Size of the payload. Defined as the maximum size of an address less the size of a TNodeId.
+	*/
+	enum
+		{
+		EPayloadSize = __Align8(TRuntimeCtxId::KMaxInlineAddressSize + sizeof(TUint) - sizeof(TNodeId)),
+		};
+
+	/**
+	@return the size of the remainder
+	*/
+	TInt Size() const { return iSize; }
+	/**
+	@param aFrom TRuntimeCtxId to take payload from.
+	*/
+	IMPORT_C explicit TNodeIdRemainder(const TRuntimeCtxId& aFrom);
+	IMPORT_C explicit TNodeIdRemainder();
+
+	/**
+	Assignment operator. Will only copy the bytes from (&aRHS + sizeof(TNodeId)) onwards.
+	*/
+	IMPORT_C const TNodeIdRemainder& operator=(const TRuntimeCtxId& aRHS);
+	/**
+	Comparison operator. Will only compare the bytes from (&aRHS + sizeof(TNodeId)) onwards.
+	@param aRHS to compare to the payload
+	@return ETrue if the bytes match, EFalse otherwise
+	*/
+	IMPORT_C TBool operator==(const TRuntimeCtxId& aRHS) const;
+	/**
+	Comparison operator.
+	@param aRHS remainder to compare to
+	*/
+	IMPORT_C TBool operator==(const TNodeIdRemainder& aRHS) const;
+
+	private:
+	TUint8 iRemainder[EPayloadSize];
+	TInt   iSize;
+	};
+
+
+class TNodeCtxId : public TNodeId
+/**
+TNodeCtxId enriches TNodeId to describe entities addressable _within_ the nodes
+(entities of finer granularity than nodes). It is perceived that a single node
+(ANode) can maintain multiple conversations with its peers and hence it's the conversations
+that need addressing and not just the node.
+
+@publishedPartner
+@released
+*/
+	{
+	friend class TNodeCtxIdOp;
+	friend class RNodeCtxInterface;
+
+public:
+	/**
+	@return the null instance of TNodeCtxId
+	*/
+	IMPORT_C static const TNodeCtxId& NullId();
+
+	IMPORT_C explicit TNodeCtxId();
+	/**
+	@param aNodeCtx Value used to identify an entity within a node. Usually an activity id, but not nescessarily.
+	@param aNodeId Node to be addressed.
+	*/
+	IMPORT_C explicit TNodeCtxId(TUint16 aNodeCtx, const TNodeId& aNodeId);
+
+	/**
+	Copy constructor.
+	*/
+	IMPORT_C TNodeCtxId(const TNodeCtxId& aNodeCtxId); //Copy ctor can not be explicit (?!?)
+
+	/**
+	Assignment operator. Size of aRHS must be greater than or equal to sizeof(TNodeCtxId)
+	@param aRHS object to copy contents from
+	*/
+	IMPORT_C const TNodeCtxId& operator=(const TRuntimeCtxId& aRHS);
+
+	/**
+	Equality operator.
+	*/
+	inline TBool operator==(const TNodeCtxId& aRHS) const
+		{
+		return TNodeId::operator==(aRHS);
+		}
+
+	/**
+	Non-equality operator
+	*/
+	inline TBool operator!=(const TNodeCtxId& aRHS) const
+		{
+		return TNodeId::operator!=(aRHS);
+		}
+
+	/**
+	@return the node ctx value for this address.
+	*/
+	inline TUint16 NodeCtx() const {return iNodeCtx;}
+
+protected:
+	IMPORT_C explicit TNodeCtxId(TUint8 aSize);
+
+private:
+	TUint16 iNodeCtx;
+
+	/**
+	   Solely here to word align the object, so sizeof() will really return the size.
+	   Otherwise, comparision breaks.
+	   @internalComponent
+	*/
+	TUint16 iReserved;
+	};
+
+
+/* Unfortunatelly we can not define this enum using sizeof(TNodeCtxId),
+since the size of TNodeCtxId is not known at the base class level.
+But this is where we protect the consistency of our definition.
+*/
+__ASSERT_COMPILE(TRuntimeCtxId::KMaxInlineAddressSize == sizeof(TNodeCtxId) + sizeof(TInt));
+
+/**
+Cast an address reference to another type of address reference.
+The size of the casted address reference must be greater than or equal to the size of the casted to address type.
+*/
+template <class ADDRESSTYPE>
+ADDRESSTYPE& address_cast(Messages::TRuntimeCtxId& aAddress)
+    {
+    __ASSERT_DEBUG(aAddress.Size()>=sizeof(ADDRESSTYPE),User::Panic(Messages::KMessagesPanic,Messages::EAddressCastPanic));
+    return static_cast<ADDRESSTYPE&>(aAddress);
+    }
+
+/**
+Cast a constant address reference to another type of constant address reference.
+The size of the casted address reference must be greater than or equal to the size of the casted to address type.
+*/
+template <class ADDRESSTYPE>
+const ADDRESSTYPE& address_cast(const Messages::TRuntimeCtxId& aAddress)
+    {
+	__ASSERT_DEBUG(aAddress.Size()>=sizeof(ADDRESSTYPE),User::Panic(Messages::KMessagesPanic,Messages::EAddressCastPanic));
+    return static_cast<const ADDRESSTYPE&>(aAddress);
+    }
+
+/**
+Cast an address pointer to another type of address pointer.
+The size of the casted address pointer must be greater than or equal to the size of the casted to address type.
+*/
+template <class ADDRESSTYPE>
+ADDRESSTYPE* address_cast(Messages::TRuntimeCtxId* aAddress)
+    {
+    __ASSERT_DEBUG(aAddress,User::Panic(Messages::KMessagesPanic,Messages::EAddressCastPanic));
+    return aAddress->Size()>=sizeof(ADDRESSTYPE)? static_cast<ADDRESSTYPE*>(aAddress) : NULL;
+    }
+
+/**
+Cast a constant address pointer to another type of constant address pointer.
+The size of the casted address pointer must be greater than or equal to the size of the casted to address type.
+*/
+template <class ADDRESSTYPE>
+const ADDRESSTYPE* address_cast(const Messages::TRuntimeCtxId* aAddress)
+    {
+    __ASSERT_DEBUG(aAddress,User::Panic(Messages::KMessagesPanic,Messages::EAddressCastPanic));
+    return aAddress->Size()>=sizeof(ADDRESSTYPE)? static_cast<const ADDRESSTYPE*>(aAddress) : NULL;
+    }
+
+} //namespace Messages
+
+
+#endif
+//SYMBIAN_NM_ADDRESS_H
+