/*

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

#define CDLREFS_H

#include <e32base.h>

#include <CdlEngine.h>

class CCdlUids;

class CCdlRefs;

/**

* CCdlRefs is a collection of references to CDL interfaces.

* This class contains functions for manipulating such collections.

* It also is the basis for the customisation control system, so it

* has functions for maniplating customisation state.

*/

NONSHARABLE_CLASS(CCdlRefs) : public CCdlRefCollection

	{

private:

	typedef CArrayFixFlat<TCdlRef> CRefs;

public:

	/**

	* This is an iterator type for CCdlRefs.

	* There are three sub-types of iterator.

	* One type iterates all references in the collection. Another iterates

	* only those with a particular UID. A third iterates only those with a

	* particular file name.

	*/

	NONSHARABLE_CLASS(TIterator)

		{

	public:

		/**

		* Copy constructor

		*/

		IMPORT_C TIterator(const TIterator& aOther);

		/**

		* Assignment operator

		*/

		inline TIterator& operator=(const TIterator& aOther);

		/**

		* Equality operator

		*/

		inline TBool operator==(const TIterator& aOther) const;

		/**

		* Inequality operator

		*/

		inline TBool operator!=(const TIterator& aOther) const;

		/**

		* Dereference operator

		*/

		inline const TCdlRef& operator*() const;

		/**

		* Dereference and access operator

		*/

		inline const TCdlRef* operator->() const;

		/**

		* pre-increment operator

		* i.e. ++myIterator

		* this operator is preferred to the post-increment operator.

		*/

		IMPORT_C TIterator& operator++();

		/**

		* post-increment operator

		* i.e. myIterator++

		* the pre-increment operator is preferred to this operator.

		*/

		inline TIterator operator++(TInt);

	protected:

		TIterator(const CRefs& aRefs, TInt aIndex);

		virtual TBool Match(TInt aIndex) const;

	protected:

		friend class CCdlRefs;

		const CRefs& iRefs;

		TInt iIndex;

		};

public:

	/**

    * Two-phased constructor.

	*/

	IMPORT_C static CCdlRefs* NewL();

	/**

    * Two-phased constructor.

	*/

	IMPORT_C static CCdlRefs* NewLC();

    /**

    * Destructor.

    */

	IMPORT_C ~CCdlRefs();

	// Iterators

	/**

	* Create an iterator that will iterate through all references in the collection

	*/

	IMPORT_C TIterator Begin() const;

	/**

	* Create an iterator that will iterate through only those references with

	* a particular UID.

	* @param aUid the UID to match.

	*/

	IMPORT_C TIterator Begin(TUid aUid) const;

	/**

	* Create an iterator that will iterate through only those references with

	* a particular file name.

	* @param aName the name to match.

	*/

	IMPORT_C TIterator Begin(const TDesC& aName) const;

	/**

	* Create an iterator representing the first postition after the end of

	* the collection. This iterator must not be dereferenced, but other

	* iterators can be compared with this one. They will be equal when the

	* other iterator gone past the last valid reference.

	*/

	IMPORT_C TIterator End() const;

	// Modifiers

	/**

	* Append a single reference to this collection

	* @param aRef the reference to append.

	*/

	IMPORT_C void AppendL(const TCdlRef& aRef);

	/**

	* Append a collection of references to this collection

	* @param aRefs the collection of references to append.

	*/

	IMPORT_C void AppendL(const CCdlRefCollection& aRefs);

	/**

	* Append a collection of references to this collection

	* @param aHomeName the DLL name that this collection of refs was found in.

	* @param aRefs the collection of references to append.

	*/

	IMPORT_C void AppendL(const TDesC& aHomeName, const TCdlArray<TCdlRef>& aRefs);

	/**

	* Insert a reference at the specified iterator position.

	* @param aAt an iterator giving the position at which to insert the reference

	* InsertL(End(), aRef) is equivalent to Append(aRef)

	* @param aRef the reference to insert.

	*/

	IMPORT_C void InsertL(const TIterator& aAt, const TCdlRef& aRef);

	/**

	* Delete the reference indicated by the iterator.

	* @param aAt the position to delete, Delete(Begin()) deletes the first

	* element in the collection.

	*/

	IMPORT_C void Delete(TIterator& aAt);

	/**

	* Delete the references from aBegin up to, but not including aEnd.

	* @param aBegin the first position to delete

	* @param aEnd the stop position for the iterator

	*/

	IMPORT_C void Delete(const TIterator& aBegin, const TIterator& aEnd);

	/**

	* Delete a name and all references that use it from the collection.

	* @param aName the name to delete.

	*/

	IMPORT_C void Delete(const TDesC& aName);

	// Accessors & subsets

	/*

	* Return a collection of all the file names used by the references in

	* this collection.

	* @return a reference to a collection of names

	*/

	IMPORT_C const CCdlNames& Names() const;

	/*

	* Create an array of UIDs containing all of the UIDs used in this collection.

	* @return a new array of UIDs

	*/

	IMPORT_C CCdlUids* UidsLC() const;

	/*

	* Create a subset collection that only contains references for a particular UID.

	* @return a new collection

	*/

	IMPORT_C CCdlRefs* SubsetByUidLC(TUid aUid) const;

	/*

	* Create a subset collection that only contains references for a 

	* set of UIDs.

	* @return a new collection

	*/

	IMPORT_C CCdlRefs* SubsetByUidsLC(const CCdlUids& aUids) const;

	/*

	* Create a subset collection that only contains references with a

	* particular file name.

	* @return a new collection

	*/

	IMPORT_C CCdlRefs* SubsetByNameLC(const TDesC& aName) const;

	// Customisation operations

	/**

	* This function replaces references in this collection for any CDL interface UIDs that appear

	* in the new collection with those from the new collection. All other

	* references are appended.

	* The effect of this function is useful for customisation state management.

	* The current customisation state is defined by a CCdlRefs object, where for

	* each CDL interface UID that appears in the collection, the references using that

	* UID identify the layers of customisation instances that customise the interface.

	* The earlier references in the collection for the sub-layers for the later one.

	* @param aRefs the new customisation state which will replace and be merged

	* with the current state.

	*/

	IMPORT_C void MergeAndReplaceL(const CCdlRefs& aRefs);

	/**

	* This function adds references to the collection for use as new layers of customisation.

	* The effect of this function is useful for customisation state management.

	* The current customisation state is defined by a CCdlRefs object, where for

	* each CDL interface UID that appears in the collection, the references using that

	* UID identify the layers of customisation instances that customise the interface.

	* The earlier references in the collection for the sub-layers for the later one.

	* @param aRefs the new layers of customisation state that will modify the

	* current customisation.

	*/

	IMPORT_C void AddLayerL(const CCdlRefs& aRefs);

	// import/export

	/**

	* Create a descriptor containing the contents of this collection.

	* This is useful for externalising customisation state.

	* @return a new descriptor describing this collection.

	*/

	IMPORT_C HBufC8* ExportL() const;

	/**

	* Create a descriptor containing the contents of this collection.

	* This is useful for externalising customisation state.

	* @return a new descriptor describing this collection.

	*/

	IMPORT_C HBufC8* ExportLC() const;

	/**

	* Populate this collection from a descriptor containing a collection

	* that was externalised by one of the ExportL functions.

	* @param a descriptor containing an externalised representation of a

	* CCdlRefs object.

	*/

	IMPORT_C void ImportL(const TDesC8& aData);

	// CCdlRefCollection interface

	/**

	* @return the number of references in this collection

	*/

	IMPORT_C TInt CountRefs() const;

	/**

	* Access a reference at a particular index in this collection.

	* @param aIndex the postion to access.

	* @return the reference at that position.

	*/

	IMPORT_C TCdlRef Ref(TInt aIndex) const;

private:

	CCdlRefs();

private:

	NONSHARABLE_CLASS(TInterfaceIterator) : public TIterator

		{

	public:

		TInterfaceIterator(const CRefs& aRefs, TInt aIndex);

	private:

		virtual TBool Match(TInt aIndex) const;

		};

	NONSHARABLE_CLASS(TNameIterator) : public TIterator

		{

	public:

		TNameIterator(const CRefs& aRefs, TInt aIndex);

	private:

		virtual TBool Match(TInt aIndex) const;

		};

private:

	CRefs iRefs;

	CCdlNames iNames;

	};

#include <CdlRefs.inl>

#endif