epoc32/include/comms-infras/es_parameterbundle.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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 // Generic parameter bundles:
    15 // Serialisable containers for structured custom data.
    16 // Bundle
    17 // has 0..n
    18 // Parameter Set Containers
    19 // each of which has 0..n
    20 // ParameterSets
    21 // This can be seen as loosely mapping to a "table" of data,
    22 // where the
    23 // "table"
    24 // has 0..n
    25 // "rows"
    26 // each of which has 0..n
    27 // "groups of columns"
    28 // Custom data is implemented as ParameterSet-derived classes in ECom plugins. See esock/conn_params for an example
    29 // 
    30 //
    31 // Note: Every effort should be made to ensure that the classes forming this API be kept consistent with each other
    32 // When making changes to these classes also see the files es_parameterbundle.h, es_parameterfamily.h,
    33 // ss_parameterfamilybundle.h
    34 //
    35 //
    36 
    37 
    38 /**
    39  @file
    40  @internalTechnology
    41 */
    42 
    43 
    44 #ifndef ES_PARAMETERBUNDLE_H
    45 #define ES_PARAMETERBUNDLE_H
    46 
    47 #include <comms-infras/metacontainer.h>
    48 #include <comms-infras/metatype.h>
    49 #include <es_sock.h>
    50 #include <comms-infras/es_parameterset.h>
    51 	
    52 class CParameterBundleBase;
    53 
    54 
    55 class CParameterSetContainer : public CBase, public Meta::MMetaType
    56 /**
    57  * A container for 0..n Parameter Sets.
    58  * Can be seen as a "row" or "record" of information,
    59  *  with its own 32 bit Id to be used as a key to the set if required 
    60  * */
    61 	{
    62 public:
    63 	IMPORT_C static CParameterSetContainer* NewL(CParameterBundleBase& aBundle, TUint32 aContainerId = 0);
    64 	IMPORT_C static CParameterSetContainer* LoadL(CParameterBundleBase& aBundle, TPtrC8& aBuffer);
    65 
    66 	IMPORT_C static CParameterSetContainer* NewL(TUint32 aContainerId = 0); // Use this constructor if the container is to live independently of a bundle
    67 	IMPORT_C static CParameterSetContainer* LoadL(TPtrC8& aBuffer);
    68 
    69 public:
    70 	IMPORT_C virtual ~CParameterSetContainer();
    71 	
    72 	inline TUint32 Id() const
    73 		{
    74 		return iContainerId;
    75 		}
    76 
    77 	IMPORT_C void AddParameterSetL(XParameterSetBase* aParameterSet); // ownership of object is passed
    78 	IMPORT_C TInt AddParameterSet(XParameterSetBase* aParameterSet); // ownership of object is passed
    79 
    80 	/**
    81 	Searches a container for a parameter set of the given type.
    82 	@param aSetId The STypeId of the set
    83 	@return Pointer to the set if found, otherwise a NULL pointer.
    84 	*/
    85 	IMPORT_C XParameterSetBase* FindParameterSet(const Meta::STypeId& aSetId);
    86 
    87 	const XParameterSetBase* FindParameterSet(const Meta::STypeId& aSetId) const
    88 		{
    89 		return const_cast<CParameterSetContainer*>(this)->FindParameterSet(aSetId);
    90 		}
    91 
    92 	/**
    93 	Searches a container for a specific parameter set instance.
    94 	@param aRhs The parameter set to find
    95 	@return ETrue if set was found in parameter set container.
    96 	*/
    97 	IMPORT_C TBool FindParameterSet(const XParameterSetBase& aRhs);
    98 	IMPORT_C XParameterSetBase* GetParameterSet(TInt aIndex);
    99 
   100 	const XParameterSetBase* GetParameterSet(TInt aIndex) const
   101 		{
   102 		return const_cast<CParameterSetContainer*>(this)->GetParameterSet(aIndex);
   103 		}
   104 
   105 	TInt CountParameterSets() const
   106 		{
   107 		return iParameterSets.Count();
   108 		}
   109 
   110 	/** Deletes set at index aIndex and replaces it with aParameterSet.
   111 		Ownership of set passes to this parameter set container.
   112 	@param aIndex - index of container to delete and replace
   113 	@param aParameterSet - new set to replace in array
   114 	@return throws KErrArgument if aIndex out of range
   115 	*/
   116 	IMPORT_C void ReplaceParameterSetL(TInt aIndex, XParameterSetBase* aNewSet);
   117 	IMPORT_C TInt ReplaceParameterSet(TInt aIndex, XParameterSetBase* aNewSet);
   118 
   119 	/** Deletes set at index, and reorganises the array so it's 1 smaller
   120 	@param aIndex - index of container to delete and remove from array
   121 	@return throws KErrArgument if aIndex out of range
   122 	*/
   123 	IMPORT_C void DeleteParameterSetL(TInt aIndex);
   124 	IMPORT_C TInt DeleteParameterSet(TInt aIndex);
   125 	
   126 	/**
   127 	Removes the parameter set at the index. Ownership is transfered to the calling method
   128 	@param aIndex - index of container to delete and remove from array
   129 	@return returns NULL if the index was invalid, otherwise a pointer to the
   130 	removed parameter set. 
   131 	*/
   132 	IMPORT_C XParameterSetBase* RemoveParameterSet(TInt aIndex);
   133 
   134 	/** Makes room for a bulk setting operation
   135 	*/
   136 	IMPORT_C void GrowToFitL(TInt aMinSize);
   137 	IMPORT_C TInt GrowToFit(TInt aMinSize);
   138 	
   139 	inline void ClearParameterSetPointer(TInt aIndex)
   140 		{
   141 		iParameterSets[aIndex] = 0;
   142 		}
   143 
   144 	// From MMetaType
   145 	IMPORT_C virtual TInt Load(TPtrC8& aBuffer);
   146 	IMPORT_C virtual TInt Store(TDes8& aBuffer) const;
   147 	IMPORT_C virtual TInt Length() const;
   148     			
   149 protected:
   150 	CParameterSetContainer(TUint32 aContainerId)
   151 		: iContainerId(aContainerId)
   152 		{
   153 		}
   154 		
   155 	IMPORT_C void ConstructL(CParameterBundleBase& aBundle);
   156 
   157 
   158 private:
   159 	// From MMetaType
   160     virtual void Copy(const TAny* /*aData*/)
   161     	{
   162     	// Not supported
   163     	}
   164 
   165 	TUint32 iContainerId;
   166 	Meta::RMetaDataEComContainer iParameterSets;
   167 	};
   168 
   169 
   170 class CParameterBundleBase : public CBase
   171 /** Bundle of (i.e. container for) parameter set containers.
   172 
   173 The basic object shape and base type container manipulators.
   174 To be used only by CParameterBundle<PARAMETERSETCONTAINERTYPE,SUBCLASS>
   175 
   176 May contain and 0..N parameter families.
   177 */
   178 	{
   179 public:
   180 	static inline CParameterBundleBase* NewL()
   181 		{
   182 		return new(ELeave) CParameterBundleBase;
   183 		}
   184 
   185 	IMPORT_C virtual ~CParameterBundleBase();
   186 
   187 	IMPORT_C TUint Length() const;
   188 
   189 	IMPORT_C TInt Store(TDes8& aDes) const;
   190 	
   191 	// Load() can't be in base type as it requires static call to specific parameter set container type
   192 
   193 	IMPORT_C void AddParamSetContainerL(CParameterSetContainer& aContainer);
   194 	IMPORT_C TInt AddParamSetContainer(CParameterSetContainer& aContainer);
   195 
   196 	IMPORT_C CParameterSetContainer* RemoveParamSetContainer(TInt aIndex);
   197 	
   198 	TInt CountParamSetContainers() const
   199 		{
   200 		return iSetContainers.Count();
   201 		}
   202 
   203 	IMPORT_C CParameterSetContainer* GetParamSetContainer(TInt aIndex);
   204 
   205 	const CParameterSetContainer* GetParamSetContainer(TInt aIndex) const
   206 		{
   207 		return const_cast<CParameterBundleBase*>(this)->GetParamSetContainer(aIndex);
   208 		}
   209 
   210 	IMPORT_C CParameterSetContainer* FindParamSetContainer(TUint32 aContainerId);
   211 	inline const CParameterSetContainer* FindParamSetContainer(TUint32 aContainerId) const
   212 		{
   213 		const CParameterSetContainer* r = const_cast<CParameterBundleBase*>(this)->FindParamSetContainer(aContainerId);
   214 		return r;
   215 		}
   216 
   217 	// deep search for parameter set in bundle
   218 	IMPORT_C XParameterSetBase* FindParameterSet(const Meta::STypeId& aTypeId);
   219 	inline const XParameterSetBase* FindParameterSet(const Meta::STypeId& aTypeId) const
   220 		{
   221 		const XParameterSetBase* r = const_cast<CParameterBundleBase*>(this)->FindParameterSet(aTypeId);
   222 		return r;
   223 		}
   224 
   225 	// finds aOld in array, deletes it and changes that pointer in array to be aNew instead.
   226 	// throws KErrArgument if aOld is not found
   227 	IMPORT_C void ReplaceParamSetContainerL(CParameterSetContainer* aOld, CParameterSetContainer* aNew);
   228 	IMPORT_C TInt ReplaceParamSetContainer(CParameterSetContainer* aOld, CParameterSetContainer* aNew);
   229 
   230 protected:
   231 	CParameterBundleBase()
   232 		{
   233 		}
   234 
   235 private:
   236 	CParameterBundleBase(const CParameterBundleBase& aBundle);
   237 	CParameterBundleBase& operator=(const CParameterBundleBase& aBundle);
   238 
   239 protected:
   240 	RPointerArray<CParameterSetContainer> iSetContainers;
   241 };
   242 
   243 
   244 template<class PARAMSETCONTAINERTYPE, class SUBCLASS, TInt UID, TInt TYPE>
   245 class MParameterSetTemplateMethods
   246 /**
   247  * methods brought in as a template, to avoid having to rewrite
   248  * identical-looking code in every derived type of XParameterSetBase 
   249 */
   250 	{
   251 public:
   252 	static inline SUBCLASS* NewL(PARAMSETCONTAINERTYPE& aContainer)
   253 		{
   254 		SUBCLASS* obj = NewL();
   255 		CleanupStack::PushL(obj);
   256 		aContainer.AddParameterSetL(obj);
   257 		CleanupStack::Pop(obj);
   258 		return obj;
   259 		}
   260 
   261 	static inline Meta::STypeId Type()
   262 		{
   263 		return Meta::STypeId::CreateSTypeId(UID,TYPE);
   264 		}
   265 
   266 	static inline SUBCLASS* NewL()
   267 		{
   268 		// As it's a plugin we must instantiate via the plugin interface!
   269 		//  Directly calling the constructor would cause a link error as
   270 		//   the vtable won't be visible by whoever uses this.
   271 		//  So we need ECom to import it for us.
   272 		return static_cast<SUBCLASS*>(Meta::SMetaDataECom::NewInstanceL(Type()));
   273 		}
   274 		
   275 	static inline SUBCLASS* FindInParamSetContainer(PARAMSETCONTAINERTYPE& aContainer)
   276 		{
   277 		return static_cast<SUBCLASS*>(aContainer.FindParameterSet(Type()));
   278 		}
   279 		
   280 	static inline const SUBCLASS* FindInParamSetContainer(const PARAMSETCONTAINERTYPE& aContainer)
   281 		{
   282 		return static_cast<const SUBCLASS*>(aContainer.FindParameterSet(Type()));
   283 		}		
   284 
   285 	static inline SUBCLASS* FindInBundle(CParameterBundleBase& aBundle)
   286 		{
   287 		return static_cast<SUBCLASS*>(aBundle.FindParameterSet(Type()));
   288 		}
   289 		
   290 	static inline const SUBCLASS* FindInBundle(const CParameterBundleBase& aBundle)
   291 		{
   292 		return static_cast<const SUBCLASS*>(aBundle.FindParameterSet(Type()));
   293 		}		
   294 	};
   295 
   296 
   297 template<class PARAMSETCONTAINERTYPE,class SUBCLASS>
   298 class CParameterBundle : public CParameterBundleBase
   299 /** Container for (bundle of) parameter set containers.
   300 
   301 This class can't be used directly, but must be subclassed, as the NewL/LoadL refer to
   302 the subclass.
   303 
   304 May contain and 0..N parameter families of type PARAMSETCONTAINERTYPE.
   305 */
   306 {
   307 public:
   308 
   309 	static SUBCLASS* NewL()
   310 	/** Creates a new instance of a parameter bundle (heap object).
   311 	
   312 	@return newly created instance of a parameter bundle
   313 	@exception leaves with KErrNoMemory in out of memory conditions
   314 	*/
   315 		{
   316 		return new (ELeave) SUBCLASS();
   317 		}
   318 
   319 	static SUBCLASS* LoadL(TDesC8& aDes)
   320 	/** Creates a new parameter set bundle from a buffer containing the serialised object.
   321 	
   322 	@param aDes Buffer containing the serialised object information
   323 	@return a pointer to a parameter bundle if successful, otherwise leaves with system error code.
   324 	*/
   325 		{
   326 		SUBCLASS* obj = new (ELeave) SUBCLASS();
   327 		CleanupStack::PushL(obj);
   328 		User::LeaveIfError(obj->Load(aDes));
   329 		CleanupStack::Pop(obj);
   330 		return obj;
   331 		}
   332 
   333 	TInt Load(const TDesC8& aDes)
   334 	/** Instructs this sub-connection bundle to set its members based on the serialiesd data
   335 		in the buffer passed.
   336 
   337 	@param aDes Buffer containing the serialised bundle object
   338 	@return KErrNone if successful, otherwise system wide error
   339 	*/
   340 		{
   341 		TPtrC8 buf(aDes);
   342 		while (buf.Length() > 0)
   343 			{
   344 			TRAPD(ret, PARAMSETCONTAINERTYPE::LoadL(*(static_cast<SUBCLASS*>(this)), buf));
   345 			if (ret != KErrNone)
   346 				{
   347 				iSetContainers.ResetAndDestroy();
   348 				return ret;
   349 				}
   350 			}
   351 		return KErrNone;
   352 		}
   353 
   354 	inline PARAMSETCONTAINERTYPE* GetParamSetContainer(TInt aIndex)
   355 		{
   356 		return static_cast<PARAMSETCONTAINERTYPE*>(CParameterBundleBase::GetParamSetContainer(aIndex));
   357 		}
   358 
   359 	inline const PARAMSETCONTAINERTYPE* GetParamSetContainer(TInt aIndex) const
   360 		{
   361 		return static_cast<const PARAMSETCONTAINERTYPE*>(CParameterBundleBase::GetParamSetContainer(aIndex));
   362 		}
   363 
   364 	inline PARAMSETCONTAINERTYPE* FindParamSetContainer(TUint32 aContainerId)
   365 		{
   366 		return static_cast<PARAMSETCONTAINERTYPE*>(CParameterBundleBase::FindParamSetContainer(aContainerId));
   367 		}
   368 
   369 protected:
   370 	CParameterBundle()
   371 		{
   372 		}
   373 };
   374 
   375 
   376 class CGenericParameterBundle : public CParameterBundle<CParameterSetContainer,CGenericParameterBundle>
   377 	{
   378 	};
   379 
   380 
   381 
   382 
   383 #endif
   384 // ES_PARAMETERBUNDLE_H
   385 
   386