1 // Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #if !defined(__BANAMEDPLUGINS_H__)

    17 #define __BANAMEDPLUGINS_H__

    18 

    19 #if !defined(__E32STD_H__)

    20 #include <e32std.h>

    21 #endif

    22 

    23 #if !defined(__E32BASE_H__)

    24 #include <e32base.h>

    25 #endif

    26 

    27 #if !defined(__BAMDESCA_H__)

    28 #include <bamdesca.h>

    29 #endif

    30 

    31 class RFs;

    32 

    33 

    34 class CBaNamedPlugins : public CBase, public MDesCArray

    35 /** 

    36 A localised list of the names of the plug-ins available on the phone for a 

    37 particular plug-in framework.

    38 

    39 This class should be used by applications that display lists of plug-ins. 

    40 It is provided so that the plug-in names displayed to users:

    41 

    42 are not filenames

    43 

    44 are localisable, i.e. for a multi-language ROM device, plug-in names must 

    45 be translated into the correct language and sorted according to the locale's 

    46 collation rules

    47 

    48 can be filtered depending on the current locale, i.e. the user will not necessarily 

    49 see the names of all plug-ins for a given framework for every language of 

    50 a multi-language ROM.

    51 

    52 Note that the class MDesC16Array is shown in the derivation tree. The class 

    53 definition for CBaNamedPlugins, however, uses the typedef MDesCArray. In 6.1 

    54 builds, the symbol MDesCArray always resolves to MDesC16Array.

    55 

    56 @see MDesCArray

    57 @publishedAll

    58 @released

    59 */

    60 	{

    61 public:

    62 /** The prototype for a function that compares two plug-in names, aName1 and aName2 

    63 for sorting.

    64 

    65 The plug-in names list is sorted using this algorithm after it has been populated. 

    66 Implementing this function is optional. If implemented, it is passed as a 

    67 parameter to CParameters::SetCompareNames(). If not implemented, a default 

    68 algorithm is used.

    69 

    70 The function should return a positive value if aName1 is to occur after aName2 

    71 or negative if aName1 is to occur before aName2. Zero should be returned if 

    72 both descriptors are equivalent. */

    73 	typedef TInt (*TCompareNames)(const TDesC& aName1, const TDesC& aName2);

    74 

    75 /** The prototype for a function that compares two plug-in identifiers, aIdentifier1 

    76 and aIdentifier2 to find out if they are the same.

    77 

    78 Implementing this function is optional. If implemented, it is passed to CBaNamedPlugins::IndexOfIdentifier(), 

    79 which uses the function to compare a specified plug-in identifier with each 

    80 identifier in turn in the list of named plug-ins. The function should return 

    81 ETrue if they are the same, EFalse if not. TDesC::CompareC() could be used to 

    82 do the comparison.

    83 

    84 @see TDesC16::CompareC()

    85 @see TDesC8::CompareC() */

    86 	typedef TBool (*TEquivalentIdentifiers)(const TDesC& aIdentifier1, const TDesC& aIdentifier2);

    87 

    88 /** The position in the list of plug-in names for the text string which represents 

    89 the choice of no plug-in.

    90 

    91 Passed as an argument to SetTextForNoneL() and SetTextForNone(). */

    92 	enum TArrayPosition

    93 		{

    94 	/** The string is inserted at the start of the list (array position zero). */

    95 		EArrayPositionFirst,

    96 

    97 	/** The string is appended to the list. */

    98 		EArrayPositionLast

    99 		};

   100 

   101 	class TResourceFile

   102 /** Information about a resource file containing the names of one or more named 

   103 plug-ins. 

   104 

   105 The information is the full filename of the resource file (the language-specific 

   106 version of this file provides the localised names, for display to users), 

   107 the format for the contents of the resource file and a unique identifier for 

   108 the plug-in, which is either a UID or an arbitrary textual identifier (this 

   109 is not for display).

   110 

   111 An array of TResourceFile objects is passed to CParameters::NewL() and NewLC(). */

   112 		{

   113 	public:

   114 /** The format of the contents of a resource file.

   115 

   116 The EFormatArrayOfUidNamePairs format enables the names of multiple plug-ins 

   117 to be held in a single resource file. This could be used in situations where 

   118 a fixed set of plug-ins are provided in a single package, e.g. the plug-ins 

   119 provided in a ROM (helping to reduce ROM space). In other cases, the EFormatTbuf 

   120 format should be used (here a single resource file provides the name of a 

   121 single plug-in). */

   122 		enum TFormat

   123 			{

   124 	

   125 	/** The resource file contains a single TBUF (text string) resource, to hold the 

   126 	plug-in name. */

   127 			EFormatTbuf, // the resource is a TBUF

   128 

   129 			

   130 	/** The resource file contains an ARRAY resource, whose items are UID_NAME_PAIR 

   131 	structs. These contain plug-in UID and name pairs. */

   132 			EFormatArrayOfUidNamePairs // the resource is an ARRAY of UID_NAME_PAIR

   133 			};

   134 	public:

   135 	/** The full filename of the resource file, with a language-independent extension 

   136 	(i.e. .rsc rather than, for instance, .r12). The language-specific version 

   137 	of this file (with the correct language extension) contains the localised 

   138 	name of the plug-in. The BaflUtils class is used internally to create the 

   139 	correct language extension for iFullFileName.

   140 	

   141 	@see BaflUtils::NearestLanguageFile() */

   142 		HBufC* iFullFileName;

   143 	/** Optional unique identifier for the plug-in , for instance the filename of the 

   144 	plug in's DLL. If not applicable, it may be NULL. */

   145 		HBufC* iIdentifier; // this may be NULL

   146 	/** Optional plug-in UID. If not applicable, it may have a value of KNullUid. */

   147 		TUid iUid; // this may be KNullUid

   148 	/** The format of the resource file's contents. */

   149 		TFormat iFormat;

   150 		};

   151 

   152 	class MFallBackName

   153 /** 

   154 Interface class with a single pure virtual function that generates a fallback 

   155 name for plug-ins.

   156 

   157 The FallBackNameL() function is called during construction of the CBaNamedPlugins 

   158 object for any plug-ins for which no resource file could be found with the 

   159 correct language extension.

   160 

   161 Use of this interface is optional. To use it, pass an instance of a class 

   162 which implements the interface to CParameters::SetFallBackName(). If this 

   163 is not done, then by default the fallback name used for plug-ins is simply 

   164 the filename of the resource file without the drive, directory path or extension. 

   165 @publishedAll

   166 @released

   167 */

   168 		{

   169 	public:

   170 	/** 

   171 	Generates and returns a fallback name for plug-ins for which no resource is 

   172 	available. The fallback name can be generated using the filename of the plug-in's 

   173 	resource file, which is passed as an argument.

   174 	

   175 	@param aFullResourceFileName The full filename of the resource file. This 

   176 	is the same as TResourceFile::iFullFileName.

   177 	@return The fallback name for a plug-in. 

   178 	*/

   179 		virtual HBufC* FallBackNameL(const TDesC& aFullResourceFileName) const=0;

   180 	private:

   181 		IMPORT_C virtual void MFallBackName_Reserved_1();

   182 		IMPORT_C virtual void MFallBackName_Reserved_2();

   183 		};

   184 

   185 		class CParameters : public CBase

   186 /** 

   187 The parameters for a localised list of plug-in names.

   188 

   189 An object of this class is passed to CBaNamedPlugins::NewL() and NewLC(). 

   190 The parameters are as follows - minimally, the first two must be provided:

   191 

   192 An array of TResourceFile objects. Each object contains information about 

   193 a single plug-in, or multiple plug-ins, including the filename of the corresponding 

   194 resource file. Versions of these resource files with the correct filename 

   195 extensions for the required languages provide the name of one or more plug-in, 

   196 translated appropriately.

   197 

   198 A connected session with the file server. This is required to search the file 

   199 sytem for the localised resource files, then to open them for reading.

   200 

   201 An optional object that generates a fallback name for plug-ins, if no resource 

   202 file could be found. If no such function is provided, then the fallback name 

   203 used for plug-ins is simply the filename of the resource file without the 

   204 drive, directory path or extension.

   205 

   206 An optional function that compares two plug-in names for sorting. The list 

   207 is sorted after it has been fully populated, using this algorithm. If not 

   208 specified, sorting is done by using the system-wide (locale-dependent) collation 

   209 rules.

   210 

   211 An optional descriptor which, if provided, adds an additional item whose meaning 

   212 is "none" (i.e. "no plug-in") to the MDesCArray, and the array position (either 

   213 the start or the end of the array) at which to insert it. 

   214 @publishedAll

   215 @released

   216 */

   217 		{

   218 	public:

   219 	IMPORT_C static CParameters* NewL(RFs& aFileServerSession, const TArray<TResourceFile>& aArrayOfResourceFiles);

   220 	IMPORT_C static CParameters* NewLC(RFs& aFileServerSession, const TArray<TResourceFile>& aArrayOfResourceFiles);

   221 	IMPORT_C virtual ~CParameters();

   222 	IMPORT_C void SetFallBackName(const MFallBackName& aFallBackName); // fall-back name is used if the resource file does not exist - by default the name of the file without drive, directories or extension is used

   223 	IMPORT_C void SetCompareNames(TCompareNames aCompareNames);

   224 		// SetTextForNoneL and SetTextForNone both add an extra item to the array (i.e. to the MDesCArray interface)

   225 	IMPORT_C void SetTextForNoneL(const TDesC& aTextForNone, TArrayPosition aArrayPositionOfTextForNone);

   226 	IMPORT_C void SetTextForNone(HBufC* aTextForNone, TArrayPosition aArrayPositionOfTextForNone); // passes ownership of aTextForNone in to the CParameters object

   227 	private:

   228 		CParameters(RFs& aFileServerSession);

   229 		void ConstructL(const TArray<TResourceFile>& aArrayOfResourceFiles);

   230 	private:

   231 		RFs& iFileServerSession;

   232 		TArray<TResourceFile>* iArrayOfResourceFiles; // a shallow copy

   233 		const MFallBackName* iFallBackName;

   234 		TCompareNames iCompareNames;

   235 		HBufC* iTextForNone;

   236 		TArrayPosition iArrayPositionOfTextForNone; // this is undefined if iTextForNone is NULL

   237 	private:

   238 		friend class CBaNamedPlugins;

   239 		};

   240 public:

   241 	IMPORT_C static CBaNamedPlugins* NewL(const CParameters& aParameters);

   242 	IMPORT_C static CBaNamedPlugins* NewLC(const CParameters& aParameters);

   243 	IMPORT_C virtual ~CBaNamedPlugins();

   244 	IMPORT_C TInt IndexOfUid(TUid aUid) const;

   245 	IMPORT_C TInt IndexOfIdentifier(const TDesC& aIdentifier, TEquivalentIdentifiers aEquivalentIdentifiers) const;

   246 	IMPORT_C TUid UidAtIndex(TInt aIndex) const;

   247 	IMPORT_C const TDesC* IdentifierAtIndex(TInt aIndex) const;

   248 	// from MDesCArray

   249 	IMPORT_C virtual TInt MdcaCount() const;

   250 	IMPORT_C virtual TPtrC MdcaPoint(TInt aIndex) const;

   251 private:

   252 	class TNamedPlugIn

   253 /** This class is internal and is not intended for use. */

   254 		{

   255 	public:

   256 		HBufC* iName;

   257 		HBufC* iIdentifier; // this may be NULL

   258 		TUid iUid;

   259 		TCompareNames iCompareNames; // unfortunately the only decent way of passing this function pointer to CompareNamedPlugIns is by storing it in each TNamedPlugIn (an alternative would be to use Dll::Tls but that would be a lot more clumsy)

   260 		};

   261 private:

   262 	CBaNamedPlugins(TInt aGranularity);

   263 	void ConstructL(const CParameters& aParameters);

   264 	static TInt CompareNamedPlugIns(const TNamedPlugIn& aNamedPlugIn1, const TNamedPlugIn& aNamedPlugIn2);

   265 	static TInt DefaultAlgorithmToCompareNames(const TDesC& aName1, const TDesC& aName2);

   266 private:

   267 	RArray<TNamedPlugIn> iArrayOfNamedPlugIns;

   268 	};

   269 

   270 #endif

   271