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

    20 */

    21 

    22 #ifndef ES_COMMSDATAOBJECT_H

    23 #define ES_COMMSDATAOBJECT_H

    24 

    25 

    26 #include <es_sock.h>

    27 #include <comms-infras/api_ext_list.h>

    28 #include <comms-infras/metacontainer.h>

    29 #include <comms-infras/metatype.h>

    30 

    31 

    32 #ifdef _DEBUG

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

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

    35 _LIT(KSpecAssert_ESocks_cmsdtbjct, "ESocks_cmsdtbjct");

    36 #endif

    37 

    38 namespace ESock

    39 {

    40 class CConnection;

    41 class MPlatsecApiExt;

    42 class TGetOrSetParameters;

    43 

    44 

    45 /**

    46 The base class for any CommsDataObject. 

    47 

    48 A CommsDataObject is a serializable data holding object that knows how

    49 it should be persisted within the comms framework when dispatched on a

    50 node with a supported interface.

    51 

    52 Depending on the specific implementation of the object it can be used to

    53 store or retrieve information from one or more nodes in the stack of

    54 connection providers.

    55 

    56 Note: A CommsDataObject has no connection to the similarly named CommsDat

    57 database or any of its associated classes.

    58 */

    59 class XCommsDataObject : public Meta::SMetaDataECom

    60 	{

    61 	friend class ::RConnection;

    62 	friend class ESock::CConnection;

    63 	friend class ESock::TGetOrSetParameters;

    64 	

    65 public:

    66 	inline TUint RequiredItfExtId() const

    67 		{

    68 		return iReqItfExtId;

    69 		}

    70 

    71 	inline TBool IsGetSupported() const

    72 		{

    73 		return (iFlags & EGetSupported) == EGetSupported;

    74 		}

    75 		

    76 	inline TBool IsSetSupported() const

    77 		{

    78 		return (iFlags & ESetSupported) == ESetSupported;

    79 		}

    80 	

    81 	inline TBool IsProgressive() const

    82 		{

    83 		return (iFlags & EProgressive) == EProgressive;

    84 		}

    85 	

    86 protected:

    87     /**

    88     Indicates the action to be taken by the framework after the

    89     CommsDataObject has been dispatched. 

    90     */

    91 	enum TProgressAction

    92 		{

    93 		/** The selected operation is finished and the client should be completed.

    94 		This should always be returned if the CommsDataObject does not support the

    95 		EProgressive operation */

    96 		EComplete,

    97 		

    98 		/** The selected operation has more work to do and framework should continue

    99 		to forward the CommsDataObject to the next provider */

   100 		EContinue,

   101 		};

   102 

   103 	/**

   104 	Flags that identify the client requested operation. These are set

   105 	on the CommsDataObject internally and should only be used in the

   106 	implementation of a CommsDataObject when comparing the result of

   107 	OperationMode().

   108 	*/

   109 	enum 

   110 		{

   111 		/** Client requested that the object store its data on a provider */

   112 		EOperationSet = 0,

   113 

   114 		/** Client requested that the object retreive data from a provider */

   115 		EOperationGet = 1

   116 		};

   117 

   118 	

   119 	/**

   120 	Flags that identify the operations that a CommsDataObject supports.

   121 	The framework will not allow requests for unsupported operations.

   122 	*/

   123 	enum

   124 		{

   125 		/** The CommsDataObject supports storing its data on a provider */

   126 		ESetSupported = 1,

   127 

   128 		/** The CommsDataObject supports retreiving data from a provider */

   129 		EGetSupported = 2,

   130 

   131 		/** The CommsDataObject is required to progressively be dispatched

   132 		on all providers supporting the required interface. When this flag

   133 		is present the framework will listen to the TProgressAction returned

   134 		by the DispatchL() method */

   135 		EProgressive = 4,

   136 		

   137 		/**

   138 		Mask that covers all operation flags

   139 		*/

   140 		EOperationSupportMask = ESetSupported | EGetSupported,

   141 		

   142 		/**

   143 		Mask that covers all currently used flags

   144 		*/

   145 		EAllFlags = ESetSupported | EGetSupported | EProgressive,

   146 		};

   147 

   148 	

   149 	/**

   150 	Constructor for the CommsDataObject.

   151 	

   152 	This version of the constructor will default to providing a 

   153 	MAccessPointConfigApi interface when the CommsDataObject is dispatched.

   154 	

   155 	@param aFlags Flags that identify the operations supported by, and

   156 	desired framework handling of the CommsDataObject. Only use flags

   157 	supported by XCommsDataObject. The CommsDataObject must support at

   158 	least the Get or Set operation.

   159 	

   160 	@see MAccessPointConfigApi

   161 	*/

   162 	XCommsDataObject(TUint aFlags)

   163 		: iReqItfExtId((TUint)EAccessPointConfigApi), iFlags(aFlags)

   164 		{

   165 		__ASSERT_DEBUG((aFlags & ~EAllFlags) == 0, User::Panic(KSpecAssert_ESocks_cmsdtbjct, 1));

   166 		__ASSERT_DEBUG((aFlags & EOperationSupportMask) != 0, User::Panic(KSpecAssert_ESocks_cmsdtbjct, 2));

   167 		}

   168 

   169 	

   170 	/**

   171 	Constructor for the CommsDataObject.

   172 	

   173 	@param aFlags Flags that identify the operations supported by, and

   174 	desired framework handling of the CommsDataObject. Only use flags

   175 	supported by XCommsDataObject. The CommsDataObject must support at

   176 	least the Get or Set operation.

   177 	

   178 	@param aReqItfExtId An interface identifier from TSupportedCommsApiExt.

   179 	*/

   180 	XCommsDataObject(TUint aFlags, TUint aReqItfExtId)

   181 		: iReqItfExtId(aReqItfExtId), iFlags(aFlags)

   182 		{

   183 		__ASSERT_DEBUG((aFlags & ~EAllFlags) == 0, User::Panic(KSpecAssert_ESocks_cmsdtbjct, 3));

   184 		__ASSERT_DEBUG((aFlags & EOperationSupportMask) != 0, User::Panic(KSpecAssert_ESocks_cmsdtbjct, 4));

   185 		}

   186 

   187 	

   188 	/**

   189 	Called by the framework. Needs to be implemented by the CommsDataObject to perform

   190 	the operation indicated by OperationMode().

   191 	

   192 	@param aItfPtr A pointer to the interface that the CommsDataObject has requested.

   193 	@param aItfPtr A pointer to a ESock::MPlatsecApiExt interface to be used for any

   194 	required platsec checks.

   195 	

   196 	@return A value from TProgressAction indicating whether or not the CommsDataObject

   197 	has finished its operation. Should always be EComplete if the object does not support

   198 	the EProgressive operation.

   199 	

   200 	@see ESock::MPlatsecApiExt

   201 	*/

   202 	virtual TProgressAction DispatchL(TAny* aItfPtr, ESock::MPlatsecApiExt* aPlatsecItf) = 0;

   203 

   204 	/**

   205 	@return The operation requested by the client.

   206 	*/

   207 	inline TUint OperationMode() const

   208 		{

   209 		return iOperationMode;

   210 		}

   211 		

   212 	/**

   213 	@return The supported operation flags

   214 	*/

   215 	inline TUint Flags() const

   216 		{

   217 		return iFlags;

   218 		}

   219 

   220 private:		

   221     /**

   222 	Used internally to set the operation mode requested by the client.

   223 	*/

   224 	inline void SetOperationMode(TUint aMode)

   225 		{

   226 		iOperationMode = aMode;

   227 		}

   228 	

   229 protected:

   230 	EXPORT_DATA_VTABLE_AND_FN	

   231 	

   232 private:

   233 	TUint iOperationMode;

   234 	TUint iReqItfExtId;

   235 	TUint iFlags;

   236 	};

   237 

   238 

   239 /**

   240 Container class for the XCommsDataObject. Responsible for

   241 owning, serialising, and deserialising the CommsDataObject during API

   242 calls

   243 

   244 Note: A CommsDataObject has no connection to the similarly named CommsDat

   245 database or any of its associated classes.

   246 

   247 @see XCommsDataObject

   248 */

   249 class CCommsDataObjectBase : public CBase, public Meta::MMetaType

   250 	{

   251 	friend class ::RConnection;	

   252 	

   253 public:

   254 	/**

   255 	NewL for the CCommsDataObject class.

   256 	@param aDataObject A ptr to the data object to take ownership of

   257 	*/

   258 	IMPORT_C static CCommsDataObjectBase* NewL(XCommsDataObject* aDataObject);

   259 	IMPORT_C static CCommsDataObjectBase* LoadL(TPtrC8& aBuffer);

   260 	

   261 	/**

   262 	@D'tor for the CCommsDataObject class

   263 	*/

   264 	IMPORT_C ~CCommsDataObjectBase();

   265 

   266 	// From  Meta::MetaType

   267 	IMPORT_C virtual TInt Load(TPtrC8& aBuffer);

   268 	IMPORT_C virtual TInt Store(TDes8& aBuffer) const;

   269     IMPORT_C virtual void Copy(const TAny* aData);

   270 	IMPORT_C virtual TInt Length() const;

   271 	

   272 protected:

   273 	/**

   274 	C'tor for the CCommsDataObject class.

   275 	@param aDataObject A ptr to the data object to take ownership of

   276 	*/

   277 	IMPORT_C CCommsDataObjectBase(XCommsDataObject* aDataObject);

   278 

   279 protected:

   280 	XCommsDataObject* iDataObject;

   281 	};

   282 

   283 

   284 /**

   285 Thin wrapper template class to provide type safety around CCommsDataObjectBase

   286 */

   287 template<class SUBCLASS, class XCLASS>

   288 class CCommsDataObject : public CCommsDataObjectBase

   289 	{

   290 public:	

   291 	inline static SUBCLASS* NewL(XCLASS* aDataObject)

   292 		{

   293 		__ASSERT_DEBUG(aDataObject, User::Panic(KSpecAssert_ESocks_cmsdtbjct, 5));

   294 		if (XCLASS::TypeId() != aDataObject->GetTypeId()) 

   295 			{

   296 			User::Leave(KErrArgument);

   297 			}

   298 		return static_cast<SUBCLASS*>(CCommsDataObjectBase::NewL(aDataObject));

   299 		}

   300 		

   301 	inline static SUBCLASS* LoadL(TPtrC8& aBuffer)

   302 		{

   303 		TPtrC8 typeCheckPtr(aBuffer);

   304 		STypeId typeId = STypeId::CreateSTypeId(typeCheckPtr);

   305 		if (XCLASS::TypeId() != typeId) 

   306 			{

   307 			User::Leave(KErrCorrupt);

   308 			}

   309 		return static_cast<SUBCLASS*>(CCommsDataObjectBase::LoadL(aBuffer));

   310 		}

   311 

   312     inline XCLASS& DataObject()

   313         {

   314         return static_cast<XCLASS&>(*iDataObject);

   315         }

   316 

   317 protected:

   318     inline CCommsDataObject(XCommsDataObject* aDataObject)

   319         : CCommsDataObjectBase(aDataObject)

   320         {

   321         }

   322 	};

   323 

   324 } // namespace ESock

   325 

   326 #endif

   327 // ES_COMMSDATAOBJECT_H

   328