1 /* |
|
2 * Copyright (c) 2003-2005 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 the License "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: Declares an API for the consumer applications to access the |
|
15 * Language Interworking Framework. |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 |
|
23 |
|
24 |
|
25 #ifndef LIW_SERVICE_HANDLER_H |
|
26 #define LIW_SERVICE_HANDLER_H |
|
27 |
|
28 // INCLUDES |
|
29 #include <barsread.h> |
|
30 #include <liwcommon.h> |
|
31 #include <e32capability.h> |
|
32 |
|
33 // CONSTANTS |
|
34 |
|
35 // MACROS |
|
36 |
|
37 // FUNCTION PROTOTYPES |
|
38 |
|
39 // FORWARD DECLARATIONS |
|
40 class CLiwServiceHandlerImpl; |
|
41 |
|
42 class CRTSecMgrScriptSession; |
|
43 |
|
44 |
|
45 enum TLiwLoadStatus |
|
46 { |
|
47 KLiwUnknown = -5, |
|
48 KLiwMetaDataInvalidFormat, //-4 |
|
49 KLiwInvalidVersionSpecification, //-3 |
|
50 KLiwVersionOutOfRange, //-2 |
|
51 KLiwSecurityAccessCheckFailed, //-1 |
|
52 KLiwServiceLoadSuccess, //0 |
|
53 KLiwServiceAlreadyLoaded //1 |
|
54 |
|
55 //..Other possible error codes |
|
56 }; |
|
57 |
|
58 |
|
59 // CLASS DECLARATION |
|
60 |
|
61 /** |
|
62 * CLiwServiceHandler is the main class of the Language Interworking |
|
63 * Framework. The Service Handler implements support for dynamically |
|
64 * loadable service providers which offer services to consumer applications. |
|
65 * The Service Handler maps consumers and service providers together via |
|
66 * interests and data agreements and hides the consumers from the providers. |
|
67 * |
|
68 * SERVICE is any command or functionality offered by a provider to |
|
69 * consumer. The service includes typically menu item UI elements, |
|
70 * but it can also just an engine type of command which executes specific |
|
71 * functionality and reports status back to the consumer. |
|
72 * |
|
73 * CONSUMER application accesses interesting services offered by |
|
74 * service provider(s). The consumer uses only those services in which |
|
75 * it is interested in. The interest is expressed using a set of criteria |
|
76 * items. |
|
77 * |
|
78 * INTEREST is a list of criteria items. |
|
79 * |
|
80 * CRITERIA consists of set of attributes which guide the LIW Framework to use |
|
81 * only those providers in which the consumer is interested in. |
|
82 * The criteria consists of following attributes: |
|
83 * - Criteria UID (we can allocate pre-defined criteria items). |
|
84 * - Service command UID (we can allocate pre-defined commands). |
|
85 * - Content MIME type (string). |
|
86 * - Additional options (variant data type just in case). |
|
87 * |
|
88 * PROVIDER produces those services for a consumer that match the given criteria |
|
89 * specified by the consumer. A provider can offer menu items and their command |
|
90 * handling logic to the consumer applications. A provider can also offer base |
|
91 * services that don't require any UI elements. |
|
92 * |
|
93 * DATA AGREEMENT is an agreement between consumer and provider about parameters |
|
94 * needed to be passed in a use case. |
|
95 * |
|
96 * @lib ServiceHandler.lib |
|
97 * @since Series 60 2.6 |
|
98 */ |
|
99 NONSHARABLE_CLASS(CLiwServiceHandler) : public CBase |
|
100 { |
|
101 public: // Construction & destruction |
|
102 |
|
103 /** |
|
104 * Constructs a Service Handler instance. |
|
105 */ |
|
106 IMPORT_C static CLiwServiceHandler* NewL(); |
|
107 |
|
108 /** |
|
109 * Constructs a Service Handler instance. |
|
110 */ |
|
111 IMPORT_C static CLiwServiceHandler* NewLC(); |
|
112 |
|
113 /** |
|
114 * Destructor. |
|
115 */ |
|
116 IMPORT_C virtual ~CLiwServiceHandler(); |
|
117 |
|
118 public: // Management |
|
119 |
|
120 /** |
|
121 * Resets the Service Handler, discards existing interest and unloads |
|
122 * corresponding service providers. |
|
123 */ |
|
124 IMPORT_C void Reset(); |
|
125 |
|
126 /** |
|
127 * Returns the amount of providers that fulfil the given criteria. |
|
128 * |
|
129 * @param aCriteria Criteria to match. |
|
130 * @return Number of providers matching the criteria. |
|
131 */ |
|
132 IMPORT_C TInt NbrOfProviders(const CLiwCriteriaItem* aCriteria); |
|
133 |
|
134 public: // Interest handling |
|
135 |
|
136 /** |
|
137 * Adds the given interest to the Service Handler from a resource and updates |
|
138 * possibly existing old interest. Corresponding service providers are loaded. |
|
139 * If a provider leaves during initialization, it is trapped by the Service Handler. |
|
140 * |
|
141 * @param aInterestResourceId ID of the resource containing criteria items. |
|
142 * @leave KErrNotSupported CCoeEnv is not accessible. |
|
143 * @see Reset |
|
144 */ |
|
145 IMPORT_C void AttachL(TInt aInterestResourceId); |
|
146 |
|
147 /** |
|
148 * Adds given interest to the Service Handler from an array of criteria items. |
|
149 * If a provider leaves during initialization, it is trapped by the Service Handler. |
|
150 * |
|
151 * @param aInterest Array of criteria items. Ownership is not transferred. |
|
152 */ |
|
153 IMPORT_C TInt AttachL(const RCriteriaArray& aInterest); |
|
154 |
|
155 /** |
|
156 * Gets the currently valid interest in use by the Service Handler. |
|
157 * |
|
158 * @param aInterest An array of returned criteria items, may be empty. |
|
159 * Ownership is not transferred, i.e. the objects in the |
|
160 * array must not be deleted. |
|
161 */ |
|
162 IMPORT_C void GetInterest(RCriteriaArray& aInterest); |
|
163 |
|
164 /** |
|
165 * Removes given interest from the Service Handler. Corresponding service |
|
166 * providers are unloaded. |
|
167 * |
|
168 * @param aInterest Array of returned criteria items, may be empty. |
|
169 */ |
|
170 IMPORT_C void DetachL(const RCriteriaArray& aInterest); |
|
171 |
|
172 /** |
|
173 * Removes given interest from the Service Handler. Corresponding service |
|
174 * providers are unloaded. |
|
175 * |
|
176 * @param aInterestResourceId ID of the resource containing criteria items. |
|
177 * @leave KErrNotSupported CCoeEnv is not accessible. |
|
178 */ |
|
179 IMPORT_C void DetachL(TInt aInterestResourceId); |
|
180 |
|
181 /** |
|
182 * Returns criteria by ID. |
|
183 * |
|
184 * @param aId Criteria ID. |
|
185 * @return Criteria item pointer matching the ID. Ownership is not transferred. |
|
186 */ |
|
187 IMPORT_C const CLiwCriteriaItem* GetCriteria(TInt aId); |
|
188 |
|
189 /** |
|
190 * Returns an empty instance of CLiwGenericParamList class. It can be |
|
191 * used for example as an input parameter list for the Service Handler's |
|
192 * API methods. This is just a convenience method and doesn't have |
|
193 * to be used. If consumer wants to create input list by itself |
|
194 * it is ok. If this method is used, the Service Handler takes care |
|
195 * of deleting returned generic parameter list. |
|
196 * |
|
197 * @return An empty instance of CLiwGenericParameter list. |
|
198 */ |
|
199 IMPORT_C CLiwGenericParamList& InParamListL(); |
|
200 |
|
201 /** |
|
202 * Returns an empty instance of CLiwGenericParamList class. The instance can be |
|
203 * used for example as an output parameter list for Service Handler |
|
204 * API methods. This is just a convenience method and doesn't have |
|
205 * to be used. If consumer wants to create output list by itself |
|
206 * it is ok. If this method is used, Service Handler takes care |
|
207 * of deleting returned generic parameter list. |
|
208 * |
|
209 * @return An empty instance of CLiwGenericParameter list. |
|
210 */ |
|
211 IMPORT_C CLiwGenericParamList& OutParamListL(); |
|
212 |
|
213 public: // Menu handling |
|
214 |
|
215 /** |
|
216 * Initialises menu pane with service commands from a provider. |
|
217 * This method must be called upon DynInitMenuPaneL of consumer |
|
218 * application in order to let the provider to hook its menu items. |
|
219 * |
|
220 * @param aMenuPane Handle of the menu pane to initialise. |
|
221 * @param aMenuResourceId The menu to be attached. |
|
222 * @param aBaseMenuCmdId Base ID for the Service Handler to generate |
|
223 * menu IDs for placeholders. |
|
224 * @param aInParamList Input parameter list for provider's parameters checking. |
|
225 * @leave KErrNotSupported CCoeEnv is not accessible. |
|
226 * @leave KErrOverflow Consumer application has too many LIW placeholders in its menu. |
|
227 * Currently, maximum 16 is supported. |
|
228 */ |
|
229 IMPORT_C void InitializeMenuPaneL( |
|
230 CEikMenuPane& aMenuPane, |
|
231 TInt aMenuResourceId, |
|
232 TInt aBaseMenuCmdId, |
|
233 const CLiwGenericParamList& aInParamList); |
|
234 /** |
|
235 * Initialises menu pane with service commands from a provider. |
|
236 * This method must be called upon DynInitMenuPaneL of consumer |
|
237 * application in order to let the provider to hook its menu items. |
|
238 * In normal circumstances, the other variant of this method should be used. |
|
239 * |
|
240 * @param aMenuPane Handle of the menu pane to initialise. |
|
241 * @param aMenuResourceId The menu to be attached. |
|
242 * @param aBaseMenuCmdId Base ID for the Service Handler to generate |
|
243 * menu IDs for placeholders. |
|
244 * @param aInParamList Input parameter list for provider's parameters checking. |
|
245 * @param aUseSubmenuTextsIfAvailable If the provider has specified alternative submenu |
|
246 * texts for its menu items, those can be taken into use if this |
|
247 * parameter is set to ETrue. This should be used only for manually |
|
248 * created submenus. If using LIW_CASCADE_ID or |
|
249 * LIW_INTELLIGENT_CASCADE_ID, the LIW framework can automatically |
|
250 * decide whether to use the submenu texts or not, and this parameter |
|
251 * has no effect. |
|
252 * @leave KErrNotSupported CCoeEnv is not accessible. |
|
253 * @leave KErrOverflow Consumer application has too many LIW placeholders in its menu. |
|
254 * Currently, maximum 16 is supported. |
|
255 */ |
|
256 IMPORT_C void InitializeMenuPaneL( |
|
257 CEikMenuPane& aMenuPane, |
|
258 TInt aMenuResourceId, |
|
259 TInt aBaseMenuCmdId, |
|
260 const CLiwGenericParamList& aInParamList, |
|
261 TBool aUseSubmenuTextsIfAvailable); |
|
262 |
|
263 /** |
|
264 * Returns the service command ID associated to the menu command. If found, it means |
|
265 * that there is a provider which can handle the menu command. Thus the command |
|
266 * handling needs to be routed to the provider via ExecuteMenuCmdL. |
|
267 * |
|
268 * @param aMenuCmdId Menu command ID to be mapped to service cmd, |
|
269 * KNullServiceCmd is returned if no service command exists. |
|
270 * @return Service command ID, KLiwCmdNone if no ID is found. |
|
271 * @see ExecuteMenuCmdL |
|
272 */ |
|
273 IMPORT_C TInt ServiceCmdByMenuCmd(TInt aMenuCmdId) const; |
|
274 |
|
275 /** |
|
276 * Tells the provider to execute a menu command invoked by the consumer. |
|
277 * Not supported if calling outside UI framework. Use ServiceCmdByMenuCmd to |
|
278 * check if there is any provider for the menu command. |
|
279 * |
|
280 * @param aMenuCmdId The menu command to be executed. |
|
281 * @param aInParamList Input data parameters, can be an empty list. |
|
282 * @param aOutParamList Output data parameters, can be an empty list. |
|
283 * @param aCmdOptions Options for the command, see TLiwServiceCmdOptions in LiwCommon.hrh. |
|
284 * @param aCallback Callback for asynchronous command handling, parameter checking, etc. |
|
285 * @leave KErrArgument Callback is missing when required. |
|
286 * @leave KErrNotSupported No cmd matches given menu command or CCoeEnv is not accessible. |
|
287 * @see ServiceCmdByMenuCmd |
|
288 */ |
|
289 IMPORT_C void ExecuteMenuCmdL( |
|
290 TInt aMenuCmdId, |
|
291 const CLiwGenericParamList& aInParamList, |
|
292 CLiwGenericParamList& aOutParamList, |
|
293 TUint aCmdOptions = 0, |
|
294 MLiwNotifyCallback* aCallback= NULL); |
|
295 |
|
296 /** |
|
297 * Attach menu related criteria items to the given menu. |
|
298 * If a provider leaves during initialization, it is trapped by the Service Handler. |
|
299 * |
|
300 * @param aMenuResourceId Menu to be attached. |
|
301 * @param aInterestResourceId Resource id for the interest list. |
|
302 * @leave KErrNotSupported CCoeEnv is not accessible. |
|
303 */ |
|
304 IMPORT_C void AttachMenuL(TInt aMenuResourceId, TInt aInterestResourceId); |
|
305 |
|
306 /** |
|
307 * Attach menu related criteria items to the given menu. |
|
308 * If a provider leaves during initialization, it is trapped by the Service Handler. |
|
309 * |
|
310 * @param aMenuResourceId Menu to be attached. |
|
311 * @param aReader Resource reader for the interest list. |
|
312 * @leave KErrNotSupported CCoeEnv is not accessible. |
|
313 */ |
|
314 IMPORT_C void AttachMenuL(TInt aMenuResourceId, TResourceReader& aReader); |
|
315 /** |
|
316 * Attach menu related criteria items to the given menu. |
|
317 * |
|
318 * @param aMenuResourceId Menu to be attached. |
|
319 * @param aInterest Array of criteria items. Ownership is not transferred. |
|
320 * @leave KErrNotSupported CCoeEnv is not accessible. |
|
321 */ |
|
322 IMPORT_C void AttachMenuL(TInt aMenuResourceId, const RCriteriaArray& aInterest); |
|
323 |
|
324 /** |
|
325 * Attach menu related criteria items to the given menu. |
|
326 * |
|
327 * @param aMenuEntries List of menu command ids, ids not related to interests may be set to 0. |
|
328 * @param aMenuResourceId Menu to be attached. |
|
329 * @param aInterest Interest list. |
|
330 */ |
|
331 IMPORT_C void AttachMenuL(RArray<TInt>& aMenuEntries, TInt aMenuResourceId, RCriteriaArray& aInterest); |
|
332 |
|
333 /** |
|
334 * Detach menu related criteria items from the given menu. |
|
335 * In following cases this method just returns without doing anything: |
|
336 * 1. If interest resource id is non-zero and CCoeEnv is not accessible. |
|
337 * 2. If interest resource id is non-zero and there occurs an error when reading |
|
338 * the interest (e.g. not enough memory). |
|
339 * |
|
340 * @param aMenuResourceId Menu to be detached. |
|
341 * @param aInterestResourceId Resource id for the interest list. If NULL, all |
|
342 * criteria items are detached from the given menu. |
|
343 */ |
|
344 IMPORT_C void DetachMenu(TInt aMenuResourceId, TInt aInterestResourceId); |
|
345 |
|
346 /** |
|
347 * Checks if there are menu providers attached to given menu id. Consumer |
|
348 * application can use this information to decide whether a sub menu |
|
349 * containing only LIW items should be hidden or not. |
|
350 * |
|
351 * @param aSubMenuId The menu id to be checked. |
|
352 * @return ETrue if there isn't any menu providers attached to this menu. |
|
353 * EFalse otherwise. |
|
354 */ |
|
355 IMPORT_C TBool IsSubMenuEmpty(TInt aSubMenuId); |
|
356 |
|
357 /** |
|
358 * Returns boolean value indicating whether the given menu contains |
|
359 * currently attached placeholders. |
|
360 * |
|
361 * @param aMenuResourceId Resource id of the menu to be queried. |
|
362 * @return ETrue if aMenuResource contains currently attached placeholders. |
|
363 * EFalse otherwise. |
|
364 */ |
|
365 IMPORT_C TBool IsLiwMenu(TInt aMenuResourceId); |
|
366 |
|
367 /** |
|
368 * Handles LIW submenus. This method should be called from consumer application's |
|
369 * DynInitMenuPaneL. |
|
370 * |
|
371 * @param aPane Menu pane to be handled. |
|
372 * @return ETrue if aPane was an LIW submenu and it was handled. |
|
373 * Consumer's DynInitMenuPaneL pane may now return. |
|
374 * EFalse if aPane was not an LIW submenu and DynInitMenuPaneL should |
|
375 * continue normally. |
|
376 */ |
|
377 IMPORT_C TBool HandleSubmenuL(CEikMenuPane& aPane); |
|
378 |
|
379 /** |
|
380 * CEikMenuPane uses this method to inform AIF framework that a menu is launched. |
|
381 * This method does not need to be called by any other component. |
|
382 * |
|
383 * @since Series 60 3.0 |
|
384 */ |
|
385 IMPORT_C static void ReportMenuLaunch(); |
|
386 |
|
387 public: // Generic Service Command handling |
|
388 |
|
389 /** |
|
390 * Executes a service command for all providers. Otherwise similar to ExecuteMenuCmdL. |
|
391 * |
|
392 * @param aCmdId The command to be executed. |
|
393 * @param aInParamList Input data parameters, can be an empty list. |
|
394 * @param aOutParamList Output data parameters, can be an empty list. |
|
395 * @param aCmdOptions Options for the command, see TLiwServiceCmdOptions in LiwCommon.hrh. |
|
396 * @param aCallback Callback for asynchronous command handling, parameter checking, etc. |
|
397 * @leave KErrArgument Callback is missing when required. |
|
398 * @leave KErrNotSupported No provider supports the service. |
|
399 */ |
|
400 IMPORT_C void ExecuteServiceCmdL( |
|
401 const TInt& aCmdId, |
|
402 const CLiwGenericParamList& aInParamList, |
|
403 CLiwGenericParamList& aOutParamList, |
|
404 TUint aCmdOptions = 0, |
|
405 MLiwNotifyCallback* aCallback = 0); |
|
406 |
|
407 /** |
|
408 * Executes a service command. |
|
409 * |
|
410 * @param aCmd The criteria item containing the service command and content type |
|
411 * @param aInParamList Input data parameters, can be an empty list. |
|
412 * @param aOutParamList Output data parameters, can be an empty list. |
|
413 * @param aCmdOptions Options for the command, see TLiwServiceCmdOptions in LiwCommon.hrh. |
|
414 * @param aCallback Callback for asynchronous command handling, parameter checking, etc. |
|
415 * @leave KErrArgument Callback is missing when required. |
|
416 * @leave KErrNotSupported No provider supports the service. |
|
417 */ |
|
418 IMPORT_C void ExecuteServiceCmdL( |
|
419 const CLiwCriteriaItem& aCmd, |
|
420 const CLiwGenericParamList& aInParamList, |
|
421 CLiwGenericParamList& aOutParamList, |
|
422 TUint aCmdOptions = 0, |
|
423 MLiwNotifyCallback* aCallback = 0); |
|
424 |
|
425 /** |
|
426 * Gets provider command ID by dynamic command ID. |
|
427 * |
|
428 * @since Series 60 3.0 |
|
429 * @param aMenuCmdId The consumer's menu command ID generated by LIW framework. |
|
430 * This can be get e.g. from consumer's HandleCommandL(). |
|
431 * @return Found provider menu command ID, KErrNotFound if not found. |
|
432 */ |
|
433 IMPORT_C TInt MenuCmdId(TInt aMenuCmdId) const; |
|
434 |
|
435 IMPORT_C TInt AttachL(const RCriteriaArray& aInterest,CRTSecMgrScriptSession& aSecMgrScriptSession); |
|
436 |
|
437 /** |
|
438 * Lists available service implementations |
|
439 * |
|
440 * @param aFilterItem |
|
441 * @param aProviderList |
|
442 * |
|
443 * @return none |
|
444 */ |
|
445 IMPORT_C void QueryImplementationL(RCriteriaArray& aFilterItem, RCriteriaArray& aProviderList); |
|
446 |
|
447 private: |
|
448 void ConstructL(); |
|
449 CLiwServiceHandler(); |
|
450 |
|
451 private: |
|
452 CLiwServiceHandlerImpl* iImpl; |
|
453 }; |
|
454 |
|
455 #endif // LIW_SERVICE_HANDLER_H |
|
456 |
|
457 // END of File |
|