/*
* 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