--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/comms-infras/es_parameterbundle.h Wed Mar 31 12:33:34 2010 +0100
@@ -0,0 +1,386 @@
+// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+// Generic parameter bundles:
+// Serialisable containers for structured custom data.
+// Bundle
+// has 0..n
+// Parameter Set Containers
+// each of which has 0..n
+// ParameterSets
+// This can be seen as loosely mapping to a "table" of data,
+// where the
+// "table"
+// has 0..n
+// "rows"
+// each of which has 0..n
+// "groups of columns"
+// Custom data is implemented as ParameterSet-derived classes in ECom plugins. See esock/conn_params for an example
+//
+//
+// Note: Every effort should be made to ensure that the classes forming this API be kept consistent with each other
+// When making changes to these classes also see the files es_parameterbundle.h, es_parameterfamily.h,
+// ss_parameterfamilybundle.h
+//
+//
+
+
+/**
+ @file
+ @internalTechnology
+*/
+
+
+#ifndef ES_PARAMETERBUNDLE_H
+#define ES_PARAMETERBUNDLE_H
+
+#include <comms-infras/metacontainer.h>
+#include <comms-infras/metatype.h>
+#include <es_sock.h>
+#include <comms-infras/es_parameterset.h>
+
+class CParameterBundleBase;
+
+
+class CParameterSetContainer : public CBase, public Meta::MMetaType
+/**
+ * A container for 0..n Parameter Sets.
+ * Can be seen as a "row" or "record" of information,
+ * with its own 32 bit Id to be used as a key to the set if required
+ * */
+ {
+public:
+ IMPORT_C static CParameterSetContainer* NewL(CParameterBundleBase& aBundle, TUint32 aContainerId = 0);
+ IMPORT_C static CParameterSetContainer* LoadL(CParameterBundleBase& aBundle, TPtrC8& aBuffer);
+
+ IMPORT_C static CParameterSetContainer* NewL(TUint32 aContainerId = 0); // Use this constructor if the container is to live independently of a bundle
+ IMPORT_C static CParameterSetContainer* LoadL(TPtrC8& aBuffer);
+
+public:
+ IMPORT_C virtual ~CParameterSetContainer();
+
+ inline TUint32 Id() const
+ {
+ return iContainerId;
+ }
+
+ IMPORT_C void AddParameterSetL(XParameterSetBase* aParameterSet); // ownership of object is passed
+ IMPORT_C TInt AddParameterSet(XParameterSetBase* aParameterSet); // ownership of object is passed
+
+ /**
+ Searches a container for a parameter set of the given type.
+ @param aSetId The STypeId of the set
+ @return Pointer to the set if found, otherwise a NULL pointer.
+ */
+ IMPORT_C XParameterSetBase* FindParameterSet(const Meta::STypeId& aSetId);
+
+ const XParameterSetBase* FindParameterSet(const Meta::STypeId& aSetId) const
+ {
+ return const_cast<CParameterSetContainer*>(this)->FindParameterSet(aSetId);
+ }
+
+ /**
+ Searches a container for a specific parameter set instance.
+ @param aRhs The parameter set to find
+ @return ETrue if set was found in parameter set container.
+ */
+ IMPORT_C TBool FindParameterSet(const XParameterSetBase& aRhs);
+ IMPORT_C XParameterSetBase* GetParameterSet(TInt aIndex);
+
+ const XParameterSetBase* GetParameterSet(TInt aIndex) const
+ {
+ return const_cast<CParameterSetContainer*>(this)->GetParameterSet(aIndex);
+ }
+
+ TInt CountParameterSets() const
+ {
+ return iParameterSets.Count();
+ }
+
+ /** Deletes set at index aIndex and replaces it with aParameterSet.
+ Ownership of set passes to this parameter set container.
+ @param aIndex - index of container to delete and replace
+ @param aParameterSet - new set to replace in array
+ @return throws KErrArgument if aIndex out of range
+ */
+ IMPORT_C void ReplaceParameterSetL(TInt aIndex, XParameterSetBase* aNewSet);
+ IMPORT_C TInt ReplaceParameterSet(TInt aIndex, XParameterSetBase* aNewSet);
+
+ /** Deletes set at index, and reorganises the array so it's 1 smaller
+ @param aIndex - index of container to delete and remove from array
+ @return throws KErrArgument if aIndex out of range
+ */
+ IMPORT_C void DeleteParameterSetL(TInt aIndex);
+ IMPORT_C TInt DeleteParameterSet(TInt aIndex);
+
+ /**
+ Removes the parameter set at the index. Ownership is transfered to the calling method
+ @param aIndex - index of container to delete and remove from array
+ @return returns NULL if the index was invalid, otherwise a pointer to the
+ removed parameter set.
+ */
+ IMPORT_C XParameterSetBase* RemoveParameterSet(TInt aIndex);
+
+ /** Makes room for a bulk setting operation
+ */
+ IMPORT_C void GrowToFitL(TInt aMinSize);
+ IMPORT_C TInt GrowToFit(TInt aMinSize);
+
+ inline void ClearParameterSetPointer(TInt aIndex)
+ {
+ iParameterSets[aIndex] = 0;
+ }
+
+ // From MMetaType
+ IMPORT_C virtual TInt Load(TPtrC8& aBuffer);
+ IMPORT_C virtual TInt Store(TDes8& aBuffer) const;
+ IMPORT_C virtual TInt Length() const;
+
+protected:
+ CParameterSetContainer(TUint32 aContainerId)
+ : iContainerId(aContainerId)
+ {
+ }
+
+ IMPORT_C void ConstructL(CParameterBundleBase& aBundle);
+
+
+private:
+ // From MMetaType
+ virtual void Copy(const TAny* /*aData*/)
+ {
+ // Not supported
+ }
+
+ TUint32 iContainerId;
+ Meta::RMetaDataEComContainer iParameterSets;
+ };
+
+
+class CParameterBundleBase : public CBase
+/** Bundle of (i.e. container for) parameter set containers.
+
+The basic object shape and base type container manipulators.
+To be used only by CParameterBundle<PARAMETERSETCONTAINERTYPE,SUBCLASS>
+
+May contain and 0..N parameter families.
+*/
+ {
+public:
+ static inline CParameterBundleBase* NewL()
+ {
+ return new(ELeave) CParameterBundleBase;
+ }
+
+ IMPORT_C virtual ~CParameterBundleBase();
+
+ IMPORT_C TUint Length() const;
+
+ IMPORT_C TInt Store(TDes8& aDes) const;
+
+ // Load() can't be in base type as it requires static call to specific parameter set container type
+
+ IMPORT_C void AddParamSetContainerL(CParameterSetContainer& aContainer);
+ IMPORT_C TInt AddParamSetContainer(CParameterSetContainer& aContainer);
+
+ IMPORT_C CParameterSetContainer* RemoveParamSetContainer(TInt aIndex);
+
+ TInt CountParamSetContainers() const
+ {
+ return iSetContainers.Count();
+ }
+
+ IMPORT_C CParameterSetContainer* GetParamSetContainer(TInt aIndex);
+
+ const CParameterSetContainer* GetParamSetContainer(TInt aIndex) const
+ {
+ return const_cast<CParameterBundleBase*>(this)->GetParamSetContainer(aIndex);
+ }
+
+ IMPORT_C CParameterSetContainer* FindParamSetContainer(TUint32 aContainerId);
+ inline const CParameterSetContainer* FindParamSetContainer(TUint32 aContainerId) const
+ {
+ const CParameterSetContainer* r = const_cast<CParameterBundleBase*>(this)->FindParamSetContainer(aContainerId);
+ return r;
+ }
+
+ // deep search for parameter set in bundle
+ IMPORT_C XParameterSetBase* FindParameterSet(const Meta::STypeId& aTypeId);
+ inline const XParameterSetBase* FindParameterSet(const Meta::STypeId& aTypeId) const
+ {
+ const XParameterSetBase* r = const_cast<CParameterBundleBase*>(this)->FindParameterSet(aTypeId);
+ return r;
+ }
+
+ // finds aOld in array, deletes it and changes that pointer in array to be aNew instead.
+ // throws KErrArgument if aOld is not found
+ IMPORT_C void ReplaceParamSetContainerL(CParameterSetContainer* aOld, CParameterSetContainer* aNew);
+ IMPORT_C TInt ReplaceParamSetContainer(CParameterSetContainer* aOld, CParameterSetContainer* aNew);
+
+protected:
+ CParameterBundleBase()
+ {
+ }
+
+private:
+ CParameterBundleBase(const CParameterBundleBase& aBundle);
+ CParameterBundleBase& operator=(const CParameterBundleBase& aBundle);
+
+protected:
+ RPointerArray<CParameterSetContainer> iSetContainers;
+};
+
+
+template<class PARAMSETCONTAINERTYPE, class SUBCLASS, TInt UID, TInt TYPE>
+class MParameterSetTemplateMethods
+/**
+ * methods brought in as a template, to avoid having to rewrite
+ * identical-looking code in every derived type of XParameterSetBase
+*/
+ {
+public:
+ static inline SUBCLASS* NewL(PARAMSETCONTAINERTYPE& aContainer)
+ {
+ SUBCLASS* obj = NewL();
+ CleanupStack::PushL(obj);
+ aContainer.AddParameterSetL(obj);
+ CleanupStack::Pop(obj);
+ return obj;
+ }
+
+ static inline Meta::STypeId Type()
+ {
+ return Meta::STypeId::CreateSTypeId(UID,TYPE);
+ }
+
+ static inline SUBCLASS* NewL()
+ {
+ // As it's a plugin we must instantiate via the plugin interface!
+ // Directly calling the constructor would cause a link error as
+ // the vtable won't be visible by whoever uses this.
+ // So we need ECom to import it for us.
+ return static_cast<SUBCLASS*>(Meta::SMetaDataECom::NewInstanceL(Type()));
+ }
+
+ static inline SUBCLASS* FindInParamSetContainer(PARAMSETCONTAINERTYPE& aContainer)
+ {
+ return static_cast<SUBCLASS*>(aContainer.FindParameterSet(Type()));
+ }
+
+ static inline const SUBCLASS* FindInParamSetContainer(const PARAMSETCONTAINERTYPE& aContainer)
+ {
+ return static_cast<const SUBCLASS*>(aContainer.FindParameterSet(Type()));
+ }
+
+ static inline SUBCLASS* FindInBundle(CParameterBundleBase& aBundle)
+ {
+ return static_cast<SUBCLASS*>(aBundle.FindParameterSet(Type()));
+ }
+
+ static inline const SUBCLASS* FindInBundle(const CParameterBundleBase& aBundle)
+ {
+ return static_cast<const SUBCLASS*>(aBundle.FindParameterSet(Type()));
+ }
+ };
+
+
+template<class PARAMSETCONTAINERTYPE,class SUBCLASS>
+class CParameterBundle : public CParameterBundleBase
+/** Container for (bundle of) parameter set containers.
+
+This class can't be used directly, but must be subclassed, as the NewL/LoadL refer to
+the subclass.
+
+May contain and 0..N parameter families of type PARAMSETCONTAINERTYPE.
+*/
+{
+public:
+
+ static SUBCLASS* NewL()
+ /** Creates a new instance of a parameter bundle (heap object).
+
+ @return newly created instance of a parameter bundle
+ @exception leaves with KErrNoMemory in out of memory conditions
+ */
+ {
+ return new (ELeave) SUBCLASS();
+ }
+
+ static SUBCLASS* LoadL(TDesC8& aDes)
+ /** Creates a new parameter set bundle from a buffer containing the serialised object.
+
+ @param aDes Buffer containing the serialised object information
+ @return a pointer to a parameter bundle if successful, otherwise leaves with system error code.
+ */
+ {
+ SUBCLASS* obj = new (ELeave) SUBCLASS();
+ CleanupStack::PushL(obj);
+ User::LeaveIfError(obj->Load(aDes));
+ CleanupStack::Pop(obj);
+ return obj;
+ }
+
+ TInt Load(const TDesC8& aDes)
+ /** Instructs this sub-connection bundle to set its members based on the serialiesd data
+ in the buffer passed.
+
+ @param aDes Buffer containing the serialised bundle object
+ @return KErrNone if successful, otherwise system wide error
+ */
+ {
+ TPtrC8 buf(aDes);
+ while (buf.Length() > 0)
+ {
+ TRAPD(ret, PARAMSETCONTAINERTYPE::LoadL(*(static_cast<SUBCLASS*>(this)), buf));
+ if (ret != KErrNone)
+ {
+ iSetContainers.ResetAndDestroy();
+ return ret;
+ }
+ }
+ return KErrNone;
+ }
+
+ inline PARAMSETCONTAINERTYPE* GetParamSetContainer(TInt aIndex)
+ {
+ return static_cast<PARAMSETCONTAINERTYPE*>(CParameterBundleBase::GetParamSetContainer(aIndex));
+ }
+
+ inline const PARAMSETCONTAINERTYPE* GetParamSetContainer(TInt aIndex) const
+ {
+ return static_cast<const PARAMSETCONTAINERTYPE*>(CParameterBundleBase::GetParamSetContainer(aIndex));
+ }
+
+ inline PARAMSETCONTAINERTYPE* FindParamSetContainer(TUint32 aContainerId)
+ {
+ return static_cast<PARAMSETCONTAINERTYPE*>(CParameterBundleBase::FindParamSetContainer(aContainerId));
+ }
+
+protected:
+ CParameterBundle()
+ {
+ }
+};
+
+
+class CGenericParameterBundle : public CParameterBundle<CParameterSetContainer,CGenericParameterBundle>
+ {
+ };
+
+
+
+
+#endif
+// ES_PARAMETERBUNDLE_H
+
+