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