1 // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @publishedPartner

    19  @released since 9.5

    20 */

    21 

    22 #ifndef SYMBIAN_NM_ADDRESS_H

    23 #define SYMBIAN_NM_ADDRESS_H

    24 

    25 #include <elements/nm_common.h>

    26 

    27 

    28 #ifdef _DEBUG

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

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

    31 _LIT(KSpecAssert_ElemNodeMessAdrH, "ElemNodeMessAdrH");

    32 #endif

    33 

    34 class TChipReceiver;

    35 

    36 namespace Messages

    37 {

    38 

    39 class ANode;

    40 class RClientInterface;

    41 class RNodeInterface;

    42 class TRuntimeCtxIdOp;

    43 class TNodeIdOp;

    44 class TSignalBase;

    45 class TNodePeerId;

    46 

    47 

    48 class TRuntimeCtxId

    49 /**

    50 TRuntimeCtxId is the baseclass intended for addressing message

    51 (TSignalBase) destinations, i.e.: As implied by the respective API,

    52 the sender of a TSignalBase must supply a TRuntimeCtxId object.

    53 

    54 TRuntimeCtxId defines the maximum size of the addressing structure

    55 and its bedrock composition  (namely: the destination thread of execution).

    56 

    57 @ref TSignalBase

    58 @publishedPartner

    59 @released

    60 */

    61 	{

    62 	friend class TRuntimeCtxIdOp;

    63 	friend class RNodeInterface;     //to directly access TRuntimeCtxId::KIsNullMask8 and avoid a bit costier TRuntimeCtxIdOp

    64 	friend class TChipReceiver;      //to speed up iThread Id swap on dispatch

    65 

    66 public:

    67 	/** The space required for reconstructing the address object.

    68 	It is imagineable that a context within a node context would be required.

    69 	Plus one additional sizeof(TInt) to be on the safe side.

    70 	Size protected by __ASSERT_COMPILE lower down where the

    71 	sizeof(TNodeCtxId) is known.

    72 	*/

    73 	enum { KMaxInlineAddressSize = 20 }; //sizeof(TNodeCtxId) + sizeof(TInt);

    74 	/**

    75     If this mask is not present in the size of a runtime context id, then the runtime context id is a null address

    76 	and should not be used.

    77 	 */

    78 	enum { KIsNullMask8 = 0x80 };

    79 

    80 public:

    81 	/**

    82 	@return the null instance of TRuntimeContextId

    83 	 */

    84 	IMPORT_C static const TRuntimeCtxId& NullId();

    85 	IMPORT_C explicit TRuntimeCtxId();

    86 	/**

    87 	Copy constructor

    88 	@param aRuntimeCtxId runtime context id to copy

    89 	 */

    90 	IMPORT_C TRuntimeCtxId(const TRuntimeCtxId& aRuntimeCtxId); //Copy ctor can not be explicit (?!?)

    91 

    92 	/**

    93 	Assignment operator. Copies contents of the passed in runtime context id into this runtime context id.

    94 	@param aRHS runtime ctx id to copy

    95 	*/

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

    97 

    98 	/**

    99 	Compare the contents of this runtime context id to the contents of another.

   100 	Only iSize bytes are compared, so if aRHS is bigger than the runtime context id it is being compared to

   101 	any byte greater than iSize will not be compared.

   102 

   103 	@param aRHS runtime context id to compare against

   104 	@return ETrue is the contents of both runtime contexts are the same. EFalse otherwise

   105 	*/

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

   107 

   108 	/**

   109 	@see operator==

   110 

   111 	@return EFalse if the contents of both runtime context ids are the same, ETrue otherwise

   112 	*/

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

   114 		{

   115 		return !operator==(aRHS);

   116 		};

   117 

   118 	/**

   119 	Compare the first aSize bytes of this runtime context id with aRHS

   120 	@param aRHS runtime context id to compare against

   121 	@param aSize number of bytes to compare

   122 	@return ETrue if the comparison matches, EFalse otherwise

   123 	*/

   124 	IMPORT_C TBool ComparePart(const TRuntimeCtxId& aRHS, TUint8 aSize) const;

   125 

   126 	/**

   127 	Serialise into a descriptor

   128 	@param aDes descriptor to serialise into

   129 	@return KErrNone if successful, KErrOverflow if the descriptor is not big enough.

   130 	*/

   131 	IMPORT_C TInt Store(TDes8& aDes) const;

   132 

   133 	/**

   134 	@return the size, in bytes, of the id

   135 	*/

   136 	inline TUint8 Size() const {return iSize & ~KIsNullMask8;}

   137 	/**

   138 	@return ETrue if this is a null id, EFalse otherwise

   139 	*/

   140 	inline TBool IsNull() const {return ~iSize & KIsNullMask8;}

   141 	/**

   142 	Make this id a null id

   143 	*/

   144 	inline void SetNull() {iSize &= ~KIsNullMask8;}	//Only one setter allowed by design

   145 

   146 	/**

   147 	@return Salt used to prevent reuse of the id

   148 	*/

   149 	inline TUint8 Salt() const {return iSalt;}

   150 	/**

   151 	@return The scope of the address, currently unused

   152 	*/

   153 	inline TUint32 Scope() const {return iScope;}

   154 	/**

   155 	@return thread in which the addressed object was created

   156 	*/

   157 	inline TUint16 Thread() const {return iThread;}

   158 

   159 	/**

   160 	Post a message to the addressed object.

   161 	@param aPostFrom address of sender

   162 	@param aMessage message to send

   163 	*/

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

   165 

   166 protected:

   167 	/**

   168 	@param aSize size in bytes of the new id

   169 	*/

   170 	IMPORT_C explicit TRuntimeCtxId(TUint8 aSize);

   171 

   172 private:

   173 	TUint8 iSize;

   174 	TUint8 iSalt;	//Reuse protection

   175 

   176 	TUint16 iThread;

   177 	TUint32 iScope;

   178 	};

   179 

   180 class TNodeIdRemainder;

   181 class TNodeId : public TRuntimeCtxId

   182 /**

   183 TNodeId enriches TRuntimeCtxId to enable addressing an object (ANode) 'present'

   184 in the destination thread of execution. The Distributed Object Model (i.e.: this component)

   185 defines a scheme whereby objects (MNodes) running in different runtime contexts can

   186 communicate. It is assumed that an object only ever runs in a single runtime context and

   187 hence its code isn't reentrant. If it were, the object would have potentially as many

   188 identities as there are threads executing the object's code.

   189 

   190 @publishedPartner

   191 @released

   192 */

   193 	{

   194 	friend class TNodeIdOp;

   195 public:

   196 	typedef TNodeIdRemainder TRemainder;

   197 

   198 	/**

   199 	@return the null instance of TNodeId

   200 	*/

   201 	IMPORT_C static const TNodeId& NullId();

   202 	IMPORT_C explicit TNodeId();

   203 

   204 	/**

   205 	Copy constructor.

   206 	@param aNodeId node id to copy

   207 	*/

   208 	IMPORT_C TNodeId(const TNodeId& aNodeId); //Copy ctor can not be explicit (?!?)

   209 

   210 	/**

   211 	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

   212 	must be greater or equal to the size of the target node id. Otherwise as panic will occur.

   213 

   214 	@param aRHS node id to copy

   215 	*/

   216 	IMPORT_C const TNodeId& operator=(const TRuntimeCtxId& aRHS);

   217 

   218 	/**

   219 	Is not equal to operator.

   220 

   221 	@param aRHS node id to compare to

   222 	@return ETrue if this node id is different to aRHS. EFalse otherwise

   223 	*/

   224 	inline TBool operator!=(const TNodeId& aRHS) const

   225 		{

   226 		return TRuntimeCtxId::operator!=(aRHS);

   227 		}

   228 

   229 	/**

   230 	@return the pointer member of this node id

   231 	*/

   232 	inline TAny* Ptr() const {return iPtr;}

   233 

   234 	/**

   235 	@return the node this node id addresses

   236 	*/

   237 	inline ANode& Node() const

   238 		{

   239 		__ASSERT_DEBUG(iPtr, User::Panic(KSpecAssert_ElemNodeMessAdrH, 1));

   240 		return *reinterpret_cast<ANode*>(iPtr);

   241 		}

   242 

   243 protected:

   244 	IMPORT_C explicit TNodeId(TUint8 aSize);

   245 

   246 private:

   247 	TAny* iPtr;

   248 	};

   249 

   250 class TNodeIdRemainder

   251 /*

   252 TNodeIdRemainder represents the reminder of TRuntimeCtxId beyond TNodeId.

   253 The split at this level is meaningful through its usefullness. NodeMessages (this component)

   254 defines the concept of a Node (ANode), but also recognizes entities of finer

   255 granularity need representing.

   256 */

   257 	{

   258 	friend class RNodeInterface;

   259 public:

   260 	/**

   261 	Size of the payload. Defined as the maximum size of an address less the size of a TNodeId.

   262 	*/

   263 	enum

   264 		{

   265 		EPayloadSize = __Align8(TRuntimeCtxId::KMaxInlineAddressSize + sizeof(TUint) - sizeof(TNodeId)),

   266 		};

   267 

   268 	/**

   269 	@return the size of the remainder

   270 	*/

   271 	TInt Size() const { return iSize; }

   272 	/**

   273 	@param aFrom TRuntimeCtxId to take payload from.

   274 	*/

   275 	IMPORT_C explicit TNodeIdRemainder(const TRuntimeCtxId& aFrom);

   276 	IMPORT_C explicit TNodeIdRemainder();

   277 

   278 	/**

   279 	Assignment operator. Will only copy the bytes from (&aRHS + sizeof(TNodeId)) onwards.

   280 	*/

   281 	IMPORT_C const TNodeIdRemainder& operator=(const TRuntimeCtxId& aRHS);

   282 	/**

   283 	Comparison operator. Will only compare the bytes from (&aRHS + sizeof(TNodeId)) onwards.

   284 	@param aRHS to compare to the payload

   285 	@return ETrue if the bytes match, EFalse otherwise

   286 	*/

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

   288 	/**

   289 	Comparison operator.

   290 	@param aRHS remainder to compare to

   291 	*/

   292 	IMPORT_C TBool operator==(const TNodeIdRemainder& aRHS) const;

   293 

   294 	private:

   295 	TUint8 iRemainder[EPayloadSize];

   296 	TInt   iSize;

   297 	};

   298 

   299 

   300 class TNodeCtxId : public TNodeId

   301 /**

   302 TNodeCtxId enriches TNodeId to describe entities addressable _within_ the nodes

   303 (entities of finer granularity than nodes). It is perceived that a single node

   304 (ANode) can maintain multiple conversations with its peers and hence it's the conversations

   305 that need addressing and not just the node.

   306 

   307 @publishedPartner

   308 @released

   309 */

   310 	{

   311 	friend class TNodeCtxIdOp;

   312 	friend class RNodeCtxInterface;

   313 

   314 public:

   315 	/**

   316 	@return the null instance of TNodeCtxId

   317 	*/

   318 	IMPORT_C static const TNodeCtxId& NullId();

   319 

   320 	IMPORT_C explicit TNodeCtxId();

   321 	/**

   322 	@param aNodeCtx Value used to identify an entity within a node. Usually an activity id, but not nescessarily.

   323 	@param aNodeId Node to be addressed.

   324 	*/

   325 	IMPORT_C explicit TNodeCtxId(TUint16 aNodeCtx, const TNodeId& aNodeId);

   326 

   327 	/**

   328 	Copy constructor.

   329 	*/

   330 	IMPORT_C TNodeCtxId(const TNodeCtxId& aNodeCtxId); //Copy ctor can not be explicit (?!?)

   331 

   332 	/**

   333 	Assignment operator. Size of aRHS must be greater than or equal to sizeof(TNodeCtxId)

   334 	@param aRHS object to copy contents from

   335 	*/

   336 	IMPORT_C const TNodeCtxId& operator=(const TRuntimeCtxId& aRHS);

   337 

   338 	/**

   339 	Equality operator.

   340 	*/

   341 	inline TBool operator==(const TNodeCtxId& aRHS) const

   342 		{

   343 		return TNodeId::operator==(aRHS);

   344 		}

   345 

   346 	/**

   347 	Non-equality operator

   348 	*/

   349 	inline TBool operator!=(const TNodeCtxId& aRHS) const

   350 		{

   351 		return TNodeId::operator!=(aRHS);

   352 		}

   353 

   354 	/**

   355 	@return the node ctx value for this address.

   356 	*/

   357 	inline TUint16 NodeCtx() const {return iNodeCtx;}

   358 

   359 protected:

   360 	IMPORT_C explicit TNodeCtxId(TUint8 aSize);

   361 

   362 private:

   363 	TUint16 iNodeCtx;

   364 

   365 	/**

   366 	   Solely here to word align the object, so sizeof() will really return the size.

   367 	   Otherwise, comparision breaks.

   368 	   @internalComponent

   369 	*/

   370 	TUint16 iReserved;

   371 	};

   372 

   373 

   374 /* Unfortunatelly we can not define this enum using sizeof(TNodeCtxId),

   375 since the size of TNodeCtxId is not known at the base class level.

   376 But this is where we protect the consistency of our definition.

   377 */

   378 __ASSERT_COMPILE(TRuntimeCtxId::KMaxInlineAddressSize == sizeof(TNodeCtxId) + sizeof(TInt));

   379 

   380 /**

   381 Cast an address reference to another type of address reference.

   382 The size of the casted address reference must be greater than or equal to the size of the casted to address type.

   383 */

   384 template <class ADDRESSTYPE>

   385 ADDRESSTYPE& address_cast(Messages::TRuntimeCtxId& aAddress)

   386     {

   387     __ASSERT_DEBUG(aAddress.Size()>=sizeof(ADDRESSTYPE),User::Panic(Messages::KMessagesPanic,Messages::EAddressCastPanic));

   388     return static_cast<ADDRESSTYPE&>(aAddress);

   389     }

   390 

   391 /**

   392 Cast a constant address reference to another type of constant address reference.

   393 The size of the casted address reference must be greater than or equal to the size of the casted to address type.

   394 */

   395 template <class ADDRESSTYPE>

   396 const ADDRESSTYPE& address_cast(const Messages::TRuntimeCtxId& aAddress)

   397     {

   398 	__ASSERT_DEBUG(aAddress.Size()>=sizeof(ADDRESSTYPE),User::Panic(Messages::KMessagesPanic,Messages::EAddressCastPanic));

   399     return static_cast<const ADDRESSTYPE&>(aAddress);

   400     }

   401 

   402 /**

   403 Cast an address pointer to another type of address pointer.

   404 The size of the casted address pointer must be greater than or equal to the size of the casted to address type.

   405 */

   406 template <class ADDRESSTYPE>

   407 ADDRESSTYPE* address_cast(Messages::TRuntimeCtxId* aAddress)

   408     {

   409     __ASSERT_DEBUG(aAddress,User::Panic(Messages::KMessagesPanic,Messages::EAddressCastPanic));

   410     return aAddress->Size()>=sizeof(ADDRESSTYPE)? static_cast<ADDRESSTYPE*>(aAddress) : NULL;

   411     }

   412 

   413 /**

   414 Cast a constant address pointer to another type of constant address pointer.

   415 The size of the casted address pointer must be greater than or equal to the size of the casted to address type.

   416 */

   417 template <class ADDRESSTYPE>

   418 const ADDRESSTYPE* address_cast(const Messages::TRuntimeCtxId* aAddress)

   419     {

   420     __ASSERT_DEBUG(aAddress,User::Panic(Messages::KMessagesPanic,Messages::EAddressCastPanic));

   421     return aAddress->Size()>=sizeof(ADDRESSTYPE)? static_cast<const ADDRESSTYPE*>(aAddress) : NULL;

   422     }

   423 

   424 } //namespace Messages

   425 

   426 

   427 #endif

   428 //SYMBIAN_NM_ADDRESS_H

   429