williamr@2: // Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #if !defined(__BANAMEDPLUGINS_H__)
williamr@2: #define __BANAMEDPLUGINS_H__
williamr@2: 
williamr@2: #if !defined(__E32STD_H__)
williamr@2: #include <e32std.h>
williamr@2: #endif
williamr@2: 
williamr@2: #if !defined(__E32BASE_H__)
williamr@2: #include <e32base.h>
williamr@2: #endif
williamr@2: 
williamr@2: #if !defined(__BAMDESCA_H__)
williamr@2: #include <bamdesca.h>
williamr@2: #endif
williamr@2: 
williamr@2: class RFs;
williamr@2: 
williamr@2: 
williamr@2: class CBaNamedPlugins : public CBase, public MDesCArray
williamr@2: /** 
williamr@2: A localised list of the names of the plug-ins available on the phone for a 
williamr@2: particular plug-in framework.
williamr@2: 
williamr@2: This class should be used by applications that display lists of plug-ins. 
williamr@2: It is provided so that the plug-in names displayed to users:
williamr@2: 
williamr@2: are not filenames
williamr@2: 
williamr@2: are localisable, i.e. for a multi-language ROM device, plug-in names must 
williamr@2: be translated into the correct language and sorted according to the locale's 
williamr@2: collation rules
williamr@2: 
williamr@2: can be filtered depending on the current locale, i.e. the user will not necessarily 
williamr@2: see the names of all plug-ins for a given framework for every language of 
williamr@2: a multi-language ROM.
williamr@2: 
williamr@2: Note that the class MDesC16Array is shown in the derivation tree. The class 
williamr@2: definition for CBaNamedPlugins, however, uses the typedef MDesCArray. In 6.1 
williamr@2: builds, the symbol MDesCArray always resolves to MDesC16Array.
williamr@2: 
williamr@2: @see MDesCArray
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: /** The prototype for a function that compares two plug-in names, aName1 and aName2 
williamr@2: for sorting.
williamr@2: 
williamr@2: The plug-in names list is sorted using this algorithm after it has been populated. 
williamr@2: Implementing this function is optional. If implemented, it is passed as a 
williamr@2: parameter to CParameters::SetCompareNames(). If not implemented, a default 
williamr@2: algorithm is used.
williamr@2: 
williamr@2: The function should return a positive value if aName1 is to occur after aName2 
williamr@2: or negative if aName1 is to occur before aName2. Zero should be returned if 
williamr@2: both descriptors are equivalent. */
williamr@2: 	typedef TInt (*TCompareNames)(const TDesC& aName1, const TDesC& aName2);
williamr@2: 
williamr@2: /** The prototype for a function that compares two plug-in identifiers, aIdentifier1 
williamr@2: and aIdentifier2 to find out if they are the same.
williamr@2: 
williamr@2: Implementing this function is optional. If implemented, it is passed to CBaNamedPlugins::IndexOfIdentifier(), 
williamr@2: which uses the function to compare a specified plug-in identifier with each 
williamr@2: identifier in turn in the list of named plug-ins. The function should return 
williamr@2: ETrue if they are the same, EFalse if not. TDesC::CompareC() could be used to 
williamr@2: do the comparison.
williamr@2: 
williamr@2: @see TDesC16::CompareC()
williamr@2: @see TDesC8::CompareC() */
williamr@2: 	typedef TBool (*TEquivalentIdentifiers)(const TDesC& aIdentifier1, const TDesC& aIdentifier2);
williamr@2: 
williamr@2: /** The position in the list of plug-in names for the text string which represents 
williamr@2: the choice of no plug-in.
williamr@2: 
williamr@2: Passed as an argument to SetTextForNoneL() and SetTextForNone(). */
williamr@2: 	enum TArrayPosition
williamr@2: 		{
williamr@2: 	/** The string is inserted at the start of the list (array position zero). */
williamr@2: 		EArrayPositionFirst,
williamr@2: 
williamr@2: 	/** The string is appended to the list. */
williamr@2: 		EArrayPositionLast
williamr@2: 		};
williamr@2: 
williamr@2: 	class TResourceFile
williamr@2: /** Information about a resource file containing the names of one or more named 
williamr@2: plug-ins. 
williamr@2: 
williamr@2: The information is the full filename of the resource file (the language-specific 
williamr@2: version of this file provides the localised names, for display to users), 
williamr@2: the format for the contents of the resource file and a unique identifier for 
williamr@2: the plug-in, which is either a UID or an arbitrary textual identifier (this 
williamr@2: is not for display).
williamr@2: 
williamr@2: An array of TResourceFile objects is passed to CParameters::NewL() and NewLC(). */
williamr@2: 		{
williamr@2: 	public:
williamr@2: /** The format of the contents of a resource file.
williamr@2: 
williamr@2: The EFormatArrayOfUidNamePairs format enables the names of multiple plug-ins 
williamr@2: to be held in a single resource file. This could be used in situations where 
williamr@2: a fixed set of plug-ins are provided in a single package, e.g. the plug-ins 
williamr@2: provided in a ROM (helping to reduce ROM space). In other cases, the EFormatTbuf 
williamr@2: format should be used (here a single resource file provides the name of a 
williamr@2: single plug-in). */
williamr@2: 		enum TFormat
williamr@2: 			{
williamr@2: 	
williamr@2: 	/** The resource file contains a single TBUF (text string) resource, to hold the 
williamr@2: 	plug-in name. */
williamr@2: 			EFormatTbuf, // the resource is a TBUF
williamr@2: 
williamr@2: 			
williamr@2: 	/** The resource file contains an ARRAY resource, whose items are UID_NAME_PAIR 
williamr@2: 	structs. These contain plug-in UID and name pairs. */
williamr@2: 			EFormatArrayOfUidNamePairs // the resource is an ARRAY of UID_NAME_PAIR
williamr@2: 			};
williamr@2: 	public:
williamr@2: 	/** The full filename of the resource file, with a language-independent extension 
williamr@2: 	(i.e. .rsc rather than, for instance, .r12). The language-specific version 
williamr@2: 	of this file (with the correct language extension) contains the localised 
williamr@2: 	name of the plug-in. The BaflUtils class is used internally to create the 
williamr@2: 	correct language extension for iFullFileName.
williamr@2: 	
williamr@2: 	@see BaflUtils::NearestLanguageFile() */
williamr@2: 		HBufC* iFullFileName;
williamr@2: 	/** Optional unique identifier for the plug-in , for instance the filename of the 
williamr@2: 	plug in's DLL. If not applicable, it may be NULL. */
williamr@2: 		HBufC* iIdentifier; // this may be NULL
williamr@2: 	/** Optional plug-in UID. If not applicable, it may have a value of KNullUid. */
williamr@2: 		TUid iUid; // this may be KNullUid
williamr@2: 	/** The format of the resource file's contents. */
williamr@2: 		TFormat iFormat;
williamr@2: 		};
williamr@2: 
williamr@2: 	class MFallBackName
williamr@2: /** 
williamr@2: Interface class with a single pure virtual function that generates a fallback 
williamr@2: name for plug-ins.
williamr@2: 
williamr@2: The FallBackNameL() function is called during construction of the CBaNamedPlugins 
williamr@2: object for any plug-ins for which no resource file could be found with the 
williamr@2: correct language extension.
williamr@2: 
williamr@2: Use of this interface is optional. To use it, pass an instance of a class 
williamr@2: which implements the interface to CParameters::SetFallBackName(). If this 
williamr@2: is not done, then by default the fallback name used for plug-ins is simply 
williamr@2: the filename of the resource file without the drive, directory path or extension. 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 		{
williamr@2: 	public:
williamr@2: 	/** 
williamr@2: 	Generates and returns a fallback name for plug-ins for which no resource is 
williamr@2: 	available. The fallback name can be generated using the filename of the plug-in's 
williamr@2: 	resource file, which is passed as an argument.
williamr@2: 	
williamr@2: 	@param aFullResourceFileName The full filename of the resource file. This 
williamr@2: 	is the same as TResourceFile::iFullFileName.
williamr@2: 	@return The fallback name for a plug-in. 
williamr@2: 	*/
williamr@2: 		virtual HBufC* FallBackNameL(const TDesC& aFullResourceFileName) const=0;
williamr@2: 	private:
williamr@2: 		IMPORT_C virtual void MFallBackName_Reserved_1();
williamr@2: 		IMPORT_C virtual void MFallBackName_Reserved_2();
williamr@2: 		};
williamr@2: 
williamr@2: 		class CParameters : public CBase
williamr@2: /** 
williamr@2: The parameters for a localised list of plug-in names.
williamr@2: 
williamr@2: An object of this class is passed to CBaNamedPlugins::NewL() and NewLC(). 
williamr@2: The parameters are as follows - minimally, the first two must be provided:
williamr@2: 
williamr@2: An array of TResourceFile objects. Each object contains information about 
williamr@2: a single plug-in, or multiple plug-ins, including the filename of the corresponding 
williamr@2: resource file. Versions of these resource files with the correct filename 
williamr@2: extensions for the required languages provide the name of one or more plug-in, 
williamr@2: translated appropriately.
williamr@2: 
williamr@2: A connected session with the file server. This is required to search the file 
williamr@2: sytem for the localised resource files, then to open them for reading.
williamr@2: 
williamr@2: An optional object that generates a fallback name for plug-ins, if no resource 
williamr@2: file could be found. If no such function is provided, then the fallback name 
williamr@2: used for plug-ins is simply the filename of the resource file without the 
williamr@2: drive, directory path or extension.
williamr@2: 
williamr@2: An optional function that compares two plug-in names for sorting. The list 
williamr@2: is sorted after it has been fully populated, using this algorithm. If not 
williamr@2: specified, sorting is done by using the system-wide (locale-dependent) collation 
williamr@2: rules.
williamr@2: 
williamr@2: An optional descriptor which, if provided, adds an additional item whose meaning 
williamr@2: is "none" (i.e. "no plug-in") to the MDesCArray, and the array position (either 
williamr@2: the start or the end of the array) at which to insert it. 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: 		{
williamr@2: 	public:
williamr@2: 	IMPORT_C static CParameters* NewL(RFs& aFileServerSession, const TArray<TResourceFile>& aArrayOfResourceFiles);
williamr@2: 	IMPORT_C static CParameters* NewLC(RFs& aFileServerSession, const TArray<TResourceFile>& aArrayOfResourceFiles);
williamr@2: 	IMPORT_C virtual ~CParameters();
williamr@2: 	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
williamr@2: 	IMPORT_C void SetCompareNames(TCompareNames aCompareNames);
williamr@2: 		// SetTextForNoneL and SetTextForNone both add an extra item to the array (i.e. to the MDesCArray interface)
williamr@2: 	IMPORT_C void SetTextForNoneL(const TDesC& aTextForNone, TArrayPosition aArrayPositionOfTextForNone);
williamr@2: 	IMPORT_C void SetTextForNone(HBufC* aTextForNone, TArrayPosition aArrayPositionOfTextForNone); // passes ownership of aTextForNone in to the CParameters object
williamr@2: 	private:
williamr@2: 		CParameters(RFs& aFileServerSession);
williamr@2: 		void ConstructL(const TArray<TResourceFile>& aArrayOfResourceFiles);
williamr@2: 	private:
williamr@2: 		RFs& iFileServerSession;
williamr@2: 		TArray<TResourceFile>* iArrayOfResourceFiles; // a shallow copy
williamr@2: 		const MFallBackName* iFallBackName;
williamr@2: 		TCompareNames iCompareNames;
williamr@2: 		HBufC* iTextForNone;
williamr@2: 		TArrayPosition iArrayPositionOfTextForNone; // this is undefined if iTextForNone is NULL
williamr@2: 	private:
williamr@2: 		friend class CBaNamedPlugins;
williamr@2: 		};
williamr@2: public:
williamr@2: 	IMPORT_C static CBaNamedPlugins* NewL(const CParameters& aParameters);
williamr@2: 	IMPORT_C static CBaNamedPlugins* NewLC(const CParameters& aParameters);
williamr@2: 	IMPORT_C virtual ~CBaNamedPlugins();
williamr@2: 	IMPORT_C TInt IndexOfUid(TUid aUid) const;
williamr@2: 	IMPORT_C TInt IndexOfIdentifier(const TDesC& aIdentifier, TEquivalentIdentifiers aEquivalentIdentifiers) const;
williamr@2: 	IMPORT_C TUid UidAtIndex(TInt aIndex) const;
williamr@2: 	IMPORT_C const TDesC* IdentifierAtIndex(TInt aIndex) const;
williamr@2: 	// from MDesCArray
williamr@2: 	IMPORT_C virtual TInt MdcaCount() const;
williamr@2: 	IMPORT_C virtual TPtrC MdcaPoint(TInt aIndex) const;
williamr@2: private:
williamr@2: 	class TNamedPlugIn
williamr@2: /** This class is internal and is not intended for use. */
williamr@2: 		{
williamr@2: 	public:
williamr@2: 		HBufC* iName;
williamr@2: 		HBufC* iIdentifier; // this may be NULL
williamr@2: 		TUid iUid;
williamr@2: 		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)
williamr@2: 		};
williamr@2: private:
williamr@2: 	CBaNamedPlugins(TInt aGranularity);
williamr@2: 	void ConstructL(const CParameters& aParameters);
williamr@2: 	static TInt CompareNamedPlugIns(const TNamedPlugIn& aNamedPlugIn1, const TNamedPlugIn& aNamedPlugIn2);
williamr@2: 	static TInt DefaultAlgorithmToCompareNames(const TDesC& aName1, const TDesC& aName2);
williamr@2: private:
williamr@2: 	RArray<TNamedPlugIn> iArrayOfNamedPlugIns;
williamr@2: 	};
williamr@2: 
williamr@2: #endif