--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/uiresources_plat/cdl_api/inc/CdlEngine.h Thu Dec 17 09:14:12 2009 +0200
@@ -0,0 +1,547 @@
+/*
+* Copyright (c) 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:
+*
+*/
+#if !defined(CDLENGINE_H)
+#define CDLENGINE_H
+
+#include <e32base.h>
+#include <CdlEngDef.h>
+#include <badesca.h>
+
+class CCdlEngine;
+class CCdlEngineBase;
+class CCdlRefs;
+
+typedef void (TCdlEngineFunc)();
+
+
+/**
+* This class is the base for all classes which need to maintain a reference to the
+* CDL engine or an object it owns.
+*
+* When created, this object adds a reference to the CDL engine.
+* When deleted, this object removes any remaining reference to the CDL engine.
+* References may added or removed during the object's lifetime, but there must be 0 or 1
+* reference when this object is deleted.
+*
+* This class is not instantiable or derivable outside of the CDL engine.
+*/
+NONSHARABLE_CLASS(CCdlEngineRef) : public CBase
+ {
+public:
+ CCdlEngineRef(CCdlEngineBase* aEngine);
+ IMPORT_C ~CCdlEngineRef();
+
+ void AddRef();
+ void ReleaseRef();
+
+ CCdlEngineBase* Engine() const;
+
+private:
+ TInt iRefCount;
+ CCdlEngineBase* iEngine; // ownership is shared among all instances
+ };
+
+
+/**
+* This is the abstract base class for all collections of TCdlRef objects.
+*/
+class CCdlRefCollection : public CBase
+ {
+public:
+ virtual TInt CountRefs() const = 0;
+ virtual TCdlRef Ref(TInt aIndex) const = 0;
+ };
+
+
+/**
+* The abstract base class for all customisation instance objects.
+* Only the CDL engine can create objects derived from this class.
+*/
+NONSHARABLE_CLASS(CCdlInstance) : public CCdlEngineRef
+ {
+public: // General public API
+
+ /**
+ * Gets the CDL instance reference for this instance
+ * @return the CDL reference for this instance
+ */
+ IMPORT_C const TCdlRef& Ref() const;
+
+ /**
+ * Gets the instance that forms the sub-layer for this instance. Any API not implemented
+ * by this instance will be implemented in a sub-layer.
+ * @return the sub-layer for this instance, may be NULL.
+ */
+ IMPORT_C const CCdlInstance* SubLayer() const;
+
+ /**
+ * The CDL instance reference for the instance that actually implemented the last
+ * accessed API. If this instance implemented the API, then this instance's reference
+ * will be returned. Otherwise it will be the reference of one of this instance's
+ * sub-layers.
+ * @return the CDL reference of the instance that implemented the last accessed API.
+ */
+ IMPORT_C const TCdlRef& LastAccessedRef() const;
+
+ /**
+ * Adjusts a filename to be relative to the file containing the CDL instance that
+ * implemented the last accessed API. The filename will be made relative to this instances
+ * file, or the file of one of this instances sub-layers.
+ * @param aFileName the filename to be adjusted.
+ */
+ IMPORT_C void FileNameRelativeToLastAccessedInstance(TFileName& aFileName) const;
+
+ /**
+ * Test whether this instance is the same as another.
+ * @param aOther the instance you want to compare with this one.
+ * @return true if they are the same instance.
+ */
+ IMPORT_C TBool operator==(const CCdlInstance& aOther) const;
+
+ /**
+ * Does this instance implement all of it's API? Instances that don't implement their
+ * entire API need a sub-layer that does implement the entire API.
+ * @return true if the entire API is implemented
+ */
+ virtual TBool IsComplete() const = 0;
+
+public: // API used by CDL compiler generated header files
+ IMPORT_C static CCdlInstance* NewL( const TCdlRef& aRef,
+ const SCdlInterface* aInterfaceParams,
+ const CCdlInstance* aSubLayer = NULL,
+ CCdlEngine* aEngine = NULL,
+ TInt* aLastApi = NULL);
+ IMPORT_C static CCdlInstance* NewLC(const TCdlRef& aRef,
+ const SCdlInterface* aInterfaceParams,
+ const CCdlInstance* aSubLayer = NULL,
+ CCdlEngine* aEngine = NULL,
+ TInt* aLastApi = NULL);
+ IMPORT_C TAny* GetData(TInt aCdlApiId) const;
+ IMPORT_C TCdlEngineFunc* GetFunction(TInt aCdlApiId) const;
+
+public: // CDL System API
+ const CCdlInstance* Implementor(TInt aCdlApiId) const;
+ virtual TAny* Implementation(TInt aCdlApiId) const = 0;
+ virtual const SCdlInterface& Interface() const = 0;
+ virtual TAny* Extension(TInt aId) const;
+
+protected:
+ CCdlInstance(CCdlEngine* aEngine, TInt* aLastApi);
+
+protected:
+ friend class CdlEngine; // for optimised GetFunction()
+ TCdlRef iRef;
+ const CCdlInstance* iSubLayer; // not owned
+ TInt& iLastApi;
+ };
+
+
+/**
+* A collection of UIDs.
+* Used within the CDL engine to represent collections of CDL interface UIDs.
+*/
+class CCdlUids : public CArrayFixFlat<TUid>
+ {
+public:
+ /**
+ * Two-phased constructor.
+ */
+ IMPORT_C static CCdlUids* NewLC();
+
+ /**
+ * C++ default constructor.
+ */
+ IMPORT_C CCdlUids();
+
+ /**
+ * Adds a UID to the collection, if it is not already present
+ * @param aUid the UID to add
+ */
+ IMPORT_C void AddL(TUid aUid);
+
+ /**
+ * Removes a UID from the collection
+ * @param aUid the UID to remove
+ */
+ IMPORT_C void Remove(TUid aUid);
+
+ /**
+ * Adds a collection of UIDs to this collection. UIDs are only added if they are not
+ * already present.
+ * @param aArray the collection of UIDs to add
+ */
+ IMPORT_C void AddL(const CCdlUids& aArray);
+
+ /**
+ * Removes a collection of UIDs from this collection
+ * @param aParam the collection of UIDs to remove
+ */
+ IMPORT_C void Remove(const CCdlUids& aArray);
+
+ /**
+ * Finds the array index of a UID in this collection
+ * @param aUid the UID to search for
+ * @return The index of the UID if found. KErrNotFound otherwise.
+ */
+ IMPORT_C TInt FindIndex(TUid aUid) const;
+
+ /**
+ * Creates a new collection containing the UIDs which are common to this and the passed
+ * in collection.
+ * @param aArray the other collection
+ * @return a new collection of UID containing the intersection of the two inputs.
+ */
+ IMPORT_C CCdlUids* IntersectionLC(const CCdlUids& aArray) const;
+
+ /**
+ * Populates a UID collection from a descriptor containing an exported UID collection.
+ * @param aDes a descriptor containing a UID collection created by the Export() function.
+ */
+ IMPORT_C void ImportL(const TDesC8& aDes);
+
+ /**
+ * Creates a descriptor containing the exported UID collection. Used for externalising
+ * UID collections and transmitting them across processes.
+ * @return a descriptor containing the exported contents of this collection.
+ */
+ IMPORT_C TPtrC8 Export() const;
+ };
+
+
+/**
+* A collection of names stored as HBufC*.
+* This collection contains one instance of each name. CdlEngine::CompareNames() is used
+* to check whether two names are the same.
+* This collection type is used as a string pool for the CCdlRefs class, where there are
+* many TCdlRefs that share the same name.
+* This class is used instead of CDesCArray because the descriptors returned by CDesCArray
+* are not referenceable.
+* The HBufCs in the array are owned by this class.
+*/
+class CCdlNames : public CArrayPtrFlat<HBufC>
+ {
+public:
+
+ /**
+ * Two-phased constructor.
+ */
+ IMPORT_C static CCdlNames* NewLC();
+
+ /**
+ * C++ default constructor.
+ */
+ IMPORT_C CCdlNames();
+
+ /**
+ * Destructor.
+ */
+ IMPORT_C ~CCdlNames();
+
+ /**
+ * Finds the array index of a name in this collection.
+ * @param aName the name to look for.
+ * @return the array index of the name, if found. KErrNotFound otherwise.
+ */
+ IMPORT_C TInt FindIndex(const TDesC& aName) const;
+
+ /**
+ * Adds a name to the collection. If the name is already present in the collection is
+ * not added again. In any case, the names HBufC* in the collection is returned.
+ * @param aName the name to add to the collection.
+ * @return The HBufC* in the collection that contains the name.
+ */
+ IMPORT_C HBufC* AddL(const TDesC& aName);
+
+ /**
+ * Populates the collection from a descriptor containing an exported collection of names.
+ * @param aDes a descriptor containing a collection of names, which has been exported
+ * by ExportL or ExportLC.
+ */
+ IMPORT_C void ImportL(const TDesC8& aDes);
+
+ /**
+ * Creates a descriptor containing the exported collection of names
+ * @return a new HBufC
+ */
+ IMPORT_C HBufC8* ExportL() const;
+
+ /**
+ * Creates a descriptor containing the exported collection of names
+ * @return a new HBufC on the cleanup stack
+ */
+ IMPORT_C HBufC8* ExportLC() const;
+
+private:
+ static void CleanupImport(TAny* aThis);
+ void DoCleanupImport();
+ };
+
+
+/**
+* Mixin class for observing changes in the CDL customisation world.
+* This class has concrete implementations of all its virtual functions. These are NULL
+* implementations, except for the destructor which deregisters the observer.
+*/
+class MCdlChangeObserver
+ {
+public:
+
+ /**
+ * a virtual destructor that de-registers this observer with the CDL engine
+ */
+ IMPORT_C virtual ~MCdlChangeObserver();
+
+ /**
+ * This event handler function is called when the current customisation of one or more
+ * interfaces has changed.
+ * @param aUids the collection of interface UIDs which have changed
+ */
+ IMPORT_C virtual void HandleCustomisationChangeL(const CCdlUids& aUids);
+
+ /**
+ * This event handler function is called when the set of available customisations changes
+ */
+ IMPORT_C virtual void HandleAvailableRefsChangeL();
+ };
+
+
+/**
+* CdlEngine is a static fascade interface to the singleton CDL engine object.
+* There is at most one CDL engine per thread. This static interface ensures that this
+* fact can not be changed.
+*/
+class CdlEngine
+ {
+public:
+ // General public API
+ /**
+ * Tests for the existence of the CDL engine.
+ * Useful for cases where the client code can work without the CDL engine,
+ * and does not want to create and hold a CCdlEngineRef to ensure the existence
+ * of the CDL engine.
+ * @return ETrue if the CDL engine exists, EFalse otherwise.
+ */
+ IMPORT_C static TBool IsCdlEngineCreated();
+
+ /**
+ * Creates a reference to the CDL engine singleton, and creates the CDL engine if it
+ * does not already exist. If your client code is unsure if the CDL exists in this thread,
+ * it should use this function to ensure that it does.
+ * @return a reference to the CDL engine. The CDL engine is guaranteed to exist as long
+ * as this reference does.
+ */
+ IMPORT_C static CCdlEngineRef* CreateCdlEngineL();
+
+ /**
+ * Starts the global customisation of CDL interfaces that are configured for global
+ * customisation.
+ * CDL interfaces can be customised either locally or globally. Local customisation
+ * means that changes to the customisation only affect the local thread. Global customisation
+ * means that customisation settings are stored in the CDL server and affect all threads.
+ * that subscribe to customisation of that interface.
+ */
+ IMPORT_C static void StartGlobalCustomisationL();
+
+ // API used by CDL compiler generated header files
+ IMPORT_C static TAny* GetData(TUid aCdlUid, TInt aApiId);
+ IMPORT_C static TCdlEngineFunc* GetFunction(TUid aCdlUid, TInt aApiId);
+ IMPORT_C static const CCdlInstance* Implementor(TUid aCdlUid, TInt aApiId);
+
+ /**
+ * Is customisation for this CDL interface loaded?
+ *
+ * This function is normally used through a CDL compiler generated header
+ * specific to a particular CDL interface.
+ * @param aInterfaceParams the interface in question
+ * @return ETrue if the interface is available and a customisation is loaded.
+ */
+ IMPORT_C static TBool IsCustomisationStarted(const SCdlInterface* aInterfaceParams);
+
+ /**
+ * Set a requirement for customisations of this interface that they have
+ * to implement at least the version of the interface that the client specifies.
+ * If customisations are already loaded that do not satisfy this interface,
+ * this function will leave with KErrNotSupported.
+ *
+ * This function is normally used through a CDL compiler generated header
+ * specific to a particular CDL interface.
+ * @param aInterfaceParams the interface in question
+ */
+ IMPORT_C static void RequireCustomisationL(const SCdlInterface* aInterfaceParams);
+
+ /**
+ * Load a customisation from this reference.
+ * If no customisation has already been loaded for this interface, this
+ * customisation instance must meet any requirements already specified by
+ * the clients of the interface.
+ *
+ * This function is normally used through a CDL compiler generated header
+ * specific to a particular CDL interface.
+ * @param aRef a CDL instance reference defining the customisation.
+ */
+ IMPORT_C static void LoadCustomisationL(const TCdlRef& aRef);
+
+ /**
+ * Get a CDL instance that represents the current customisation.
+ * This instance will automatically be updated to reflect changes in
+ * customisation.
+ *
+ * This function is normally used through a CDL compiler generated header
+ * specific to a particular CDL interface.
+ * @param aCdlUid the UID of the CDL interface that you want customisation for
+ * @return a reference to a customisation instance
+ */
+ IMPORT_C static const CCdlInstance& CustomisationInstance(TUid aCdlUid);
+
+ /**
+ * Sets a customisation change observer object for a particular interface.
+ * Using this function, client code can be informed when the current
+ * customisation for a particular interface changes.
+ * A single observer can observe changes in many interfaces.
+ *
+ * This function is normally used through a CDL compiler generated header
+ * specific to a particular CDL interface.
+ * @param aObserver a pointer to an object implementing the MCdlChangeObserver interface.
+ * @param aCdlUid the UID of the CDL interface that you want to observe.
+ */
+ IMPORT_C static void SetCustomisationChangeObserverL(MCdlChangeObserver* aObserver, TUid aCdlUid);
+
+ /**
+ * Get a reference for the last customisation instance which was accessed
+ * to implement a particular interface.
+ *
+ * This function is normally used through a CDL compiler generated header
+ * specific to a particular CDL interface.
+ * @param aCdlUid the UID of the CDL interface
+ * @return a reference for the instance that was last accessed to implement
+ * the asked for interface.
+ */
+ IMPORT_C static const TCdlRef& LastAccessedRef(TUid aCdlUid);
+
+ /**
+ * Modify a filename to be relative to the file containing the customisation
+ * instance that was last accessed to implement a particular CDL interface.
+ * For instance, if an interface was accessed to get a bitmap file name, a
+ * full path for that bitmap file can be generated by using this function
+ * immediately afterwards.
+ *
+ * This function is normally used through a CDL compiler generated header
+ * specific to a particular CDL interface.
+ * @param aCdlUid the UID of the CDL interface
+ * @param aFileName the filename to be modified
+ */
+ IMPORT_C static void FileNameRelativeToLastAccessedInstance(TUid aCdlUid, TFileName& aFileName);
+
+ /**
+ * Get the latest API id accessed by a CDL client. If used from inside a customisation
+ * instance, this will be the API id of the current implementation.
+ *
+ * @return the latest API id that was accessed by a CDL client.
+ */
+ IMPORT_C static TInt LastApiId();
+
+ // API for controlling customisation settings
+
+ /**
+ * Create a collection of CDL references that implement a particular interface.
+ * @param aCdlUid the UID of the interface in question
+ * @return a new collection of the CDL instance references that implement that interface.
+ */
+ IMPORT_C static CCdlRefs* FindInstancesLC(TUid aCdlUid);
+
+ /**
+ * Create a collection of references for the CDL instancesthat are implemented
+ * in a named file.
+ * @param aFileName the name of the file that contains CDL instances
+ * @return a new collection of CDL instance references.
+ */
+ IMPORT_C static CCdlRefCollection* FileContentsLC(const TDesC& aFileName);
+
+ /**
+ * Create a collection of file names of files that contain CDL customisation instances.
+ * @return a new collection of file names.
+ */
+ IMPORT_C static CCdlNames* FindCustomisationFilesLC();
+
+ /**
+ * Create a collection of references to all known CDL customisation instances.
+ * @return a collection of references to all known instances.
+ */
+ IMPORT_C static CCdlRefs* AllAvailableRefsLC();
+
+ /**
+ * Set an observer for changes in the set of available customisations.
+ * @param aObserver a implementor of the MCdlChangeObserver interface that is interested
+ * in knowing about changes to the set of all available references.
+ */
+ IMPORT_C static void SetAvailableRefsChangeObserverL(MCdlChangeObserver* aObserver);
+
+ /**
+ * Sets the current local customisation as described by a collection of CDL instance references.
+ * For each reference, the instance referenced will be used to customise it's interface.
+ * If more than one instance in the collection customise the same interface, the earlier
+ * reference in the collection will be a sub-layer for the later one.
+ * This only affects customisation in this thread.
+ * @param aState the collection of CDL instance references that will be used for customisation.
+ */
+ IMPORT_C static void SetLocalStateL(const CCdlRefs& aState);
+
+ /**
+ * Sets the global customisation as described by a collection of CDL instance references.
+ * For each reference, the instance referenced will be used to customise it's interface.
+ * If more than one instance in the collection customise the same interface, the earlier
+ * reference in the collection will be a sub-layer for the later one.
+ * This sets the global customisation. It will only affect the local customisation state
+ * if global customisation of the relevant interfaces is enabled in this thread.
+ * @param aState the collection of CDL instance references that will be used for customisation.
+ */
+ IMPORT_C static void SetGlobalStateL(const CCdlRefs& aState);
+
+ /**
+ * Creates a collection of CDL instance references that describe the local customisation
+ * of a set of interfaces.
+ * @param aCdlUids the set of interface UIDs of interest.
+ * @return a collection of references that describe the customisation state.
+ */
+ IMPORT_C static CCdlRefs* LocalStateLC(const CCdlUids& aCdlUids);
+
+ /**
+ * Creates a collection of CDL instance references that describe the global customisation
+ * of a set of interfaces.
+ * @param aCdlUids the set of interface UIDs of interest.
+ * @return a collection of references that describe the customisation state.
+ */
+ IMPORT_C static CCdlRefs* GlobalStateLC(const CCdlUids& aCdlUids);
+
+ /**
+ * Enable or disable global customisation for a collection of interfaces.
+ * @param aCdlUids the interface UIDs for which global customisation is to be enabled or disabled
+ * @param aEnabled are they to be enabled or disabled?
+ */
+ IMPORT_C static void EnableGlobalCustomisationL(const CCdlUids& aCdlUids, TBool aEnabled);
+
+ /**
+ * Compares two names.
+ * @param aLeft a name to compare.
+ * @param aRight a name to compare.
+ * @return as for TDesC::CompareF: 0 if the names are the same. Non-zero otherwise.
+ */
+ IMPORT_C static TInt CompareNames(const TDesC& aLeft, const TDesC& aRight);
+ };
+
+
+#endif