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: Voice command service interfaces |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 #ifndef VCOMMANDAPI_H |
|
21 #define VCOMMANDAPI_H |
|
22 |
|
23 #include <e32def.h> |
|
24 #include <e32cmn.h> |
|
25 #include <s32strm.h> |
|
26 #include <nssvasmrrd.h> // For KNssVASMAXRRDTextLength only |
|
27 |
|
28 /** |
|
29 * Maximal length of the exe arguments string |
|
30 * @todo If longer arguments needed, reengineer the storage scheme. |
|
31 * Currently argument string has to fit into the VAS DB rrdtext column |
|
32 * @see CTagCommandConverter |
|
33 */ |
|
34 const TInt KMaxVCArgumentLength = KNssVASMAXRRDTextLength; |
|
35 |
|
36 class MNssPlayEventHandler; |
|
37 class CStoredVCommand; |
|
38 class MVCService; |
|
39 class CVCommandHandler; |
|
40 class CGulIcon; |
|
41 |
|
42 /** |
|
43 * Container for the voice command folder information. Note that every command can |
|
44 * have its own folder information |
|
45 */ |
|
46 class CVCFolderInfo : public CBase |
|
47 { |
|
48 public: |
|
49 /** |
|
50 * This object does not take an ownership of the passed descriptors, |
|
51 * but makes own copies. |
|
52 * |
|
53 * @param aTitle Folder title. It is shown at the top of the screen, |
|
54 * when the folder is opened in the VCommand application |
|
55 * @param aListedName Version of a title shown when the folder is |
|
56 * is displayed in the list of VCommands in the VCommand app |
|
57 * @param aHelpTopicId Topic to open when help is requested for the |
|
58 * given folder |
|
59 * @param aIconIndex Zero based index of the folder icon in the folder icons mbm file |
|
60 * each index correspods to two images - the actual icon and its mask |
|
61 * @param aIconFile Mbm file where the icons are obtained from. If KNullDesC, |
|
62 * the default icon file is used |
|
63 * |
|
64 */ |
|
65 IMPORT_C static CVCFolderInfo* NewL( const TDesC& aTitle, |
|
66 const TDesC& aListedName, TUint32 aHelpTopicId, TUint aIconIndex, |
|
67 const TDesC& aIconFile = KNullDesC ); |
|
68 |
|
69 /** |
|
70 * Constructs the folder information from stream |
|
71 * @leave KErrNotSupported if the stream data format is unsupported |
|
72 */ |
|
73 IMPORT_C static CVCFolderInfo* NewL( RReadStream& aStream ); |
|
74 |
|
75 /** |
|
76 * Cloning constructor |
|
77 */ |
|
78 IMPORT_C static CVCFolderInfo* NewL( const CVCFolderInfo& aOriginal ); |
|
79 |
|
80 IMPORT_C ~CVCFolderInfo(); |
|
81 |
|
82 /** |
|
83 * Saves the folder information to stream. |
|
84 * Descriptor components are saved as <length><descriptor> pairs, where |
|
85 * <length> is TInt32 and <descriptor> is the default descriptor represetation |
|
86 */ |
|
87 IMPORT_C void ExternalizeL( RWriteStream &aStream ) const; |
|
88 |
|
89 /** |
|
90 * Returns folder title. It is shown at the top of the screen, |
|
91 * when the folder is opened in the VCommand application |
|
92 */ |
|
93 IMPORT_C const TDesC& Title() const; |
|
94 |
|
95 /** |
|
96 * Version of a title shown when the folder is |
|
97 * is displayed in the list of VCommands in the VCommand app |
|
98 */ |
|
99 IMPORT_C const TDesC& ListedName() const; |
|
100 |
|
101 IMPORT_C TUint32 HelpTopicId() const; |
|
102 |
|
103 /** |
|
104 * Creates an icon to represent this folder. Works only if CEikonEnv is available |
|
105 * @return Icon for the folder |
|
106 */ |
|
107 IMPORT_C CGulIcon* IconLC() const; |
|
108 |
|
109 IMPORT_C TBool operator==( const CVCFolderInfo& aFolderInfo ) const; |
|
110 |
|
111 protected: |
|
112 CVCFolderInfo( TUint32 aHelpTopicId, TUint aIconIndex ); |
|
113 // unhiding inherited parameterless constructor |
|
114 CVCFolderInfo() {} |
|
115 |
|
116 /** |
|
117 * Zero based index of the folder icon in the icon file |
|
118 * @see IconFile |
|
119 */ |
|
120 TUint IconIndex() const; |
|
121 |
|
122 /** |
|
123 * Full file name of the file name, where the folder icon is obtained from |
|
124 * Is always no longer, than KMaxFileName |
|
125 * If KNullDesC is returned, the default icon file is used |
|
126 */ |
|
127 TDesC& IconFile() const; |
|
128 |
|
129 private: |
|
130 /** @see NewL */ |
|
131 void ConstructL( const TDesC& aTitle, |
|
132 const TDesC& aListedName, |
|
133 const TDesC& aIconFile ); |
|
134 |
|
135 void ConstructL( RReadStream& aStream ); |
|
136 |
|
137 private: |
|
138 HBufC* iTitle; |
|
139 |
|
140 HBufC* iListedName; |
|
141 |
|
142 HBufC* iIconFile; |
|
143 |
|
144 TUint32 iHelpTopicId; |
|
145 |
|
146 TUint iIconIndex; |
|
147 |
|
148 }; |
|
149 |
|
150 /** |
|
151 * Container for VC app specific "human-visible" parts of the voice command: |
|
152 * tooltip, displayable text, folder, icon, etc |
|
153 */ |
|
154 class CVCCommandUi : public CBase |
|
155 { |
|
156 public: |
|
157 /** |
|
158 * This object does not take an ownership of the passed descriptors, |
|
159 * but makes own copies. |
|
160 * |
|
161 * @param aWrittenText Text to display |
|
162 * @param aTooltip Second line of the text if ant |
|
163 * @param aFolderInfo Folder-related details |
|
164 * @param aModifiable If user can modify the command |
|
165 * @param aConfirmationNeeded If EFalse, when the command is recognized, |
|
166 * it is immediately executed |
|
167 * If ETrue, when the command is recognized, it is played back and |
|
168 * user is asked to confirm the recognition results |
|
169 * @see |
|
170 * @todo Add "see" reference to the recognition-side function that uses the |
|
171 * "confirmation needed information" |
|
172 * @todo aModifiable param is "hanging in the air" and never actually used |
|
173 * Clarify its existence and responsibilities |
|
174 * @param aUserText Optional user-specified shortcut for the command |
|
175 */ |
|
176 IMPORT_C static CVCCommandUi* NewL( const TDesC& aWrittenText, |
|
177 const CVCFolderInfo& aFolderInfo, TBool aModifiable, |
|
178 const TDesC& aTooltip, const TUid& aIconUid, |
|
179 const TDesC& aUserText = KNullDesC, |
|
180 TBool aConfirmationNeeded = ETrue ); |
|
181 |
|
182 /** |
|
183 * Factory function that constructs a CVCCommandUi from the stream |
|
184 * @leave KErrNotSupported if the stream data format is unsupported |
|
185 * e.g. if it has been written by newer implementation |
|
186 */ |
|
187 IMPORT_C static CVCCommandUi* NewL( RReadStream& aStream ); |
|
188 |
|
189 /** |
|
190 * Copy the existing CVCCommandUi |
|
191 */ |
|
192 IMPORT_C static CVCCommandUi* NewL( const CVCCommandUi& aOriginal ); |
|
193 |
|
194 /** Destructor */ |
|
195 IMPORT_C ~CVCCommandUi(); |
|
196 |
|
197 /** |
|
198 * Saves the command to stream. |
|
199 * Descriptor components are saved as <length><descriptor> pairs, where |
|
200 * <length> is TInt32 and <descriptor> is the default descriptor represetation |
|
201 * TBools are saved as TInt32 either |
|
202 */ |
|
203 IMPORT_C void ExternalizeL( RWriteStream &aStream ) const; |
|
204 |
|
205 // Accessor methods |
|
206 |
|
207 /** |
|
208 * @return Unmodifiable written text |
|
209 */ |
|
210 IMPORT_C const TDesC& WrittenText() const; |
|
211 |
|
212 /** |
|
213 * @return Unmodifiable user-specified shortcut for the command |
|
214 * KNullDesC if none |
|
215 */ |
|
216 IMPORT_C const TDesC& UserText() const; |
|
217 |
|
218 /** |
|
219 * @return Unmodifiable folder name |
|
220 */ |
|
221 IMPORT_C const CVCFolderInfo& FolderInfo() const; |
|
222 |
|
223 /** |
|
224 * @return ETrue if the command is modifiable by user |
|
225 * EFalse otherwise |
|
226 */ |
|
227 IMPORT_C TBool Modifiable() const; |
|
228 |
|
229 /** |
|
230 * @return EFalse, if when the command is recognized, |
|
231 * it is immediately executed |
|
232 * ETrue, if when the command is recognized, it is played back and |
|
233 * user is asked to confirm the recognition results |
|
234 * @see |
|
235 * @todo Add "see" reference to the recognition-side function that uses the |
|
236 * "confirmation needed information" |
|
237 **/ |
|
238 IMPORT_C TBool ConfirmationNeeded() const; |
|
239 |
|
240 /** |
|
241 * @return Unmodifiable extra text |
|
242 */ |
|
243 IMPORT_C const TDesC& Tooltip() const; |
|
244 |
|
245 |
|
246 /** |
|
247 * @return global icon id |
|
248 * @todo AVKON-global? What kind of global? |
|
249 */ |
|
250 IMPORT_C const TUid& IconUid() const; |
|
251 |
|
252 /** |
|
253 * Creates the command icon. Takes into account the skin-specifics |
|
254 * Works only if CEikonEnv is available |
|
255 * @return The command icon pushed to the cleanup stack |
|
256 */ |
|
257 IMPORT_C CGulIcon* IconLC() const; |
|
258 |
|
259 IMPORT_C TBool operator==( const CVCCommandUi& aCommandUi ) const; |
|
260 |
|
261 /** |
|
262 * Tells if all non user-changeable parts of aCommandUi are equal to this object's |
|
263 * @return ETrue if equal, EFalse otherwise |
|
264 */ |
|
265 IMPORT_C TBool EqualNonUserChangeableData( const CVCCommandUi& aCommandUi ) const; |
|
266 |
|
267 |
|
268 private: |
|
269 /** |
|
270 * Second-phase constructor |
|
271 * @see NewL for guard conditions |
|
272 */ |
|
273 void ConstructL( const TDesC& aWrittenText, |
|
274 const CVCFolderInfo& aFolderInfo, TBool aModifiable, |
|
275 const TDesC& aTooltip, const TUid& aIconUid, |
|
276 const TDesC& aUserText, TBool aConfirmationNeeded ); |
|
277 |
|
278 void ConstructL( RReadStream& aStream ); |
|
279 |
|
280 private: // Data |
|
281 |
|
282 // Text shown on screen |
|
283 HBufC* iWrittenText; |
|
284 |
|
285 // User-specified alternative command text |
|
286 HBufC* iUserText; |
|
287 |
|
288 // Text shown on screen |
|
289 HBufC* iTooltip; |
|
290 |
|
291 // Folder-related details |
|
292 CVCFolderInfo* iFolderInfo; |
|
293 |
|
294 // Tells if this command is user modifiable |
|
295 TBool iUserCanModify; |
|
296 |
|
297 // Ask user to confirm the recognition result |
|
298 TBool iConfirmationNeeded; |
|
299 |
|
300 // global icon id |
|
301 /** @todo AVKON-global? What kind of global? */ |
|
302 TUid iIconUid; |
|
303 }; |
|
304 |
|
305 /** |
|
306 * Container for the information on how the command should be executed: |
|
307 * 1) app uid OR exe filename; 2) optional command line arguments |
|
308 */ |
|
309 class CVCRunnable : public CBase |
|
310 { |
|
311 public: |
|
312 /** |
|
313 * Factory function |
|
314 * @param aAppUid UID of the application to start. Cannot be KNullUidValue |
|
315 * @param aArguments Command line to pass to the application. This object makes |
|
316 * a copy of the passed string |
|
317 * @leave KErrOverflow if aArguments is longer, than KMaxVCArgumentLength |
|
318 * @leave KErrArgument if aAppUid is KNullUidValue |
|
319 */ |
|
320 IMPORT_C static CVCRunnable* NewL( TUid aAppUid, const TDesC8& aArguments = KNullDesC8 ); |
|
321 |
|
322 /** |
|
323 * Factory function |
|
324 * @param aExeName Exe-file to start. Can be full or partical name according to |
|
325 * the RProcess::Create rules. Cannot be KNullDesC |
|
326 * @param aArguments Command line to pass to the application. This object makes |
|
327 * a copy of the passed string |
|
328 * @leave KErrOverflow if aArguments is longer, than KMaxVCArgumentLength or |
|
329 * aExeName is longer, than KMaxFileName |
|
330 * @leave KErrUndeflow if aExeName is empty |
|
331 */ |
|
332 IMPORT_C static CVCRunnable* NewL( const TDesC& aExeName, |
|
333 const TDesC8& aArguments = KNullDesC8 ); |
|
334 |
|
335 /** |
|
336 * Internalizes the object from stream |
|
337 * @leave KErrNotSupported if the stream data format is unsupported |
|
338 * e.g. if it has been written by newer implementation of CVCommandUi |
|
339 */ |
|
340 IMPORT_C static CVCRunnable* NewL( RReadStream &aStream ); |
|
341 |
|
342 /** |
|
343 * Copy the existing CVRunnable |
|
344 */ |
|
345 IMPORT_C static CVCRunnable* NewL( const CVCRunnable& aOriginal ); |
|
346 |
|
347 |
|
348 /** Destructor */ |
|
349 IMPORT_C ~CVCRunnable(); |
|
350 |
|
351 /** |
|
352 * Run the command. In case of aAppUid specified during the construction |
|
353 * application is started via the RApaLsSession::StartApp, otherwise |
|
354 * via the RProcess::Create |
|
355 * @leave System-wide error code. In particular KErrNotFound if there is |
|
356 * no such app in the system |
|
357 */ |
|
358 IMPORT_C void ExecuteL() const; |
|
359 |
|
360 /** Saves the object to stream */ |
|
361 IMPORT_C void ExternalizeL( RWriteStream &aStream ) const; |
|
362 |
|
363 /** |
|
364 * @return The uid of the application to be started. KNullUid if there is none |
|
365 */ |
|
366 IMPORT_C const TUid Uid() const; |
|
367 |
|
368 /** |
|
369 * @return The filename of the application to be started. KNullDesC if there is none |
|
370 */ |
|
371 IMPORT_C const TDesC& ExeName() const; |
|
372 |
|
373 /** |
|
374 * The arguments to be passed to the application. This object keeps |
|
375 * the ownership of the returned value |
|
376 */ |
|
377 IMPORT_C const TDesC8& Arguments() const; |
|
378 |
|
379 IMPORT_C TBool operator==( const CVCRunnable& aRunnable ) const; |
|
380 |
|
381 private: |
|
382 void ConstructL( TUid aAppUid, const TDesC8& aArguments ); |
|
383 void ConstructL( const TDesC& aExeName, const TDesC8& aArguments ); |
|
384 void ConstructL( RReadStream& aStream ); |
|
385 |
|
386 private: |
|
387 // UID of the application to be run, when the vcommand is recognized |
|
388 // KNullUidValue if none specified |
|
389 TUid iExeUid; |
|
390 |
|
391 // Filename to pass to RProcess::Create or NULL |
|
392 HBufC* iExeName; |
|
393 |
|
394 // Arguments string |
|
395 HBufC8* iArguments; |
|
396 }; |
|
397 |
|
398 /** |
|
399 * The packaged VCommand storable/retriavable to/from VAS |
|
400 */ |
|
401 class CVCommand : public CBase |
|
402 { |
|
403 public: |
|
404 /** |
|
405 * Factory function. Create a const snapshop of exe-ui-vastext collection |
|
406 * @param aText Text to be trained by VAS. Can be of any length, however |
|
407 * only first KNssVasDbTagName characters will be trained by VAS |
|
408 * @see KNssVasDbTagName in nssvasdbkonsts.h |
|
409 * @param aRunnable Executable to be fired when the command is recognized. |
|
410 * VCommand takes the ownership on the aRunnable |
|
411 * @param aUi visible strings to be displayed in VC App. VCommand takes |
|
412 * the ownership on the aUi |
|
413 */ |
|
414 IMPORT_C static CVCommand* NewL( const TDesC& aText, const CVCRunnable& aRunnable, |
|
415 const CVCCommandUi& aUi ); |
|
416 |
|
417 /** |
|
418 * Internalizes the command from stream |
|
419 * @leave KErrNotSupported if the stream data format is unsupported |
|
420 * e.g. if it has been written by newer implementation |
|
421 */ |
|
422 IMPORT_C static CVCommand* NewL( RReadStream &aStream ); |
|
423 |
|
424 /** |
|
425 * Copy the existing CVCommand |
|
426 */ |
|
427 IMPORT_C static CVCommand* NewL( const CVCommand& aOriginal ); |
|
428 |
|
429 /** Destructor */ |
|
430 IMPORT_C ~CVCommand(); |
|
431 |
|
432 /** |
|
433 * Saves the command to stream |
|
434 * Format: <protocol version: int32><SpokenTextLength: int32><SpokenText descriptor> |
|
435 * <runnable><commandui> |
|
436 */ |
|
437 IMPORT_C void ExternalizeL( RWriteStream &aStream ) const; |
|
438 |
|
439 /** |
|
440 * @return the Runnable component of the command |
|
441 */ |
|
442 IMPORT_C const CVCRunnable& Runnable() const; |
|
443 |
|
444 /** |
|
445 * @return the UI-related component of the command |
|
446 */ |
|
447 IMPORT_C const CVCCommandUi& CommandUi() const; |
|
448 |
|
449 /** |
|
450 * @return the text, that user is expected to pronounce |
|
451 * It is different from the CVCommandUi::WrittenText |
|
452 */ |
|
453 IMPORT_C const TDesC& SpokenText() const; |
|
454 |
|
455 /** |
|
456 * @return the user specified text, that user can pronounce to |
|
457 * recognize the command. Is always identical to the |
|
458 * CVCommandUi::UserText() |
|
459 * Can be KNullDesC |
|
460 * |
|
461 * @todo Responsibilities of SpokenText, AlternativeSpokenText, |
|
462 * WrittenText and UserText are mixed. The source of problems |
|
463 * is the fact that WrittenText can really be different from the |
|
464 * default spoken text while User supplied text is always what's |
|
465 * expected to be [alternatively] recognized |
|
466 * A better structuring would be very welcome |
|
467 */ |
|
468 IMPORT_C const TDesC& AlternativeSpokenText() const; |
|
469 |
|
470 /** |
|
471 * Asynchronous |
|
472 * Attempts to play back the text expected to be recognized. |
|
473 * To be playable command has to be added to CVCommandHandler AND |
|
474 * then retrieved back |
|
475 * |
|
476 * @param aHandler CVCommandHandler where the command is stored |
|
477 * @todo Consider storing link to CVCommandHandler within the CVCommand (CStoredVCommand) |
|
478 * Pros: No clumsy aHandler argument for the playback |
|
479 * Pros: No need to remember in which handler the command is stored |
|
480 * and why specifying storage is needed during the playback |
|
481 * Cons: In case of internal link the linked handler should still |
|
482 * exist. It cannot be e.g. destroyed and recreated later even |
|
483 * if the latter one is using the same VAS |
|
484 * |
|
485 * @param aPlayEventHandler Entity that handles the playback callbacks |
|
486 * @see NssVasMPlayEventHandler.h |
|
487 * |
|
488 * @leave KErrBadHandle if the current command has not been retrieved |
|
489 * from CVCommandHandler (i.e. was not trained for recognition) |
|
490 * @leave KErrNotFound if this command cannot be found in aHandler |
|
491 * @leave KErrNotReady @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
492 * EVasUnexpectedRequest |
|
493 * @leave KErrInUse @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
494 * EVasInUse |
|
495 * @leave KErrArgument @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
496 * EVasInvalidParameter |
|
497 * @leave KErrGeneral @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
498 * EVasPlayFailed |
|
499 */ |
|
500 IMPORT_C virtual void PlaySpokenTextL( const CVCommandHandler& aHandler, |
|
501 MNssPlayEventHandler& aPlayEventHandler ) const; |
|
502 |
|
503 /** |
|
504 * Asynchronous |
|
505 * Plays back the user-specified alternative spoken text. |
|
506 * Otherwise is identical to PlaySpokenTextL |
|
507 * @see PlaySpokenTextL |
|
508 * @leave KErrNotFound if this command cannot be found in aHandler of if |
|
509 * it doesn't have a user-specified text |
|
510 */ |
|
511 IMPORT_C virtual void PlayAlternativeSpokenTextL( const CVCommandHandler& aHandler, |
|
512 MNssPlayEventHandler& aPlayEventHandler ) const; |
|
513 |
|
514 /** |
|
515 * Cancels playback of a spoken or alternative spoken text |
|
516 * To be playable command has to be added to CVCommandHandler AND |
|
517 * then retrieved back. After this function neither HandlePlayStarted, |
|
518 * nor HandlePlayComplete will be called |
|
519 * |
|
520 * @param aHandler CVCommandHandler where the command is stored |
|
521 * |
|
522 * @leave KErrBadHandle if the current command has not been retrieved |
|
523 * from CVCommandHandler (i.e. was not trained for recognition) |
|
524 * @leave KErrNotReady if playback has never been started |
|
525 * |
|
526 */ |
|
527 IMPORT_C virtual void CancelPlaybackL( const CVCommandHandler& aHandler ) const; |
|
528 |
|
529 IMPORT_C TBool operator==( const CVCommand& aCommand ) const; |
|
530 |
|
531 /** |
|
532 * Tells if all non user-changeable parts of aCommand are equal to this command |
|
533 * @return ETrue if equal, EFalse otherwise |
|
534 */ |
|
535 IMPORT_C TBool EqualNonUserChangeableData( const CVCommand& aCommand ) const; |
|
536 |
|
537 protected: |
|
538 /** |
|
539 * @leave KErrOverflow if aText is longer, than KMaxVCTextLength |
|
540 */ |
|
541 void ConstructL( const TDesC& aText, const CVCRunnable& aRunnable, |
|
542 const CVCCommandUi& aUi ); |
|
543 /** |
|
544 * @see NewL( RReadStream& aStream ) |
|
545 */ |
|
546 void ConstructL( RReadStream& aStream ); |
|
547 |
|
548 /** |
|
549 * Clone itself |
|
550 * Is used for copying via NewL( CVCommand& aOriginal ) |
|
551 * To be overridden by descendants |
|
552 */ |
|
553 virtual CVCommand* CloneL() const; |
|
554 |
|
555 private: |
|
556 // Text to be recognized |
|
557 HBufC* iSpokenText; |
|
558 CVCRunnable* iRunnable; |
|
559 CVCCommandUi* iCommandUi; |
|
560 |
|
561 }; |
|
562 |
|
563 /** Array of pointers to CVCommands */ |
|
564 typedef RPointerArray<CVCommand> RVCommandArray; |
|
565 |
|
566 /** |
|
567 * Non-modifiable list of VCommands |
|
568 */ |
|
569 class CVCommandArray : public CBase |
|
570 { |
|
571 public: |
|
572 /** |
|
573 * Constructs the non-modifiable CVCommandArray |
|
574 * @param aSource Commands to store. CVCommandArray makes |
|
575 * copies of them |
|
576 */ |
|
577 IMPORT_C static CVCommandArray* NewL( const RVCommandArray& aSource ); |
|
578 |
|
579 /** |
|
580 * Destructor |
|
581 */ |
|
582 IMPORT_C ~CVCommandArray(); |
|
583 |
|
584 /** |
|
585 * Returns the reference to the command stored in this |
|
586 * CVCommandArray |
|
587 * @param aIndex Zero-based index of the command. If aIndex is out of |
|
588 * bounds, this method will panic with USER 130 |
|
589 * @return Unmodifiable reference to CVCommand |
|
590 */ |
|
591 IMPORT_C const CVCommand& At( TInt aIndex ) const; |
|
592 |
|
593 /** |
|
594 * Equivalent to the operator At |
|
595 * @see At() |
|
596 */ |
|
597 IMPORT_C const CVCommand& operator[]( TInt aIndex ) const; |
|
598 |
|
599 /** |
|
600 * Returns the number of commands |
|
601 */ |
|
602 IMPORT_C TInt Count() const; |
|
603 |
|
604 /** |
|
605 * For the compatibility with routines, requiring RVCommandArray |
|
606 * @return Unmodifiable array of pointers to VCommands |
|
607 */ |
|
608 IMPORT_C const RVCommandArray& PointerArray() const; |
|
609 |
|
610 /** |
|
611 * Figures out which commands have to untrained (removed from the system) |
|
612 * if this command set is merged with aUpdates. |
|
613 * Merging is performed on the basis of comapring the commands' Runnable component |
|
614 * If runnables are equal, the commands are considered being equal. |
|
615 * It is useful e.g. when figuring out what to (un)train after the language change |
|
616 * |
|
617 * @param aUpdates Set of commands to merge in. |
|
618 * @return Set of commands to be removed from the system if the merging takes place |
|
619 * @see ProduceTrainSetByRunnables |
|
620 */ |
|
621 IMPORT_C CVCommandArray* ProduceUntrainSetByRunnablesLC( |
|
622 const RVCommandArray& aUpdates ) const; |
|
623 |
|
624 /** |
|
625 * Figures out which commands have to trained (removed added to the system) |
|
626 * if this command set is merged with aUpdates. |
|
627 * Merging is performed on the basis of comapring the commands' Runnable component |
|
628 * If runnables are equal, the commands are considered being equal. |
|
629 * It is useful e.g. when figuring out what to (un)train after the language change |
|
630 * |
|
631 * @param aUpdates Set of commands to merge in. |
|
632 * @return Set of commands to be added to the system if the merging takes place |
|
633 * @see ProduceUntrainSetByRunnables |
|
634 */ |
|
635 IMPORT_C CVCommandArray* ProduceTrainSetByRunnablesLC( |
|
636 const RVCommandArray& aUpdates ) const; |
|
637 |
|
638 private: |
|
639 void ConstructL( const RVCommandArray& aSource ); |
|
640 |
|
641 private: |
|
642 RVCommandArray iCommands; |
|
643 }; |
|
644 |
|
645 /** |
|
646 * Allows the CVCommandHandler clients be notified about the vcommand set |
|
647 * changes by another instances of the CVCommandHandler |
|
648 */ |
|
649 class MVCommandHandlerObserver |
|
650 { |
|
651 public: |
|
652 /** |
|
653 * Is called whenever the VCommand set is changed |
|
654 * by *another* instance of CVCommandHandler. I.e. lets the client know if |
|
655 * his understanding of the VCommand set is up to date |
|
656 */ |
|
657 virtual void CommandSetChanged() = 0; |
|
658 }; |
|
659 |
|
660 /** |
|
661 * Provider of the voice command services |
|
662 */ |
|
663 class CVCommandHandler : public CBase |
|
664 { |
|
665 public: |
|
666 /** |
|
667 * Factory function |
|
668 * @param aObserver Listener to be notified whenever the VCommand set is changed |
|
669 * by *another* instance of CVCommandHandler. I.e. lets the client know if |
|
670 * his understanding of the VCommand set is up to date |
|
671 */ |
|
672 IMPORT_C static CVCommandHandler* NewL( MVCommandHandlerObserver* aObserver = NULL ); |
|
673 |
|
674 IMPORT_C virtual ~CVCommandHandler(); |
|
675 |
|
676 /** |
|
677 * Synchronous. Service doesn't take the ownership, but makes an own copy |
|
678 * Duplicates can be added |
|
679 * @todo should we check for duplicates and leave with KErrAlreadyExists? |
|
680 */ |
|
681 IMPORT_C virtual void AddCommandL( const CVCommand& aCommand ); |
|
682 |
|
683 /** |
|
684 * Synchronous. Service doesn't take the ownership, but makes an own copies |
|
685 * Duplicates can be added |
|
686 * @todo should we check for duplicates and leave with KErrAlreadyExists? |
|
687 * @param aCommands Commands to add |
|
688 * @param aIgnoreErrors If ETrue, even if some commands fail to be trained, |
|
689 * handler adds all that are trainable |
|
690 */ |
|
691 IMPORT_C virtual void AddCommandsL( const RVCommandArray& aCommands, |
|
692 TBool aIgnoreErrors = EFalse ); |
|
693 |
|
694 /** |
|
695 * Synchronous. Removes the command from the system |
|
696 * @param aCommand Reference to the command to be removed. Existing commands are |
|
697 * compared against aCommand. All the matches are removed from VAS |
|
698 * @leave KErrNotFound No such command |
|
699 */ |
|
700 IMPORT_C virtual void RemoveCommandL( const CVCommand& aCommand ); |
|
701 |
|
702 /** |
|
703 * Synchronous. |
|
704 * @param aCommands Reference to the list of commands to be removed. Existing commands are |
|
705 * compared against aCommands items. All the matches are removed from VAS |
|
706 * @param aIgnoreErrors If ETrue, even if some commands fail to be removed, |
|
707 * handler will remove as many as possible |
|
708 */ |
|
709 IMPORT_C virtual void RemoveCommandsL( const RVCommandArray& aCommands, |
|
710 TBool aIgnoreErrors = EFalse ); |
|
711 |
|
712 |
|
713 /** |
|
714 * Synchronous |
|
715 * @return an array of the commands in the system |
|
716 * Ownership of the array is transfered to the client |
|
717 * The returned CVCommandArray contains copies of all the |
|
718 * commands currently stored in this handler |
|
719 */ |
|
720 IMPORT_C virtual CVCommandArray* ListCommandsL(); |
|
721 |
|
722 /** |
|
723 * Not intented to be called directly. |
|
724 * @see CVCommand::PlaySpokenTextL |
|
725 */ |
|
726 virtual void PlaySpokenTextL( const CStoredVCommand& aCommand, |
|
727 MNssPlayEventHandler& aPlayEventHandler ) const; |
|
728 |
|
729 /** |
|
730 * Not intented to be called directly. |
|
731 * @see CVCommand::PlayAlternativeSpokenTextL |
|
732 */ |
|
733 virtual void PlayAlternativeSpokenTextL( const CStoredVCommand& aCommand, |
|
734 MNssPlayEventHandler& aPlayEventHandler ) const; |
|
735 |
|
736 /** |
|
737 * Not intented to be called directly. |
|
738 * @see CVCommand::CancelPlaybackL |
|
739 */ |
|
740 virtual void CancelPlaybackL( const CStoredVCommand& aCommand ) const; |
|
741 |
|
742 private: |
|
743 void ConstructL( MVCommandHandlerObserver* aObserver ); |
|
744 // Implementation of the VCommand API |
|
745 MVCService* iImpl; |
|
746 }; |
|
747 |
|
748 #endif // VCOMMANDAPI_H |
|