/*

* 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);