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 +