epoc32/include/comms-infras/es_parameterbundle.h
branchSymbian3
changeset 4 837f303aceeb
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/epoc32/include/comms-infras/es_parameterbundle.h	Wed Mar 31 12:33:34 2010 +0100
     1.3 @@ -0,0 +1,386 @@
     1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
     1.5 +// All rights reserved.
     1.6 +// This component and the accompanying materials are made available
     1.7 +// under the terms of "Eclipse Public License v1.0"
     1.8 +// which accompanies this distribution, and is available
     1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
    1.10 +//
    1.11 +// Initial Contributors:
    1.12 +// Nokia Corporation - initial contribution.
    1.13 +//
    1.14 +// Contributors:
    1.15 +//
    1.16 +// Description:
    1.17 +// Generic parameter bundles:
    1.18 +// Serialisable containers for structured custom data.
    1.19 +// Bundle
    1.20 +// has 0..n
    1.21 +// Parameter Set Containers
    1.22 +// each of which has 0..n
    1.23 +// ParameterSets
    1.24 +// This can be seen as loosely mapping to a "table" of data,
    1.25 +// where the
    1.26 +// "table"
    1.27 +// has 0..n
    1.28 +// "rows"
    1.29 +// each of which has 0..n
    1.30 +// "groups of columns"
    1.31 +// Custom data is implemented as ParameterSet-derived classes in ECom plugins. See esock/conn_params for an example
    1.32 +// 
    1.33 +//
    1.34 +// Note: Every effort should be made to ensure that the classes forming this API be kept consistent with each other
    1.35 +// When making changes to these classes also see the files es_parameterbundle.h, es_parameterfamily.h,
    1.36 +// ss_parameterfamilybundle.h
    1.37 +//
    1.38 +//
    1.39 +
    1.40 +
    1.41 +/**
    1.42 + @file
    1.43 + @internalTechnology
    1.44 +*/
    1.45 +
    1.46 +
    1.47 +#ifndef ES_PARAMETERBUNDLE_H
    1.48 +#define ES_PARAMETERBUNDLE_H
    1.49 +
    1.50 +#include <comms-infras/metacontainer.h>
    1.51 +#include <comms-infras/metatype.h>
    1.52 +#include <es_sock.h>
    1.53 +#include <comms-infras/es_parameterset.h>
    1.54 +	
    1.55 +class CParameterBundleBase;
    1.56 +
    1.57 +
    1.58 +class CParameterSetContainer : public CBase, public Meta::MMetaType
    1.59 +/**
    1.60 + * A container for 0..n Parameter Sets.
    1.61 + * Can be seen as a "row" or "record" of information,
    1.62 + *  with its own 32 bit Id to be used as a key to the set if required 
    1.63 + * */
    1.64 +	{
    1.65 +public:
    1.66 +	IMPORT_C static CParameterSetContainer* NewL(CParameterBundleBase& aBundle, TUint32 aContainerId = 0);
    1.67 +	IMPORT_C static CParameterSetContainer* LoadL(CParameterBundleBase& aBundle, TPtrC8& aBuffer);
    1.68 +
    1.69 +	IMPORT_C static CParameterSetContainer* NewL(TUint32 aContainerId = 0); // Use this constructor if the container is to live independently of a bundle
    1.70 +	IMPORT_C static CParameterSetContainer* LoadL(TPtrC8& aBuffer);
    1.71 +
    1.72 +public:
    1.73 +	IMPORT_C virtual ~CParameterSetContainer();
    1.74 +	
    1.75 +	inline TUint32 Id() const
    1.76 +		{
    1.77 +		return iContainerId;
    1.78 +		}
    1.79 +
    1.80 +	IMPORT_C void AddParameterSetL(XParameterSetBase* aParameterSet); // ownership of object is passed
    1.81 +	IMPORT_C TInt AddParameterSet(XParameterSetBase* aParameterSet); // ownership of object is passed
    1.82 +
    1.83 +	/**
    1.84 +	Searches a container for a parameter set of the given type.
    1.85 +	@param aSetId The STypeId of the set
    1.86 +	@return Pointer to the set if found, otherwise a NULL pointer.
    1.87 +	*/
    1.88 +	IMPORT_C XParameterSetBase* FindParameterSet(const Meta::STypeId& aSetId);
    1.89 +
    1.90 +	const XParameterSetBase* FindParameterSet(const Meta::STypeId& aSetId) const
    1.91 +		{
    1.92 +		return const_cast<CParameterSetContainer*>(this)->FindParameterSet(aSetId);
    1.93 +		}
    1.94 +
    1.95 +	/**
    1.96 +	Searches a container for a specific parameter set instance.
    1.97 +	@param aRhs The parameter set to find
    1.98 +	@return ETrue if set was found in parameter set container.
    1.99 +	*/
   1.100 +	IMPORT_C TBool FindParameterSet(const XParameterSetBase& aRhs);
   1.101 +	IMPORT_C XParameterSetBase* GetParameterSet(TInt aIndex);
   1.102 +
   1.103 +	const XParameterSetBase* GetParameterSet(TInt aIndex) const
   1.104 +		{
   1.105 +		return const_cast<CParameterSetContainer*>(this)->GetParameterSet(aIndex);
   1.106 +		}
   1.107 +
   1.108 +	TInt CountParameterSets() const
   1.109 +		{
   1.110 +		return iParameterSets.Count();
   1.111 +		}
   1.112 +
   1.113 +	/** Deletes set at index aIndex and replaces it with aParameterSet.
   1.114 +		Ownership of set passes to this parameter set container.
   1.115 +	@param aIndex - index of container to delete and replace
   1.116 +	@param aParameterSet - new set to replace in array
   1.117 +	@return throws KErrArgument if aIndex out of range
   1.118 +	*/
   1.119 +	IMPORT_C void ReplaceParameterSetL(TInt aIndex, XParameterSetBase* aNewSet);
   1.120 +	IMPORT_C TInt ReplaceParameterSet(TInt aIndex, XParameterSetBase* aNewSet);
   1.121 +
   1.122 +	/** Deletes set at index, and reorganises the array so it's 1 smaller
   1.123 +	@param aIndex - index of container to delete and remove from array
   1.124 +	@return throws KErrArgument if aIndex out of range
   1.125 +	*/
   1.126 +	IMPORT_C void DeleteParameterSetL(TInt aIndex);
   1.127 +	IMPORT_C TInt DeleteParameterSet(TInt aIndex);
   1.128 +	
   1.129 +	/**
   1.130 +	Removes the parameter set at the index. Ownership is transfered to the calling method
   1.131 +	@param aIndex - index of container to delete and remove from array
   1.132 +	@return returns NULL if the index was invalid, otherwise a pointer to the
   1.133 +	removed parameter set. 
   1.134 +	*/
   1.135 +	IMPORT_C XParameterSetBase* RemoveParameterSet(TInt aIndex);
   1.136 +
   1.137 +	/** Makes room for a bulk setting operation
   1.138 +	*/
   1.139 +	IMPORT_C void GrowToFitL(TInt aMinSize);
   1.140 +	IMPORT_C TInt GrowToFit(TInt aMinSize);
   1.141 +	
   1.142 +	inline void ClearParameterSetPointer(TInt aIndex)
   1.143 +		{
   1.144 +		iParameterSets[aIndex] = 0;
   1.145 +		}
   1.146 +
   1.147 +	// From MMetaType
   1.148 +	IMPORT_C virtual TInt Load(TPtrC8& aBuffer);
   1.149 +	IMPORT_C virtual TInt Store(TDes8& aBuffer) const;
   1.150 +	IMPORT_C virtual TInt Length() const;
   1.151 +    			
   1.152 +protected:
   1.153 +	CParameterSetContainer(TUint32 aContainerId)
   1.154 +		: iContainerId(aContainerId)
   1.155 +		{
   1.156 +		}
   1.157 +		
   1.158 +	IMPORT_C void ConstructL(CParameterBundleBase& aBundle);
   1.159 +
   1.160 +
   1.161 +private:
   1.162 +	// From MMetaType
   1.163 +    virtual void Copy(const TAny* /*aData*/)
   1.164 +    	{
   1.165 +    	// Not supported
   1.166 +    	}
   1.167 +
   1.168 +	TUint32 iContainerId;
   1.169 +	Meta::RMetaDataEComContainer iParameterSets;
   1.170 +	};
   1.171 +
   1.172 +
   1.173 +class CParameterBundleBase : public CBase
   1.174 +/** Bundle of (i.e. container for) parameter set containers.
   1.175 +
   1.176 +The basic object shape and base type container manipulators.
   1.177 +To be used only by CParameterBundle<PARAMETERSETCONTAINERTYPE,SUBCLASS>
   1.178 +
   1.179 +May contain and 0..N parameter families.
   1.180 +*/
   1.181 +	{
   1.182 +public:
   1.183 +	static inline CParameterBundleBase* NewL()
   1.184 +		{
   1.185 +		return new(ELeave) CParameterBundleBase;
   1.186 +		}
   1.187 +
   1.188 +	IMPORT_C virtual ~CParameterBundleBase();
   1.189 +
   1.190 +	IMPORT_C TUint Length() const;
   1.191 +
   1.192 +	IMPORT_C TInt Store(TDes8& aDes) const;
   1.193 +	
   1.194 +	// Load() can't be in base type as it requires static call to specific parameter set container type
   1.195 +
   1.196 +	IMPORT_C void AddParamSetContainerL(CParameterSetContainer& aContainer);
   1.197 +	IMPORT_C TInt AddParamSetContainer(CParameterSetContainer& aContainer);
   1.198 +
   1.199 +	IMPORT_C CParameterSetContainer* RemoveParamSetContainer(TInt aIndex);
   1.200 +	
   1.201 +	TInt CountParamSetContainers() const
   1.202 +		{
   1.203 +		return iSetContainers.Count();
   1.204 +		}
   1.205 +
   1.206 +	IMPORT_C CParameterSetContainer* GetParamSetContainer(TInt aIndex);
   1.207 +
   1.208 +	const CParameterSetContainer* GetParamSetContainer(TInt aIndex) const
   1.209 +		{
   1.210 +		return const_cast<CParameterBundleBase*>(this)->GetParamSetContainer(aIndex);
   1.211 +		}
   1.212 +
   1.213 +	IMPORT_C CParameterSetContainer* FindParamSetContainer(TUint32 aContainerId);
   1.214 +	inline const CParameterSetContainer* FindParamSetContainer(TUint32 aContainerId) const
   1.215 +		{
   1.216 +		const CParameterSetContainer* r = const_cast<CParameterBundleBase*>(this)->FindParamSetContainer(aContainerId);
   1.217 +		return r;
   1.218 +		}
   1.219 +
   1.220 +	// deep search for parameter set in bundle
   1.221 +	IMPORT_C XParameterSetBase* FindParameterSet(const Meta::STypeId& aTypeId);
   1.222 +	inline const XParameterSetBase* FindParameterSet(const Meta::STypeId& aTypeId) const
   1.223 +		{
   1.224 +		const XParameterSetBase* r = const_cast<CParameterBundleBase*>(this)->FindParameterSet(aTypeId);
   1.225 +		return r;
   1.226 +		}
   1.227 +
   1.228 +	// finds aOld in array, deletes it and changes that pointer in array to be aNew instead.
   1.229 +	// throws KErrArgument if aOld is not found
   1.230 +	IMPORT_C void ReplaceParamSetContainerL(CParameterSetContainer* aOld, CParameterSetContainer* aNew);
   1.231 +	IMPORT_C TInt ReplaceParamSetContainer(CParameterSetContainer* aOld, CParameterSetContainer* aNew);
   1.232 +
   1.233 +protected:
   1.234 +	CParameterBundleBase()
   1.235 +		{
   1.236 +		}
   1.237 +
   1.238 +private:
   1.239 +	CParameterBundleBase(const CParameterBundleBase& aBundle);
   1.240 +	CParameterBundleBase& operator=(const CParameterBundleBase& aBundle);
   1.241 +
   1.242 +protected:
   1.243 +	RPointerArray<CParameterSetContainer> iSetContainers;
   1.244 +};
   1.245 +
   1.246 +
   1.247 +template<class PARAMSETCONTAINERTYPE, class SUBCLASS, TInt UID, TInt TYPE>
   1.248 +class MParameterSetTemplateMethods
   1.249 +/**
   1.250 + * methods brought in as a template, to avoid having to rewrite
   1.251 + * identical-looking code in every derived type of XParameterSetBase 
   1.252 +*/
   1.253 +	{
   1.254 +public:
   1.255 +	static inline SUBCLASS* NewL(PARAMSETCONTAINERTYPE& aContainer)
   1.256 +		{
   1.257 +		SUBCLASS* obj = NewL();
   1.258 +		CleanupStack::PushL(obj);
   1.259 +		aContainer.AddParameterSetL(obj);
   1.260 +		CleanupStack::Pop(obj);
   1.261 +		return obj;
   1.262 +		}
   1.263 +
   1.264 +	static inline Meta::STypeId Type()
   1.265 +		{
   1.266 +		return Meta::STypeId::CreateSTypeId(UID,TYPE);
   1.267 +		}
   1.268 +
   1.269 +	static inline SUBCLASS* NewL()
   1.270 +		{
   1.271 +		// As it's a plugin we must instantiate via the plugin interface!
   1.272 +		//  Directly calling the constructor would cause a link error as
   1.273 +		//   the vtable won't be visible by whoever uses this.
   1.274 +		//  So we need ECom to import it for us.
   1.275 +		return static_cast<SUBCLASS*>(Meta::SMetaDataECom::NewInstanceL(Type()));
   1.276 +		}
   1.277 +		
   1.278 +	static inline SUBCLASS* FindInParamSetContainer(PARAMSETCONTAINERTYPE& aContainer)
   1.279 +		{
   1.280 +		return static_cast<SUBCLASS*>(aContainer.FindParameterSet(Type()));
   1.281 +		}
   1.282 +		
   1.283 +	static inline const SUBCLASS* FindInParamSetContainer(const PARAMSETCONTAINERTYPE& aContainer)
   1.284 +		{
   1.285 +		return static_cast<const SUBCLASS*>(aContainer.FindParameterSet(Type()));
   1.286 +		}		
   1.287 +
   1.288 +	static inline SUBCLASS* FindInBundle(CParameterBundleBase& aBundle)
   1.289 +		{
   1.290 +		return static_cast<SUBCLASS*>(aBundle.FindParameterSet(Type()));
   1.291 +		}
   1.292 +		
   1.293 +	static inline const SUBCLASS* FindInBundle(const CParameterBundleBase& aBundle)
   1.294 +		{
   1.295 +		return static_cast<const SUBCLASS*>(aBundle.FindParameterSet(Type()));
   1.296 +		}		
   1.297 +	};
   1.298 +
   1.299 +
   1.300 +template<class PARAMSETCONTAINERTYPE,class SUBCLASS>
   1.301 +class CParameterBundle : public CParameterBundleBase
   1.302 +/** Container for (bundle of) parameter set containers.
   1.303 +
   1.304 +This class can't be used directly, but must be subclassed, as the NewL/LoadL refer to
   1.305 +the subclass.
   1.306 +
   1.307 +May contain and 0..N parameter families of type PARAMSETCONTAINERTYPE.
   1.308 +*/
   1.309 +{
   1.310 +public:
   1.311 +
   1.312 +	static SUBCLASS* NewL()
   1.313 +	/** Creates a new instance of a parameter bundle (heap object).
   1.314 +	
   1.315 +	@return newly created instance of a parameter bundle
   1.316 +	@exception leaves with KErrNoMemory in out of memory conditions
   1.317 +	*/
   1.318 +		{
   1.319 +		return new (ELeave) SUBCLASS();
   1.320 +		}
   1.321 +
   1.322 +	static SUBCLASS* LoadL(TDesC8& aDes)
   1.323 +	/** Creates a new parameter set bundle from a buffer containing the serialised object.
   1.324 +	
   1.325 +	@param aDes Buffer containing the serialised object information
   1.326 +	@return a pointer to a parameter bundle if successful, otherwise leaves with system error code.
   1.327 +	*/
   1.328 +		{
   1.329 +		SUBCLASS* obj = new (ELeave) SUBCLASS();
   1.330 +		CleanupStack::PushL(obj);
   1.331 +		User::LeaveIfError(obj->Load(aDes));
   1.332 +		CleanupStack::Pop(obj);
   1.333 +		return obj;
   1.334 +		}
   1.335 +
   1.336 +	TInt Load(const TDesC8& aDes)
   1.337 +	/** Instructs this sub-connection bundle to set its members based on the serialiesd data
   1.338 +		in the buffer passed.
   1.339 +
   1.340 +	@param aDes Buffer containing the serialised bundle object
   1.341 +	@return KErrNone if successful, otherwise system wide error
   1.342 +	*/
   1.343 +		{
   1.344 +		TPtrC8 buf(aDes);
   1.345 +		while (buf.Length() > 0)
   1.346 +			{
   1.347 +			TRAPD(ret, PARAMSETCONTAINERTYPE::LoadL(*(static_cast<SUBCLASS*>(this)), buf));
   1.348 +			if (ret != KErrNone)
   1.349 +				{
   1.350 +				iSetContainers.ResetAndDestroy();
   1.351 +				return ret;
   1.352 +				}
   1.353 +			}
   1.354 +		return KErrNone;
   1.355 +		}
   1.356 +
   1.357 +	inline PARAMSETCONTAINERTYPE* GetParamSetContainer(TInt aIndex)
   1.358 +		{
   1.359 +		return static_cast<PARAMSETCONTAINERTYPE*>(CParameterBundleBase::GetParamSetContainer(aIndex));
   1.360 +		}
   1.361 +
   1.362 +	inline const PARAMSETCONTAINERTYPE* GetParamSetContainer(TInt aIndex) const
   1.363 +		{
   1.364 +		return static_cast<const PARAMSETCONTAINERTYPE*>(CParameterBundleBase::GetParamSetContainer(aIndex));
   1.365 +		}
   1.366 +
   1.367 +	inline PARAMSETCONTAINERTYPE* FindParamSetContainer(TUint32 aContainerId)
   1.368 +		{
   1.369 +		return static_cast<PARAMSETCONTAINERTYPE*>(CParameterBundleBase::FindParamSetContainer(aContainerId));
   1.370 +		}
   1.371 +
   1.372 +protected:
   1.373 +	CParameterBundle()
   1.374 +		{
   1.375 +		}
   1.376 +};
   1.377 +
   1.378 +
   1.379 +class CGenericParameterBundle : public CParameterBundle<CParameterSetContainer,CGenericParameterBundle>
   1.380 +	{
   1.381 +	};
   1.382 +
   1.383 +
   1.384 +
   1.385 +
   1.386 +#endif
   1.387 +// ES_PARAMETERBUNDLE_H
   1.388 +
   1.389 +