1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 #ifndef CDLREFS_H

    18 #define CDLREFS_H

    19 

    20 #include <e32base.h>

    21 #include <CdlEngine.h>

    22 

    23 class CCdlUids;

    24 class CCdlRefs;

    25 

    26 /**

    27 * CCdlRefs is a collection of references to CDL interfaces.

    28 * This class contains functions for manipulating such collections.

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

    30 * has functions for maniplating customisation state.

    31 */

    32 NONSHARABLE_CLASS(CCdlRefs) : public CCdlRefCollection

    33 	{

    34 private:

    35 	typedef CArrayFixFlat<TCdlRef> CRefs;

    36 

    37 public:

    38 	/**

    39 	* This is an iterator type for CCdlRefs.

    40 	* There are three sub-types of iterator.

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

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

    43 	* particular file name.

    44 	*/

    45 	NONSHARABLE_CLASS(TIterator)

    46 		{

    47 	public:

    48 		/**

    49 		* Copy constructor

    50 		*/

    51 		IMPORT_C TIterator(const TIterator& aOther);

    52 

    53 		/**

    54 		* Assignment operator

    55 		*/

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

    57 

    58 		/**

    59 		* Equality operator

    60 		*/

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

    62 

    63 		/**

    64 		* Inequality operator

    65 		*/

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

    67 

    68 		/**

    69 		* Dereference operator

    70 		*/

    71 		inline const TCdlRef& operator*() const;

    72 

    73 		/**

    74 		* Dereference and access operator

    75 		*/

    76 		inline const TCdlRef* operator->() const;

    77 

    78 		/**

    79 		* pre-increment operator

    80 		* i.e. ++myIterator

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

    82 		*/

    83 		IMPORT_C TIterator& operator++();

    84 

    85 		/**

    86 		* post-increment operator

    87 		* i.e. myIterator++

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

    89 		*/

    90 		inline TIterator operator++(TInt);

    91 

    92 	protected:

    93 		TIterator(const CRefs& aRefs, TInt aIndex);

    94 		virtual TBool Match(TInt aIndex) const;

    95 

    96 	protected:

    97 		friend class CCdlRefs;

    98 		const CRefs& iRefs;

    99 		TInt iIndex;

   100 		};

   101 

   102 public:

   103 	/**

   104     * Two-phased constructor.

   105 	*/

   106 	IMPORT_C static CCdlRefs* NewL();

   107 

   108 	/**

   109     * Two-phased constructor.

   110 	*/

   111 	IMPORT_C static CCdlRefs* NewLC();

   112 

   113     /**

   114     * Destructor.

   115     */

   116 	IMPORT_C ~CCdlRefs();

   117 

   118 	// Iterators

   119 	/**

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

   121 	*/

   122 	IMPORT_C TIterator Begin() const;

   123 

   124 	/**

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

   126 	* a particular UID.

   127 	* @param aUid the UID to match.

   128 	*/

   129 	IMPORT_C TIterator Begin(TUid aUid) const;

   130 

   131 	/**

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

   133 	* a particular file name.

   134 	* @param aName the name to match.

   135 	*/

   136 	IMPORT_C TIterator Begin(const TDesC& aName) const;

   137 

   138 	/**

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

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

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

   142 	* other iterator gone past the last valid reference.

   143 	*/

   144 	IMPORT_C TIterator End() const;

   145 

   146 	// Modifiers

   147 	/**

   148 	* Append a single reference to this collection

   149 	* @param aRef the reference to append.

   150 	*/

   151 	IMPORT_C void AppendL(const TCdlRef& aRef);

   152 

   153 	/**

   154 	* Append a collection of references to this collection

   155 	* @param aRefs the collection of references to append.

   156 	*/

   157 	IMPORT_C void AppendL(const CCdlRefCollection& aRefs);

   158 

   159 	/**

   160 	* Append a collection of references to this collection

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

   162 	* @param aRefs the collection of references to append.

   163 	*/

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

   165 

   166 	/**

   167 	* Insert a reference at the specified iterator position.

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

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

   170 	* @param aRef the reference to insert.

   171 	*/

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

   173 

   174 	/**

   175 	* Delete the reference indicated by the iterator.

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

   177 	* element in the collection.

   178 	*/

   179 	IMPORT_C void Delete(TIterator& aAt);

   180 

   181 	/**

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

   183 	* @param aBegin the first position to delete

   184 	* @param aEnd the stop position for the iterator

   185 	*/

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

   187 

   188 	/**

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

   190 	* @param aName the name to delete.

   191 	*/

   192 	IMPORT_C void Delete(const TDesC& aName);

   193 

   194 	// Accessors & subsets

   195 

   196 	/*

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

   198 	* this collection.

   199 	* @return a reference to a collection of names

   200 	*/

   201 	IMPORT_C const CCdlNames& Names() const;

   202 

   203 	/*

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

   205 	* @return a new array of UIDs

   206 	*/

   207 	IMPORT_C CCdlUids* UidsLC() const;

   208 

   209 	/*

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

   211 	* @return a new collection

   212 	*/

   213 	IMPORT_C CCdlRefs* SubsetByUidLC(TUid aUid) const;

   214 

   215 	/*

   216 	* Create a subset collection that only contains references for a 

   217 	* set of UIDs.

   218 	* @return a new collection

   219 	*/

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

   221 

   222 	/*

   223 	* Create a subset collection that only contains references with a

   224 	* particular file name.

   225 	* @return a new collection

   226 	*/

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

   228 

   229 	// Customisation operations

   230 	/**

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

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

   233 	* references are appended.

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

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

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

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

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

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

   240 	* with the current state.

   241 	*/

   242 	IMPORT_C void MergeAndReplaceL(const CCdlRefs& aRefs);

   243 

   244 	/**

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

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

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

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

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

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

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

   252 	* current customisation.

   253 	*/

   254 	IMPORT_C void AddLayerL(const CCdlRefs& aRefs);

   255 

   256 	// import/export

   257 

   258 	/**

   259 	* Create a descriptor containing the contents of this collection.

   260 	* This is useful for externalising customisation state.

   261 	* @return a new descriptor describing this collection.

   262 	*/

   263 	IMPORT_C HBufC8* ExportL() const;

   264 

   265 	/**

   266 	* Create a descriptor containing the contents of this collection.

   267 	* This is useful for externalising customisation state.

   268 	* @return a new descriptor describing this collection.

   269 	*/

   270 	IMPORT_C HBufC8* ExportLC() const;

   271 

   272 	/**

   273 	* Populate this collection from a descriptor containing a collection

   274 	* that was externalised by one of the ExportL functions.

   275 	* @param a descriptor containing an externalised representation of a

   276 	* CCdlRefs object.

   277 	*/

   278 	IMPORT_C void ImportL(const TDesC8& aData);

   279 

   280 	// CCdlRefCollection interface

   281 	/**

   282 	* @return the number of references in this collection

   283 	*/

   284 	IMPORT_C TInt CountRefs() const;

   285 

   286 	/**

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

   288 	* @param aIndex the postion to access.

   289 	* @return the reference at that position.

   290 	*/

   291 	IMPORT_C TCdlRef Ref(TInt aIndex) const;

   292 

   293 private:

   294 	CCdlRefs();

   295 

   296 private:

   297 	NONSHARABLE_CLASS(TInterfaceIterator) : public TIterator

   298 		{

   299 	public:

   300 		TInterfaceIterator(const CRefs& aRefs, TInt aIndex);

   301 	private:

   302 		virtual TBool Match(TInt aIndex) const;

   303 		};

   304 

   305 	NONSHARABLE_CLASS(TNameIterator) : public TIterator

   306 		{

   307 	public:

   308 		TNameIterator(const CRefs& aRefs, TInt aIndex);

   309 	private:

   310 		virtual TBool Match(TInt aIndex) const;

   311 		};

   312 

   313 private:

   314 	CRefs iRefs;

   315 	CCdlNames iNames;

   316 	};

   317 

   318 

   319 #include <CdlRefs.inl>

   320 

   321 #endif