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
|