epoc32/include/banamedplugins.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
// Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2
     2
// All rights reserved.
williamr@2
     3
// This component and the accompanying materials are made available
williamr@2
     4
// 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
     5
// which accompanies this distribution, and is available
williamr@2
     6
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     7
//
williamr@2
     8
// Initial Contributors:
williamr@2
     9
// Nokia Corporation - initial contribution.
williamr@2
    10
//
williamr@2
    11
// Contributors:
williamr@2
    12
//
williamr@2
    13
// Description:
williamr@2
    14
//
williamr@2
    15
williamr@2
    16
#if !defined(__BANAMEDPLUGINS_H__)
williamr@2
    17
#define __BANAMEDPLUGINS_H__
williamr@2
    18
williamr@2
    19
#if !defined(__E32STD_H__)
williamr@2
    20
#include <e32std.h>
williamr@2
    21
#endif
williamr@2
    22
williamr@2
    23
#if !defined(__E32BASE_H__)
williamr@2
    24
#include <e32base.h>
williamr@2
    25
#endif
williamr@2
    26
williamr@2
    27
#if !defined(__BAMDESCA_H__)
williamr@2
    28
#include <bamdesca.h>
williamr@2
    29
#endif
williamr@2
    30
williamr@2
    31
class RFs;
williamr@2
    32
williamr@2
    33
williamr@2
    34
class CBaNamedPlugins : public CBase, public MDesCArray
williamr@2
    35
