/*
* 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:
*
*/
#ifndef CDLPACKAGEEXPLORER_H
#define CDLPACKAGEEXPLORER_H

#include <CdlEngine.h>

class CCdlRefs;

/**
* Enumeration used to indicate the result of comparing two customisation instances
*/
enum TCdlInstanceComparison
	{
	ECdlInstancesNotComparable,
	EFirstCdlInstanceBetter,
	ESecondCdlInstanceBetter
	};


/**
* Utilities for the CDL explorer system
*/
class CdlExplorerUtils
	{
public:
	/**
	* Create a CCdlRefs containing a single reference to the instance passed in.
	* @param aSingleInstance an instance whose reference will appear in the collection.
	* @return a CCdlRefs containing a single reference to the instance passed in.
	*/
	IMPORT_C static CCdlRefs* CreateRefsLC(const CCdlInstance& aSingleInstance);
	/**
	* Create a CCdlRefs containing a collection of references which have come from a
	* customisation instance. If any of the references do not give a DLL name, they take
	* their DLL name from the instance provided.
	* @param aHomeInstance a customisation instance which has provided the array of references
	* @param aRefs a collection of references.
	* @return a CCdlRefs containing the references supplied.
	*/
	IMPORT_C static CCdlRefs* CreateRefsLC(const CCdlInstance& aHomeInstance, const TCdlArray<TCdlRef>& aRefs);
	};


/**
* Base class for CDL explorer classes. Has functionality for finding instances.
*/
class CCdlInstanceExplorerBase : public CBase
	{
public:
	/**
	* destructor
	*/
	IMPORT_C ~CCdlInstanceExplorerBase();

protected:
	/**
	* Finds customisation instances that implement a particular interface. The returned set is
	* filtered so that invalid and less good instances are removed.
	* @param aCdlUid the CDL interfaces UID to look for.
	* @return An array of instances that implement the specified interface.
	*/
	IMPORT_C CArrayPtr<CCdlInstance>* FindLC(TUid aCdlUid);

private:
	void TryAddL(const TCdlRef& aRef, const CCdlInstance* aSubLayer, CArrayPtr<CCdlInstance>* aInstances);

private:
	virtual CCdlInstance* CreateInstanceLC(const TCdlRef& aRef, const CCdlInstance* aSubLayer) = 0;
	virtual TCdlInstanceComparison CallCompare(const CCdlInstance& aFirst, const CCdlInstance& aSecond) const = 0;
	virtual TBool CallIsValid(const CCdlInstance& aInstance) const = 0;

private:
	CCdlInstance* iSubLayer;		// owned, used as a sub-layer for all returned instances
	};


/**
* Template class for creating explorers for specific CDL interfaces.
* The template parameter must be the CInstance class from a particular CDL interfaces namespace.
* This class uses inline virtual functions, which could result in a lot of code duplication
* if instantiated in a public header. Therefore, this class should only ever be derived from and
* instantiated inside a .cpp file where it is needed.
*/
template<class T>
class CCdlInstanceExplorer : public CCdlInstanceExplorerBase
	{
public:
	/**
	* Finds customisation instances of the type that this class is instantiated with.
	* The returned set is filtered so that invalid and less good instances are removed.
	* @return An array of instances of the type that this class is instantiated with.
	*/
	inline CArrayPtr<T>* FindLC();

private:
	inline CCdlInstance* CreateInstanceLC(const TCdlRef& aRef, const CCdlInstance* aSubLayer);
	inline TCdlInstanceComparison CallCompare(const CCdlInstance& aFirst, const CCdlInstance& aSecond) const;
	inline TBool CallIsValid(const CCdlInstance& aPackage) const;

protected:	// These functions can be overridden to specialise explorer behavior
	/**
	* Virtual function for comparing two instances.
	* Instances are comparable if they are alternative versions of the same implementation.
	* Eg for different languages.
	* If the instances are not related, they are not comparable.
	* Compare should favor aFirst in case of a tie.
	* @param aFirst The first instance to compare.
	* @param aFirst The second instance to compare.
	* @return The result of the comparison
	*/
	inline virtual TCdlInstanceComparison Compare(const T& aFirst, const T& aSecond) const;
	/**
	* Virtual function for checking the validity of an instance.
	* Instantiations of the instance explorer may want to overide this to check that 
	* instances meet certain requirements.
	* @param aInstance The instance to check validity on
	* @return ETrue if valid
	*/
	inline virtual TBool IsValid(const T& aInstance) const;
	};


/**
*  Explorer class with added functionality for packages.
*/
template<class T>
class CCdlPackageExplorer : public CCdlInstanceExplorer<T>
	{
public:
	/**
	* Extracts the contents of a package into a CCdlRefs collection
	* @param aPackage the package whose contents require extraction
	* @return a CCdlRefs containing the contents of the package.
	*/
	inline CCdlRefs* CreateRefsLC(const T& aPackage);
	};


#include <CdlExplorer.inl>

#endif