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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // Generic parameter bundles:
15 // Serialisable containers for structured custom data.
18 // Parameter Set Containers
19 // each of which has 0..n
21 // This can be seen as loosely mapping to a "table" of data,
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
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
44 #ifndef ES_PARAMETERBUNDLE_H
45 #define ES_PARAMETERBUNDLE_H
47 #include <comms-infras/metacontainer.h>
48 #include <comms-infras/metatype.h>
50 #include <comms-infras/es_parameterset.h>
52 class CParameterBundleBase;
55 class CParameterSetContainer : public CBase, public Meta::MMetaType
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
63 IMPORT_C static CParameterSetContainer* NewL(CParameterBundleBase& aBundle, TUint32 aContainerId = 0);
64 IMPORT_C static CParameterSetContainer* LoadL(CParameterBundleBase& aBundle, TPtrC8& aBuffer);
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);
70 IMPORT_C virtual ~CParameterSetContainer();
72 inline TUint32 Id() const
77 IMPORT_C void AddParameterSetL(XParameterSetBase* aParameterSet); // ownership of object is passed
78 IMPORT_C TInt AddParameterSet(XParameterSetBase* aParameterSet); // ownership of object is passed
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.
85 IMPORT_C XParameterSetBase* FindParameterSet(const Meta::STypeId& aSetId);
87 const XParameterSetBase* FindParameterSet(const Meta::STypeId& aSetId) const
89 return const_cast<CParameterSetContainer*>(this)->FindParameterSet(aSetId);
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.
97 IMPORT_C TBool FindParameterSet(const XParameterSetBase& aRhs);
98 IMPORT_C XParameterSetBase* GetParameterSet(TInt aIndex);
100 const XParameterSetBase* GetParameterSet(TInt aIndex) const
102 return const_cast<CParameterSetContainer*>(this)->GetParameterSet(aIndex);
105 TInt CountParameterSets() const
107 return iParameterSets.Count();
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
116 IMPORT_C void ReplaceParameterSetL(TInt aIndex, XParameterSetBase* aNewSet);
117 IMPORT_C TInt ReplaceParameterSet(TInt aIndex, XParameterSetBase* aNewSet);
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
123 IMPORT_C void DeleteParameterSetL(TInt aIndex);
124 IMPORT_C TInt DeleteParameterSet(TInt aIndex);
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.
132 IMPORT_C XParameterSetBase* RemoveParameterSet(TInt aIndex);
134 /** Makes room for a bulk setting operation
136 IMPORT_C void GrowToFitL(TInt aMinSize);
137 IMPORT_C TInt GrowToFit(TInt aMinSize);
139 inline void ClearParameterSetPointer(TInt aIndex)
141 iParameterSets[aIndex] = 0;
145 IMPORT_C virtual TInt Load(TPtrC8& aBuffer);
146 IMPORT_C virtual TInt Store(TDes8& aBuffer) const;
147 IMPORT_C virtual TInt Length() const;
150 CParameterSetContainer(TUint32 aContainerId)
151 : iContainerId(aContainerId)
155 IMPORT_C void ConstructL(CParameterBundleBase& aBundle);
160 virtual void Copy(const TAny* /*aData*/)
165 TUint32 iContainerId;
166 Meta::RMetaDataEComContainer iParameterSets;
170 class CParameterBundleBase : public CBase
171 /** Bundle of (i.e. container for) parameter set containers.
173 The basic object shape and base type container manipulators.
174 To be used only by CParameterBundle<PARAMETERSETCONTAINERTYPE,SUBCLASS>
176 May contain and 0..N parameter families.
180 static inline CParameterBundleBase* NewL()
182 return new(ELeave) CParameterBundleBase;
185 IMPORT_C virtual ~CParameterBundleBase();
187 IMPORT_C TUint Length() const;
189 IMPORT_C TInt Store(TDes8& aDes) const;
191 // Load() can't be in base type as it requires static call to specific parameter set container type
193 IMPORT_C void AddParamSetContainerL(CParameterSetContainer& aContainer);
194 IMPORT_C TInt AddParamSetContainer(CParameterSetContainer& aContainer);
196 IMPORT_C CParameterSetContainer* RemoveParamSetContainer(TInt aIndex);
198 TInt CountParamSetContainers() const
200 return iSetContainers.Count();
203 IMPORT_C CParameterSetContainer* GetParamSetContainer(TInt aIndex);
205 const CParameterSetContainer* GetParamSetContainer(TInt aIndex) const
207 return const_cast<CParameterBundleBase*>(this)->GetParamSetContainer(aIndex);
210 IMPORT_C CParameterSetContainer* FindParamSetContainer(TUint32 aContainerId);
211 inline const CParameterSetContainer* FindParamSetContainer(TUint32 aContainerId) const
213 const CParameterSetContainer* r = const_cast<CParameterBundleBase*>(this)->FindParamSetContainer(aContainerId);
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
221 const XParameterSetBase* r = const_cast<CParameterBundleBase*>(this)->FindParameterSet(aTypeId);
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);
231 CParameterBundleBase()
236 CParameterBundleBase(const CParameterBundleBase& aBundle);
237 CParameterBundleBase& operator=(const CParameterBundleBase& aBundle);
240 RPointerArray<CParameterSetContainer> iSetContainers;
244 template<class PARAMSETCONTAINERTYPE, class SUBCLASS, TInt UID, TInt TYPE>
245 class MParameterSetTemplateMethods
247 * methods brought in as a template, to avoid having to rewrite
248 * identical-looking code in every derived type of XParameterSetBase
252 static inline SUBCLASS* NewL(PARAMSETCONTAINERTYPE& aContainer)
254 SUBCLASS* obj = NewL();
255 CleanupStack::PushL(obj);
256 aContainer.AddParameterSetL(obj);
257 CleanupStack::Pop(obj);
261 static inline Meta::STypeId Type()
263 return Meta::STypeId::CreateSTypeId(UID,TYPE);
266 static inline SUBCLASS* NewL()
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()));
275 static inline SUBCLASS* FindInParamSetContainer(PARAMSETCONTAINERTYPE& aContainer)
277 return static_cast<SUBCLASS*>(aContainer.FindParameterSet(Type()));
280 static inline const SUBCLASS* FindInParamSetContainer(const PARAMSETCONTAINERTYPE& aContainer)
282 return static_cast<const SUBCLASS*>(aContainer.FindParameterSet(Type()));
285 static inline SUBCLASS* FindInBundle(CParameterBundleBase& aBundle)
287 return static_cast<SUBCLASS*>(aBundle.FindParameterSet(Type()));
290 static inline const SUBCLASS* FindInBundle(const CParameterBundleBase& aBundle)
292 return static_cast<const SUBCLASS*>(aBundle.FindParameterSet(Type()));
297 template<class PARAMSETCONTAINERTYPE,class SUBCLASS>
298 class CParameterBundle : public CParameterBundleBase
299 /** Container for (bundle of) parameter set containers.
301 This class can't be used directly, but must be subclassed, as the NewL/LoadL refer to
304 May contain and 0..N parameter families of type PARAMSETCONTAINERTYPE.
309 static SUBCLASS* NewL()
310 /** Creates a new instance of a parameter bundle (heap object).
312 @return newly created instance of a parameter bundle
313 @exception leaves with KErrNoMemory in out of memory conditions
316 return new (ELeave) SUBCLASS();
319 static SUBCLASS* LoadL(TDesC8& aDes)
320 /** Creates a new parameter set bundle from a buffer containing the serialised object.
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.
326 SUBCLASS* obj = new (ELeave) SUBCLASS();
327 CleanupStack::PushL(obj);
328 User::LeaveIfError(obj->Load(aDes));
329 CleanupStack::Pop(obj);
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.
337 @param aDes Buffer containing the serialised bundle object
338 @return KErrNone if successful, otherwise system wide error
342 while (buf.Length() > 0)
344 TRAPD(ret, PARAMSETCONTAINERTYPE::LoadL(*(static_cast<SUBCLASS*>(this)), buf));
347 iSetContainers.ResetAndDestroy();
354 inline PARAMSETCONTAINERTYPE* GetParamSetContainer(TInt aIndex)
356 return static_cast<PARAMSETCONTAINERTYPE*>(CParameterBundleBase::GetParamSetContainer(aIndex));
359 inline const PARAMSETCONTAINERTYPE* GetParamSetContainer(TInt aIndex) const
361 return static_cast<const PARAMSETCONTAINERTYPE*>(CParameterBundleBase::GetParamSetContainer(aIndex));
364 inline PARAMSETCONTAINERTYPE* FindParamSetContainer(TUint32 aContainerId)
366 return static_cast<PARAMSETCONTAINERTYPE*>(CParameterBundleBase::FindParamSetContainer(aContainerId));
376 class CGenericParameterBundle : public CParameterBundle<CParameterSetContainer,CGenericParameterBundle>
384 // ES_PARAMETERBUNDLE_H