|
1 /* |
|
2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Base plugin handler |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef CMPXPLUGINHANDLERBASE_H |
|
20 #define CMPXPLUGINHANDLERBASE_H |
|
21 |
|
22 #include <ecom/ecom.h> |
|
23 #include <badesca.h> |
|
24 #include "mpxpluginmonitorobserver.h" |
|
25 |
|
26 class CMPXPluginMonitor; |
|
27 class CMPXPluginInfo; |
|
28 class MMPXPluginHandlerObserver; |
|
29 |
|
30 /** |
|
31 * CMPXPluginHandlerBase instantiates and owns a CMPXPluginMonitor to monitor |
|
32 * plugins for the designated plugin interface. It also provides plugin |
|
33 * selection APIs and a common method for resolving a plugin from a set of |
|
34 * selection criteria. |
|
35 * |
|
36 * @lib mpxcommon.lib |
|
37 */ |
|
38 class CMPXPluginHandlerBase : public CBase, |
|
39 public MMPXPluginMonitorObserver |
|
40 { |
|
41 public: |
|
42 |
|
43 enum TPluginSelection |
|
44 { |
|
45 ESelectionType, // select a plugin by type |
|
46 ESelectionUid // select a plugin by uid |
|
47 }; |
|
48 |
|
49 public: |
|
50 |
|
51 /** |
|
52 * Constructor. |
|
53 * |
|
54 * @since S60 3.2.3 |
|
55 * @param aInterfaceUid The UID of the ECOM plugin interface this plugin |
|
56 * handler is designated for |
|
57 * @param aSelection plugin selection choices as defined in TPluginSelection |
|
58 * @param aSelectionType specifies the type of plugin for selection |
|
59 * @param aObserver plugin handler observer instance |
|
60 * @param aPluginMonitor plugin monitor. It is for the clients to share the |
|
61 * same plugin monitor object. |
|
62 */ |
|
63 IMPORT_C CMPXPluginHandlerBase( |
|
64 TUid aInterfaceUid, |
|
65 TPluginSelection aSelection, |
|
66 TInt aSelectionType, |
|
67 MMPXPluginHandlerObserver& aObserver, |
|
68 CMPXPluginMonitor* aPluginMonitor=NULL); |
|
69 |
|
70 /** |
|
71 * Destructor. |
|
72 * |
|
73 * @since S60 3.2.3 |
|
74 */ |
|
75 IMPORT_C ~CMPXPluginHandlerBase(); |
|
76 |
|
77 protected: |
|
78 /** |
|
79 * 2nd phase contructor. |
|
80 * |
|
81 * @since S60 3.2.3 |
|
82 */ |
|
83 IMPORT_C void BaseConstructL(); |
|
84 |
|
85 public: |
|
86 |
|
87 /** |
|
88 * Use this particular plugin. |
|
89 * |
|
90 * @since S60 3.2.3 |
|
91 * @param aPluginUid UID of the plugin to be used |
|
92 */ |
|
93 IMPORT_C void SelectPluginL(const TUid& aPluginUid); |
|
94 |
|
95 /** |
|
96 * Use the plugin with the specified display name. |
|
97 * |
|
98 * @since S60 3.2.3 |
|
99 * @param aPluginName name of the plugin |
|
100 */ |
|
101 IMPORT_C void SelectPluginL(const TDesC& aPluginName); |
|
102 |
|
103 /** |
|
104 * Select a plugin based on the URI and data type of the media given. |
|
105 * |
|
106 * @since S60 3.2.3 |
|
107 * @param aUri URI of the media |
|
108 * @param aDataType Mime type of the media. KNullDesC8 if not to be |
|
109 * used for selection. |
|
110 * @leave KErrArgument Invalid URI |
|
111 */ |
|
112 IMPORT_C virtual void SelectPluginL( |
|
113 const TDesC& aUri, |
|
114 const TDesC8& aDataType); |
|
115 |
|
116 /** |
|
117 * Select a plugin based on file handle for the given media. |
|
118 * |
|
119 * @since S60 3.2.3 |
|
120 * @param aFile a file handle to the media |
|
121 */ |
|
122 IMPORT_C virtual void SelectPluginL(const RFile& aFile); |
|
123 |
|
124 /** |
|
125 * Select a plugin based on the plugin type. |
|
126 * |
|
127 * @since S60 3.2.3 |
|
128 * @param aPluginType plugin type for the appropriate plugin to be used. |
|
129 * The representation for each bit is to be defined by each plugin |
|
130 * interface. |
|
131 */ |
|
132 IMPORT_C virtual void SelectPluginL(TInt aPluginType); |
|
133 |
|
134 /** |
|
135 * Indicates that this plugin is used by a client. Increments the reference |
|
136 * count for the plugin. |
|
137 * |
|
138 * @since S60 3.2.3 |
|
139 * @param aPluginUid plugin UID |
|
140 */ |
|
141 IMPORT_C void UsePlugin(const TUid& aPluginUid); |
|
142 |
|
143 /** |
|
144 * Indicates that this plugin is no longer used by a client. Plugins are |
|
145 * reference counted and this call may result in the plugin being unloaded. |
|
146 * |
|
147 * @since S60 3.2.3 |
|
148 * @param aPluginUid plugin UID |
|
149 * @return ETrue if the plugin is unloaded / EFalse if it is not. |
|
150 */ |
|
151 IMPORT_C TBool ReleasePlugin(const TUid& aPluginUid); |
|
152 |
|
153 /** |
|
154 * Retrieves the current selection criteria. |
|
155 * |
|
156 * @since S60 3.2.3 |
|
157 * @param aPluginSelection OUT parameter. the selection choice as defined |
|
158 * by TPluginSelection |
|
159 * @param aPluginType OUT parameter. plugin type to be used for selection |
|
160 * @param aPluginUid OUT parameter. UID of the plugin to be used for selection. |
|
161 * KNullUid is a possible return value if none is explicitly selected. |
|
162 * @param aDataType OUT parameter. The data type to be used for selection. |
|
163 * KNullDesC8 if none is specified. CMPXPluginHandlerBase is |
|
164 * responsible for the memory management of this parameter. |
|
165 * @param aScheme OUT parameter. The scheme to be used for selection. |
|
166 * KNullDesC8 if none is specified. CMPXPluginHandlerBase is |
|
167 * responsible for the memory management of this parameter. |
|
168 * @param aExtension OUT parameter. The extension to be used for selection. |
|
169 * KNullDesC8 if none is specified. CMPXPluginHandlerBase is |
|
170 * responsible for the memory management of this parameter. |
|
171 */ |
|
172 IMPORT_C virtual void GetSelectionCriteria( |
|
173 TPluginSelection& aPluginSelection, |
|
174 TInt& aPluginType, |
|
175 TUid& aPluginUid, |
|
176 TPtrC8& aDataType, |
|
177 TPtrC8& aScheme, |
|
178 TPtrC8& aExtension); |
|
179 |
|
180 /** |
|
181 * Clear selection criteria parameters. |
|
182 * |
|
183 * @since S60 3.2.3 |
|
184 */ |
|
185 IMPORT_C virtual void ClearSelectionCriteria(); |
|
186 |
|
187 #ifdef SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API |
|
188 /** |
|
189 * Select a plugin based on file handle for the given media. |
|
190 * |
|
191 * @since S60 3.2.3 |
|
192 * @param aFile a 64 bit file handle to the media |
|
193 */ |
|
194 IMPORT_C virtual void SelectPlugin64L(const RFile64& aFile); |
|
195 #endif // SYMBIAN_ENABLE_64_BIT_FILE_SERVER_API |
|
196 |
|
197 protected: |
|
198 |
|
199 /** |
|
200 * Resolves a plugin based on properties (iDataType, iExt and iScheme) and |
|
201 * selection criteria. When a plugin is found, information about the plugin |
|
202 * is returned through parameters. |
|
203 * |
|
204 * @since S60 3.2.3 |
|
205 * @param aPluginUid This is an OUT parameter. The UID of the matching plugin |
|
206 * @param aIndex This is an OUT parameter. The index for the plugin info, plugin |
|
207 * UID, and plugin types array for the matching plugin |
|
208 * @param aDisplayName This is an OUT parameter. The display name for the matching |
|
209 * plugin. CMPXPluginHandlerBase is responsible for the memory management |
|
210 * of this parameter. |
|
211 * @param aPluginType This is an OUT parameter. The plugin type for the matching |
|
212 * plugin |
|
213 * @leave KErrNotSupported Index is not found |
|
214 */ |
|
215 IMPORT_C virtual void DoResolvePluginL( |
|
216 TUid& aPluginUid, |
|
217 TInt& aIndex, |
|
218 TPtrC& aDisplayName, |
|
219 TInt& aPluginType); |
|
220 |
|
221 /** |
|
222 * From MMPXPluginMonitorObserver. This is invoked by CMPXPluginMonitor when |
|
223 * there is a change in the plugins for the designated plugin interface in |
|
224 * the system. |
|
225 * |
|
226 * @since S60 3.2.3 |
|
227 */ |
|
228 IMPORT_C virtual void PluginsChangedL(); |
|
229 |
|
230 /** |
|
231 * From MMPXPluginMonitorObserver. |
|
232 * |
|
233 * @since S60 3.2.3 |
|
234 * @see MMPXPluginMonitorObserver |
|
235 */ |
|
236 IMPORT_C virtual void HandlePluginUnload(const TUid& aPluginUid); |
|
237 |
|
238 /** |
|
239 * Resolves a plugin. To be implemented by the child class. This is invoked |
|
240 * whenever a client selects a plugin and whenever CMPXPluginMonitor notifies |
|
241 * that there is a change in the plugins for the designated plugin interface |
|
242 * in the system. |
|
243 * |
|
244 * A typical implementation for this method is to invoke DoResolvePluginL |
|
245 * and instantiate a plugin using the plugin UID returned from DoResolvePluginL. |
|
246 * |
|
247 * NOTE: this method is not pure virtual because currently the playlist |
|
248 * recognizer instantiates this class as opposed to the derived handler. |
|
249 * This should be fixed and both ResolvePluginL and UnloadPlugin should be |
|
250 * made pure virtuals. |
|
251 * |
|
252 * @since S60 3.2.3 |
|
253 */ |
|
254 IMPORT_C virtual void ResolvePluginL(); |
|
255 |
|
256 /** |
|
257 * Checks if the specified plugin is loaded. |
|
258 * |
|
259 * @since S60 3.2.3 |
|
260 * @param aPluginUid identifies the plugin |
|
261 * @return ETrue if the plugin is loaded, EFalse otherwise |
|
262 */ |
|
263 IMPORT_C virtual TBool IsPluginLoaded(const TUid& aPluginUid); |
|
264 |
|
265 /** |
|
266 * Request to the derived class to load a specified plugin. |
|
267 * |
|
268 * @since S60 3.2.3 |
|
269 * @param aPluginUid identifies the plugin |
|
270 */ |
|
271 IMPORT_C virtual void LoadPluginL(const TUid& aPluginUid); |
|
272 |
|
273 /** |
|
274 * Request to the derived class to unload a specified plugin. |
|
275 * |
|
276 * @since S60 3.2.3 |
|
277 * @param aPluginUid identifies the plugin |
|
278 */ |
|
279 IMPORT_C virtual void UnloadPlugin(const TUid& aPluginUid); |
|
280 |
|
281 /** |
|
282 * Constructs the plugins info class. |
|
283 * Can be overwritten by subclasses to construct specialized instances of the plugin info. |
|
284 * Default implementation constructs a CMPXPluginInfo class. |
|
285 * |
|
286 * @since S60 3.2.3 |
|
287 * @param aData implementation data |
|
288 */ |
|
289 IMPORT_C virtual CMPXPluginInfo* ConstructPluginInfoLC( const CImplementationInformation& aData ); |
|
290 |
|
291 #ifdef _DEBUG |
|
292 |
|
293 /** |
|
294 * Prints all plugin info entries to the debug log. |
|
295 * |
|
296 * @since S60 3.2.3 |
|
297 */ |
|
298 void PrintPluginInfo(); |
|
299 |
|
300 #endif |
|
301 |
|
302 public: |
|
303 |
|
304 /** |
|
305 * Returns display name for plugin with the given type. |
|
306 * |
|
307 * @since S60 3.2.3 |
|
308 * @param aType plugin type. |
|
309 * @return plugin name. KNullDesC returned if not found. |
|
310 */ |
|
311 IMPORT_C const TDesC& PluginName(TInt aPluginType) const; |
|
312 |
|
313 /** |
|
314 * Returns display name for plugin with the given uid. |
|
315 * |
|
316 * @since S60 3.2.3 |
|
317 * @param aUid plugin id |
|
318 * @return plugin name. KNullDesC returned if not found. |
|
319 */ |
|
320 IMPORT_C const TDesC& PluginName(const TUid& aUid) const; |
|
321 |
|
322 /** |
|
323 * Returns a list of display names for the plugins. |
|
324 * |
|
325 * @since S60 3.2.3 |
|
326 * @return an array of display names. Client is responsible |
|
327 * for the memory management of this array and its |
|
328 * items. |
|
329 */ |
|
330 IMPORT_C CDesCArray* PluginNamesL(); |
|
331 |
|
332 /** |
|
333 * Return a list of mime types supported by plugins. |
|
334 * |
|
335 * @since S60 3.2.3 |
|
336 * @return an array of mime types. Client is responsible |
|
337 * for the memory management of this array and its |
|
338 * items. |
|
339 */ |
|
340 IMPORT_C CDesCArray* SupportedMimeTypesL(); |
|
341 |
|
342 /** |
|
343 * Return a list of file extensions supported by plugins. |
|
344 * |
|
345 * @since S60 3.2.3 |
|
346 * @return an array of extensions. Client is responsible |
|
347 * for the memory management of this array and its |
|
348 * items. |
|
349 */ |
|
350 IMPORT_C CDesCArray* SupportedExtensionsL(); |
|
351 |
|
352 /** |
|
353 * Return a list of schemas supported by plugins. |
|
354 * |
|
355 * @since S60 3.2.3 |
|
356 * @return an array of schemas. Client is responsible for |
|
357 * the memory management of this array and its |
|
358 * items. |
|
359 */ |
|
360 IMPORT_C CDesCArray* SupportedSchemasL(); |
|
361 |
|
362 /** |
|
363 * Return a list of mime types supported by a plugin. |
|
364 * |
|
365 * @since S60 3.2.3 |
|
366 * @param aUid plugin id |
|
367 * @return an array of mime types. Client is responsible |
|
368 * for the memory management of this array and its |
|
369 * items. |
|
370 */ |
|
371 IMPORT_C CDesCArray* SupportedMimeTypesL(const TUid& aUid); |
|
372 |
|
373 /** |
|
374 * Return a list of file extensions supported by a plugin. |
|
375 * |
|
376 * @since S60 3.2.3 |
|
377 * @param aUid plugin id |
|
378 * @return an array of extensions. Client is responsible |
|
379 * for the memory management of this array and its |
|
380 * items. |
|
381 */ |
|
382 IMPORT_C CDesCArray* SupportedExtensionsL(const TUid& aUid); |
|
383 |
|
384 /** |
|
385 * Get plugin type for a given implementation UID. |
|
386 * |
|
387 * @since S60 3.2.3 |
|
388 * @param aUid plugin's implementation Uid |
|
389 * @return plugin's type Uid, or KNullUid if not found |
|
390 */ |
|
391 IMPORT_C TUid PluginType( const TUid& aUid ) const; |
|
392 |
|
393 /** |
|
394 * Get supported app uid for a given implementation UID |
|
395 * |
|
396 * @param aUid plugin's implementation Uid |
|
397 * @return plugin's supported app Uid, or KNullUid if not found |
|
398 */ |
|
399 IMPORT_C TUid SupportedAppUid( const TUid& aUid ) const; |
|
400 |
|
401 /** |
|
402 * Get plugin flag for a given implementation UID. |
|
403 * |
|
404 * @since S60 3.2.3 |
|
405 * @param aUid plugin's implementation Uid |
|
406 * @return Plugin's flag, or leave with KErrNotFound if not found |
|
407 * @leave KErrNotFound Uid is not found |
|
408 */ |
|
409 IMPORT_C TUint PluginFlagsL( const TUid& aUid ) const; |
|
410 |
|
411 /** |
|
412 * Get currently available plug-in types. |
|
413 * |
|
414 * @since S60 3.2.3 |
|
415 * @param aType contains plugins types |
|
416 */ |
|
417 IMPORT_C void GetPluginTypes(RArray<TInt>& aTypes) const; |
|
418 |
|
419 /** |
|
420 * Get currently available plug-in UIDs. |
|
421 * |
|
422 * @since S60 3.2.3 |
|
423 * @param aUids contains plugin uids |
|
424 */ |
|
425 IMPORT_C void GetPluginUids(RArray<TUid>& aUids) const; |
|
426 |
|
427 /** |
|
428 * All the UIDs of the plug-ins in the system of a specific type. |
|
429 * |
|
430 * @since S60 3.2.3 |
|
431 * @param aPlugins OUT parameter. Array of UIDs of all plugins of type |
|
432 * aPluginType. Client is responsible for the memory |
|
433 * management of this RArray. |
|
434 * @param aPluginType IN parameter. Plugin type |
|
435 */ |
|
436 IMPORT_C void GetPluginUidsL(RArray<TUid>& aPlugins, |
|
437 TInt aPluginType) const; |
|
438 |
|
439 /** |
|
440 * Returns the UID of the plugin with the specified display name. |
|
441 * |
|
442 * @since S60 3.2.3 |
|
443 * @param aPluginName a plugin's display name |
|
444 * @return UID of the plugin. KNullUid is returned if there is no |
|
445 * plugin by that name. |
|
446 */ |
|
447 IMPORT_C TUid PluginUid(const TDesC& aPluginName) const; |
|
448 |
|
449 /** |
|
450 * Returns the index of the specified plugin. |
|
451 * |
|
452 * @param aPluginUid UID of the plugin to search for |
|
453 * @return index of the specified plugin in CMPXPluginMonitor's 3 |
|
454 * arrays, iPluginsInfo, iPluginUids, and iPluginTypes. |
|
455 * KErrNotFound, if no matching object can be found. |
|
456 */ |
|
457 IMPORT_C TInt IndexOf(const TUid& aPluginUid) const; |
|
458 |
|
459 /** |
|
460 * Create a list of plugins. |
|
461 * |
|
462 * @since S60 3.2.3 |
|
463 */ |
|
464 IMPORT_C void CreatePluginListL(); |
|
465 |
|
466 /** |
|
467 * Check if the plugin supports the array of uids. |
|
468 * |
|
469 * @since S60 3.2.3 |
|
470 * @param aPluginId plugin id |
|
471 * @param aUids contains plugin uids |
|
472 * @return ETrue if plugin supports all uids |
|
473 */ |
|
474 IMPORT_C TBool SupportUids(const TUid& aPluginId, |
|
475 const TArray<TUid>& aUids) const; |
|
476 |
|
477 /** |
|
478 * Find a plugin with matches the array of uids the best. |
|
479 * |
|
480 * @since S60 3.2.3 |
|
481 * @param aUids contains plugin uids |
|
482 * @return Implementation id of collection plugin, |
|
483 * KNullUidValue will be returned if no plugin found |
|
484 */ |
|
485 IMPORT_C TUid FindPlugin(const TArray<TUid>& aUids) const; |
|
486 |
|
487 protected: |
|
488 MMPXPluginHandlerObserver& iObserver; // observer |
|
489 TUid iInterfaceUid; // plugin interface Uid |
|
490 CMPXPluginMonitor* iPluginMonitor; |
|
491 RPointerArray<CMPXPluginInfo> iPluginInfoArray; // Ordered by priority |
|
492 TBool iOwnedPluginMonitor; |
|
493 |
|
494 // |
|
495 // Selection parameters |
|
496 // |
|
497 TPluginSelection iSelection; |
|
498 TInt iSelectedType; |
|
499 TUid iSelectedUid; |
|
500 |
|
501 // |
|
502 // Resolution parameters |
|
503 // |
|
504 HBufC8* iDataType; |
|
505 HBufC8* iScheme; |
|
506 HBufC8* iExt; |
|
507 }; |
|
508 |
|
509 #endif // CMPXPLUGINHANDLERBASE_H |