diff -r 000000000000 -r 05e9090e2422 uiresources_plat/cdl_api/inc/CdlEngine.h --- /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 +#include +#include + +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 + { +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 + { +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