diff -r 000000000000 -r 05e9090e2422 uiresources_plat/cdl_api/inc/CdlRefs.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiresources_plat/cdl_api/inc/CdlRefs.h Thu Dec 17 09:14:12 2009 +0200 @@ -0,0 +1,321 @@ +/* +* 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 +#include + +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 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& 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 + +#endif