/** 
williamr@2
    36
A localised list of the names of the plug-ins available on the phone for a 
williamr@2
    37
particular plug-in framework.
williamr@2
    38
williamr@2
    39
This class should be used by applications that display lists of plug-ins. 
williamr@2
    40
It is provided so that the plug-in names displayed to users:
williamr@2
    41
williamr@2
    42
are not filenames
williamr@2
    43
williamr@2
    44
are localisable, i.e. for a multi-language ROM device, plug-in names must 
williamr@2
    45
be translated into the correct language and sorted according to the locale's 
williamr@2
    46
collation rules
williamr@2
    47
williamr@2
    48
can be filtered depending on the current locale, i.e. the user will not necessarily 
williamr@2
    49
see the names of all plug-ins for a given framework for every language of 
williamr@2
    50
a multi-language ROM.
williamr@2
    51
williamr@2
    52
Note that the class MDesC16Array is shown in the derivation tree. The class 
williamr@2
    53
definition for CBaNamedPlugins, however, uses the typedef MDesCArray. In 6.1 
williamr@2
    54
builds, the symbol MDesCArray always resolves to MDesC16Array.
williamr@2
    55
williamr@2
    56
@see MDesCArray
williamr@2
    57
@publishedAll
williamr@2
    58
@released
williamr@2
    59
*/
williamr@2
    60
	{
williamr@2
    61
public:
williamr@2
    62
/** The prototype for a function that compares two plug-in names, aName1 and aName2 
williamr@2
    63
for sorting.
williamr@2
    64
williamr@2
    65
The plug-in names list is sorted using this algorithm after it has been populated. 
williamr@2
    66
Implementing this function is optional. If implemented, it is passed as a 
williamr@2
    67
parameter to CParameters::SetCompareNames(). If not implemented, a default 
williamr@2
    68
algorithm is used.
williamr@2
    69
williamr@2
    70
The function should return a positive value if aName1 is to occur after aName2 
williamr@2
    71
or negative if aName1 is to occur before aName2. Zero should be returned if 
williamr@2
    72
both descriptors are equivalent. */
williamr@2
    73
	typedef TInt (*TCompareNames)(const TDesC& aName1, const TDesC& aName2);
williamr@2
    74
williamr@2
    75
/** The prototype for a function that compares two plug-in identifiers, aIdentifier1 
williamr@2
    76
and aIdentifier2 to find out if they are the same.
williamr@2
    77
williamr@2
    78
Implementing this function is optional. If implemented, it is passed to CBaNamedPlugins::IndexOfIdentifier(), 
williamr@2
    79
which uses the function to compare a specified plug-in identifier with each 
williamr@2
    80
identifier in turn in the list of named plug-ins. The function should return 
williamr@2
    81
ETrue if they are the same, EFalse if not. TDesC::CompareC() could be used to 
williamr@2
    82
do the comparison.
williamr@2
    83
williamr@2
    84
@see TDesC16::CompareC()
williamr@2
    85
@see TDesC8::CompareC() */
williamr@2
    86
	typedef TBool (*TEquivalentIdentifiers)(const TDesC& aIdentifier1, const TDesC& aIdentifier2);
williamr@2
    87
williamr@2
    88
/** The position in the list of plug-in names for the text string which represents 
williamr@2
    89
the choice of no plug-in.
williamr@2
    90
williamr@2
    91
Passed as an argument to SetTextForNoneL() and SetTextForNone(). */
williamr@2
    92
	enum TArrayPosition
williamr@2
    93
		{
williamr@2
    94
	/** The string is inserted at the start of the list (array position zero). */
williamr@2
    95
		EArrayPositionFirst,
williamr@2
    96
williamr@2
    97
	/** The string is appended to the list. */
williamr@2
    98
		EArrayPositionLast
williamr@2
    99
		};
williamr@2
   100
williamr@2
   101
	class TResourceFile
williamr@2
   102
/** Information about a resource file containing the names of one or more named 
williamr@2
   103
plug-ins. 
williamr@2
   104
williamr@2
   105
The information is the full filename of the resource file (the language-specific 
williamr@2
   106
version of this file provides the localised names, for display to users), 
williamr@2
   107
the format for the contents of the resource file and a unique identifier for 
williamr@2
   108
the plug-in, which is either a UID or an arbitrary textual identifier (this 
williamr@2
   109
is not for display).
williamr@2
   110
williamr@2
   111
An array of TResourceFile objects is passed to CParameters::NewL() and NewLC(). */
williamr@2
   112
		{
williamr@2
   113
	public:
williamr@2
   114
/** The format of the contents of a resource file.
williamr@2
   115
williamr@2
   116
The EFormatArrayOfUidNamePairs format enables the names of multiple plug-ins 
williamr@2
   117
to be held in a single resource file. This could be used in situations where 
williamr@2
   118
a fixed set of plug-ins are provided in a single package, e.g. the plug-ins 
williamr@2
   119
provided in a ROM (helping to reduce ROM space). In other cases, the EFormatTbuf 
williamr@2
   120
format should be used (here a single resource file provides the name of a 
williamr@2
   121
single plug-in). */
williamr@2
   122
		enum TFormat
williamr@2
   123
			{
williamr@2
   124
	
williamr@2
   125
	/** The resource file contains a single TBUF (text string) resource, to hold the 
williamr@2
   126
	plug-in name. */
williamr@2
   127
			EFormatTbuf, // the resource is a TBUF
williamr@2
   128
williamr@2
   129
			
williamr@2
   130
	/** The resource file contains an ARRAY resource, whose items are UID_NAME_PAIR 
williamr@2
   131
	structs. These contain plug-in UID and name pairs. */
williamr@2
   132
			EFormatArrayOfUidNamePairs // the resource is an ARRAY of UID_NAME_PAIR
williamr@2
   133
			};
williamr@2
   134
	public:
williamr@2
   135
	/** The full filename of the resource file, with a language-independent extension 
williamr@2
   136
	(i.e. .rsc rather than, for instance, .r12). The language-specific version 
williamr@2
   137
	of this file (with the correct language extension) contains the localised 
williamr@2
   138
	name of the plug-in. The BaflUtils class is used internally to create the 
williamr@2
   139
	correct language extension for iFullFileName.
williamr@2
   140
	
williamr@2
   141
	@see BaflUtils::NearestLanguageFile() */
williamr@2
   142
		HBufC* iFullFileName;
williamr@2
   143
	/** Optional unique identifier for the plug-in , for instance the filename of the 
williamr@2
   144
	plug in's DLL. If not applicable, it may be NULL. */
williamr@2
   145
		HBufC* iIdentifier; // this may be NULL
williamr@2
   146
	/** Optional plug-in UID. If not applicable, it may have a value of KNullUid. */
williamr@2
   147
		TUid iUid; // this may be KNullUid
williamr@2
   148
	/** The format of the resource file's contents. */
williamr@2
   149
		TFormat iFormat;
williamr@2
   150
		};
williamr@2
   151
williamr@2
   152
	class MFallBackName
williamr@2
   153
/** 
williamr@2
   154
Interface class with a single pure virtual function that generates a fallback 
williamr@2
   155
name for plug-ins.
williamr@2
   156
williamr@2
   157
The FallBackNameL() function is called during construction of the CBaNamedPlugins 
williamr@2
   158
object for any plug-ins for which no resource file could be found with the 
williamr@2
   159
correct language extension.
williamr@2
   160
williamr@2
   161
Use of this interface is optional. To use it, pass an instance of a class 
williamr@2
   162
which implements the interface to CParameters::SetFallBackName(). If this 
williamr@2
   163
is not done, then by default the fallback name used for plug-ins is simply 
williamr@2
   164
the filename of the resource file without the drive, directory path or extension. 
williamr@2
   165
@publishedAll
williamr@2
   166
@released
williamr@2
   167
*/
williamr@2
   168
		{
williamr@2
   169
	public:
williamr@2
   170
	/** 
williamr@2
   171
	Generates and returns a fallback name for plug-ins for which no resource is 
williamr@2
   172
	available. The fallback name can be generated using the filename of the plug-in's 
williamr@2
   173
	resource file, which is passed as an argument.
williamr@2
   174
	
williamr@2
   175
	@param aFullResourceFileName The full filename of the resource file. This 
williamr@2
   176
	is the same as TResourceFile::iFullFileName.
williamr@2
   177
	@return The fallback name for a plug-in. 
williamr@2
   178
	*/
williamr@2
   179
		virtual HBufC* FallBackNameL(const TDesC& aFullResourceFileName) const=0;
williamr@2
   180
	private:
williamr@2
   181
		IMPORT_C virtual void MFallBackName_Reserved_1();
williamr@2
   182
		IMPORT_C virtual void MFallBackName_Reserved_2();
williamr@2
   183
		};
williamr@2
   184
williamr@2
   185
		class CParameters : public CBase
williamr@2
   186
/** 
williamr@2
   187
The parameters for a localised list of plug-in names.
williamr@2
   188
williamr@2
   189
An object of this class is passed to CBaNamedPlugins::NewL() and NewLC(). 
williamr@2
   190
The parameters are as follows - minimally, the first two must be provided:
williamr@2
   191
williamr@2
   192
An array of TResourceFile objects. Each object contains information about 
williamr@2
   193
a single plug-in, or multiple plug-ins, including the filename of the corresponding 
williamr@2
   194
resource file. Versions of these resource files with the correct filename 
williamr@2
   195
extensions for the required languages provide the name of one or more plug-in, 
williamr@2
   196
translated appropriately.
williamr@2
   197
williamr@2
   198
A connected session with the file server. This is required to search the file 
williamr@2
   199
sytem for the localised resource files, then to open them for reading.
williamr@2
   200
williamr@2
   201
An optional object that generates a fallback name for plug-ins, if no resource 
williamr@2
   202
file could be found. If no such function is provided, then the fallback name 
williamr@2
   203
used for plug-ins is simply the filename of the resource file without the 
williamr@2
   204
drive, directory path or extension.
williamr@2
   205
williamr@2
   206
An optional function that compares two plug-in names for sorting. The list 
williamr@2
   207
is sorted after it has been fully populated, using this algorithm. If not 
williamr@2
   208
specified, sorting is done by using the system-wide (locale-dependent) collation 
williamr@2
   209
rules.
williamr@2
   210
williamr@2
   211
An optional descriptor which, if provided, adds an additional item whose meaning 
williamr@2
   212
is "none" (i.e. "no plug-in") to the MDesCArray, and the array position (either 
williamr@2
   213
the start or the end of the array) at which to insert it. 
williamr@2
   214
@publishedAll
williamr@2
   215
@released
williamr@2
   216
*/
williamr@2
   217
		{
williamr@2
   218
	public:
williamr@2
   219
	IMPORT_C static CParameters* NewL(RFs& aFileServerSession, const TArray<TResourceFile>& aArrayOfResourceFiles);
williamr@2
   220
	IMPORT_C static CParameters* NewLC(RFs& aFileServerSession, const TArray<TResourceFile>& aArrayOfResourceFiles);
williamr@2
   221
	IMPORT_C virtual ~CParameters();
williamr@2
   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
williamr@2
   223
	IMPORT_C void SetCompareNames(TCompareNames aCompareNames);
williamr@2
   224
		// SetTextForNoneL and SetTextForNone both add an extra item to the array (i.e. to the MDesCArray interface)
williamr@2
   225
	IMPORT_C void SetTextForNoneL(const TDesC& aTextForNone, TArrayPosition aArrayPositionOfTextForNone);
williamr@2
   226
	IMPORT_C void SetTextForNone(HBufC* aTextForNone, TArrayPosition aArrayPositionOfTextForNone); // passes ownership of aTextForNone in to the CParameters object
williamr@2
   227
	private:
williamr@2
   228
		CParameters(RFs& aFileServerSession);
williamr@2
   229
		void ConstructL(const TArray<TResourceFile>& aArrayOfResourceFiles);
williamr@2
   230
	private:
williamr@2
   231
		RFs& iFileServerSession;
williamr@2
   232
		TArray<TResourceFile>* iArrayOfResourceFiles; // a shallow copy
williamr@2
   233
		const MFallBackName* iFallBackName;
williamr@2
   234
		TCompareNames iCompareNames;
williamr@2
   235
		HBufC* iTextForNone;
williamr@2
   236
		TArrayPosition iArrayPositionOfTextForNone; // this is undefined if iTextForNone is NULL
williamr@2
   237
	private:
williamr@2
   238
		friend class CBaNamedPlugins;
williamr@2
   239
		};
williamr@2
   240
public:
williamr@2
   241
	IMPORT_C static CBaNamedPlugins* NewL(const CParameters& aParameters);
williamr@2
   242
	IMPORT_C static CBaNamedPlugins* NewLC(const CParameters& aParameters);
williamr@2
   243
	IMPORT_C virtual ~CBaNamedPlugins();
williamr@2
   244
	IMPORT_C TInt IndexOfUid(TUid aUid) const;
williamr@2
   245
	IMPORT_C TInt IndexOfIdentifier(const TDesC& aIdentifier, TEquivalentIdentifiers aEquivalentIdentifiers) const;
williamr@2
   246
	IMPORT_C TUid UidAtIndex(TInt aIndex) const;
williamr@2
   247
	IMPORT_C const TDesC* IdentifierAtIndex(TInt aIndex) const;
williamr@2
   248
	// from MDesCArray
williamr@2
   249
	IMPORT_C virtual TInt MdcaCount() const;
williamr@2
   250
	IMPORT_C virtual TPtrC MdcaPoint(TInt aIndex) const;
williamr@2
   251
private:
williamr@2
   252
	class TNamedPlugIn
williamr@2
   253
/** This class is internal and is not intended for use. */
williamr@2
   254
		{
williamr@2
   255
	public:
williamr@2
   256
		HBufC* iName;
williamr@2
   257
		HBufC* iIdentifier; // this may be NULL
williamr@2
   258
		TUid iUid;
williamr@2
   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)
williamr@2
   260
		};
williamr@2
   261
private:
williamr@2
   262
	CBaNamedPlugins(TInt aGranularity);
williamr@2
   263
	void ConstructL(const CParameters& aParameters);
williamr@2
   264
	static TInt CompareNamedPlugIns(const TNamedPlugIn& aNamedPlugIn1, const TNamedPlugIn& aNamedPlugIn2);
williamr@2
   265
	static TInt DefaultAlgorithmToCompareNames(const TDesC& aName1, const TDesC& aName2);
williamr@2
   266
private:
williamr@2
   267
	RArray<TNamedPlugIn> iArrayOfNamedPlugIns;
williamr@2
   268
	};
williamr@2
   269
williamr@2
   270
#endif