|
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: Engine, that links the VCommand application to VAS |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 #ifndef VCOMMANDSERVICES_H |
|
21 #define VCOMMANDSERVICES_H |
|
22 |
|
23 #include <nssvasmrrd.h> |
|
24 #include <nssvasctrainingparameters.h> |
|
25 #include <vcommandapi.h> |
|
26 #include <nssvasmgettagclient.h> // For MNssTagListArray |
|
27 #include <nssvasmplayeventhandler.h> |
|
28 #include "vcommandinternalapi.h" |
|
29 #include "intpropertywatcher.h" |
|
30 |
|
31 // Forward declarations |
|
32 class CNssVASDBMgr; |
|
33 class MNssContextMgr; |
|
34 class MNssTagMgr; |
|
35 class MNssTag; |
|
36 class CTagPlayer; |
|
37 |
|
38 /** |
|
39 * Key for sorting CArrayPtr<MNssTag> by the value of the |
|
40 * first element of the RRD IntArray |
|
41 */ |
|
42 class TVCommandTagPtrArrayKey : public TKeyArrayFix |
|
43 { |
|
44 public: |
|
45 inline TVCommandTagPtrArrayKey( TKeyCmpNumeric aType) |
|
46 :TKeyArrayFix( 0, aType ) {} |
|
47 virtual TAny* At( TInt aIndex ) const; |
|
48 }; |
|
49 |
|
50 /** |
|
51 * Engine, that links the VCommand application to VAS |
|
52 * @todo isolate the MNssPlayEventHandler dependency |
|
53 */ |
|
54 class CVCommandService : public CBase, public MVCService, public MNssPlayEventHandler, |
|
55 private MIntChangeNotifiable |
|
56 |
|
57 { |
|
58 public: |
|
59 // Construction/destruction |
|
60 /** |
|
61 * @param aObserver Listener to be notified whenever the VCommand set is changed |
|
62 * by *another* instance of CVCommandHandler. I.e. lets the client know if |
|
63 * his understanding of the VCommand set is up to date |
|
64 */ |
|
65 static CVCommandService* NewL( MVCommandHandlerObserver* aObserver = NULL ); |
|
66 |
|
67 virtual ~CVCommandService(); |
|
68 |
|
69 // From the MVCService |
|
70 |
|
71 /** |
|
72 * Synchronous. Service doesn't take the ownership, but makes an own copy |
|
73 * Duplicates can be added |
|
74 * @todo Should we check for duplicates and leave with KErrAlreadyExists? |
|
75 * @leave KErrLocked if there is an ongoing operation started by the same thread |
|
76 */ |
|
77 void AddCommandL( const CVCommand& aCommand ); |
|
78 |
|
79 /** |
|
80 * Synchronous. Service doesn't take the ownership, but makes an own copy |
|
81 * Duplicates can be added |
|
82 * @todo Should we check for duplicates and leave with KErrAlreadyExists? |
|
83 * @param aIgnoreErrors If ETrue, even if some commands fail to be trained, |
|
84 * handler adds all that are trainable |
|
85 * @leave KErrLocked if there is an ongoing operation started by the same thread |
|
86 */ |
|
87 void AddCommandsL( const RVCommandArray& aCommands, TBool aIgnoreErrors = EFalse ); |
|
88 |
|
89 /** |
|
90 * Synchronous. Removes the command from the system |
|
91 * @param aCommand Reference to the command to be removed. Existing commands are |
|
92 * compared against aCommand. All the matches are removed from VAS |
|
93 * @leave KErrNotFound No such command |
|
94 * @leave KErrLocked if there is an ongoing operation started by the same thread |
|
95 */ |
|
96 void RemoveCommandL( const CVCommand& aCommand ); |
|
97 |
|
98 /** |
|
99 * Synchronous. |
|
100 * @param aCommands Reference to the list of commands to be removed. Existing commands are |
|
101 * compared against aCommands items. All the matches are removed from VAS |
|
102 * @param aIgnoreErrors If ETrue, even if some commands fail to be removed, |
|
103 * handler will remove as many as possible |
|
104 * @leave KErrLocked if there is an ongoing operation started by the same thread |
|
105 */ |
|
106 void RemoveCommandsL( const RVCommandArray& aCommands, TBool aIgnoreErrors = EFalse ); |
|
107 |
|
108 /** |
|
109 * Synchronous |
|
110 * @leave KErrLocked if there is an ongoing operation started by the same thread |
|
111 * @return an array of the commands in the system |
|
112 * Ownership of the array is transfered to the client |
|
113 * The returned CVCommandArray contains copies of all the |
|
114 * commands currently stored in this handler |
|
115 */ |
|
116 CVCommandArray* ListCommandsL(); |
|
117 |
|
118 /** |
|
119 * Asynchronous |
|
120 * Attempts to play back the text expected to be recognized. |
|
121 * To be playable command has to be added to CVCommandHandler AND |
|
122 * then retrieved back. This function is asynchronous |
|
123 * |
|
124 * @param aPlayEventHandler Entity that handles the playback callbacks |
|
125 * @see NssVasMPlayEventHandler.h |
|
126 * |
|
127 * @leave KErrBadHandle if the current command has not been retrieved |
|
128 * from CVCommandHandler (i.e. was not trained for recognition) |
|
129 * @leave KErrNotFound if this command cannot be found in aHandler |
|
130 * @leave KErrNotReady @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
131 * EVasUnexpectedRequest |
|
132 * @leave KErrInUse @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
133 * EVasInUse |
|
134 * @leave KErrArgument @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
135 * EVasInvalidParameter |
|
136 * @leave KErrGeneral @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
137 * EVasPlayFailed |
|
138 * @leave KErrLocked if there is an ongoing operation started by the same thread |
|
139 */ |
|
140 void PlaySpokenTextL( const CStoredVCommand& aCommand, |
|
141 MNssPlayEventHandler& aPlayEventHandler ); |
|
142 |
|
143 /** |
|
144 * Asynchronous |
|
145 * Plays back the user-specified alternative spoken text. |
|
146 * Otherwise is identical to PlaySpokenTextL |
|
147 * @see PlaySpokenTextL |
|
148 * @leave KErrNotFound if this command cannot be found in aHandler of if |
|
149 * it doesn't have a user-specified text |
|
150 * @leave KErrLocked if there is an ongoing operation started by the same thread |
|
151 */ |
|
152 void PlayAlternativeSpokenTextL( const CStoredVCommand& aCommand, |
|
153 MNssPlayEventHandler& aPlayEventHandler ); |
|
154 |
|
155 /** |
|
156 * This method is not intended to be called directly. |
|
157 * Use CVCommand::CancelPlaybackL instead |
|
158 * @see CVCommand::CancelPlaybackL |
|
159 * @see CStoredVCommand::CancelPlaybackL |
|
160 */ |
|
161 void CancelPlaybackL( const CStoredVCommand& aCommand ); |
|
162 |
|
163 public: |
|
164 |
|
165 // From MNssPlayEventHandler |
|
166 /** |
|
167 * The HandlePlayStarted method is a virtual method implemented by the |
|
168 * client and is called when play is started |
|
169 * @param aDuration - the duration of the utterance data |
|
170 */ |
|
171 virtual void HandlePlayStarted( TTimeIntervalMicroSeconds32 aDuration ); |
|
172 |
|
173 /** |
|
174 * The HandlePlayComplete method is a virtual method implemented by the |
|
175 * client and is called when play is completed |
|
176 * @param aErrorCode EVasErrorNone if playing was successfull |
|
177 */ |
|
178 virtual void HandlePlayComplete( TNssPlayResult aErrorCode ); |
|
179 |
|
180 private: |
|
181 CVCommandService( MVCommandHandlerObserver* aObserver ); |
|
182 |
|
183 void ConstructL(); |
|
184 |
|
185 /** |
|
186 * Returns the VCommand context. Creates one on demand if none exists yet |
|
187 * @return VCommand context. Ownership is transfered to the client |
|
188 */ |
|
189 MNssContext* GetVCommandContextLC() const; |
|
190 |
|
191 /** |
|
192 * Constructs a set of new VAS tags from a command and a context. |
|
193 * Does not save to VAS, just creates. Ownership on the created tag is |
|
194 * passed to the client |
|
195 */ |
|
196 CArrayPtr<MNssTag>* CreateTagsLC2( const CVCommand& aCommand, |
|
197 const MNssContext& aContext ); |
|
198 |
|
199 /** |
|
200 * Constructs training related parameters. Like language to be used |
|
201 * @leave negated TNssSpeechItemResult |
|
202 * @todo Is it ok to mix system-wide codes with the TNssSpeechItemResult codes |
|
203 */ |
|
204 CNssTrainingParameters* ConstructTrainingParametersLC() const; |
|
205 |
|
206 /** |
|
207 * Retrieves the list of tags for a given context. Synchronous. |
|
208 * Leaves two objects on the cleanup stack! |
|
209 * First PopAndDestroy will ResetAndDestroy content |
|
210 * Second one will destroy the MNsstagListArray itself |
|
211 */ |
|
212 MNssTagListArray* GetTagListLC2( const MNssContext& aContext ) const; |
|
213 |
|
214 /** |
|
215 * Retrieves the list of tags for a given context and voice command id. |
|
216 * Synchronous. Leaves two objects on the cleanup stack! |
|
217 * First PopAndDestroy will ResetAndDestroy content |
|
218 * Second one will destroy the MNsstagListArray itself |
|
219 */ |
|
220 MNssTagListArray* GetTagListLC2( const MNssContext& aContext, TInt aCommandId ) const; |
|
221 |
|
222 /** |
|
223 * Resets iCommands and fills them with the commands from VAS |
|
224 */ |
|
225 void RefreshCommandListL(); |
|
226 |
|
227 /** |
|
228 * Marks the iCommands as an invalid reflection of the VAS content. |
|
229 * To make iCommands reflect the real VAS content a call to |
|
230 * RefreshCommandsL is needed |
|
231 */ |
|
232 void InvalidateCacheL(); |
|
233 |
|
234 /** |
|
235 * Marks the iCommands as the valid reflection of the VAS content. |
|
236 */ |
|
237 void MarkCacheValidL(); |
|
238 |
|
239 /** |
|
240 * Tells if the iCommands reflect the content of the VAS DB correctly |
|
241 * @return ETrue if the cache is valid, EFalse otherwise |
|
242 */ |
|
243 TBool IsCacheValidL(); |
|
244 |
|
245 /** |
|
246 * Generates new command id to be used for identifying voice tags, that |
|
247 * belong to the same VCommand |
|
248 */ |
|
249 TInt NewCommandIdL(); |
|
250 |
|
251 /** |
|
252 * Sets the given aId as a VCommand id for all the tags in the given list |
|
253 * This id is set as a first RRD int element of all the given MNssTags. |
|
254 * If the RRD int array has no elements yet, one element is added |
|
255 */ |
|
256 void SetVCommandIdL( CArrayPtr<MNssTag>& aTags, TInt aId ) const; |
|
257 |
|
258 /** |
|
259 * Searches vcommand tags for the tag, that corresponds to the given |
|
260 * commandId and is trained against the given text |
|
261 * @param aCommandId Command id to search for |
|
262 * @param aText |
|
263 * @return ANY of the voice tags corresponding to the given aCommandId |
|
264 * and aText. Typically there will be one such tag only. However, |
|
265 * if there are several it is not specified which one will be |
|
266 * returned |
|
267 * @return NULL if no satisfying tag is found |
|
268 */ |
|
269 MNssTag* TagByCommandIdTextL( TInt aCommandId, const TDesC& aText ); |
|
270 |
|
271 /** |
|
272 * Synchronous. Service doesn't take the ownership, but makes an own copy |
|
273 * Duplicates can be added |
|
274 * Is not the atomic operation |
|
275 * @see AddCommandsL |
|
276 */ |
|
277 void DoAddCommandsL( const RVCommandArray& aCommands, |
|
278 TBool aIgnoreErrors = EFalse ); |
|
279 |
|
280 /** |
|
281 * Synchronous |
|
282 * @see RemoveCommandsL |
|
283 */ |
|
284 void DoRemoveCommandsL( const RVCommandArray& aCommands, |
|
285 TBool aIgnoreErrors = EFalse ); |
|
286 |
|
287 /** |
|
288 * Starts the section of the code, that can be simultaneously executed |
|
289 * only by a single instance of this class. Other instances have to wait |
|
290 * Same as starting the Java "synchronized" method. Puts the function |
|
291 * EndAtomicOperation to cleanup stack to make the use leave safe. Subsequent |
|
292 * call to CleanupStack::PopAndDestroy will run EndAtomicOperation. |
|
293 */ |
|
294 void StartAtomicOperationLC(); |
|
295 |
|
296 /** |
|
297 * Ends the section of the code, that can be simultaneously executed |
|
298 * only by a single instance of this class. Other instances have to wait |
|
299 * Same as exiting the Java "synchronized" method |
|
300 * @leave KErrNotReady if atomic operation hasn't been started |
|
301 */ |
|
302 void EndAtomicOperation(); |
|
303 |
|
304 /** |
|
305 * Runs the EndAtomicOperation when calling CleanupStack::PopAndDestroy after |
|
306 * a call to StartAtomicOperationLC |
|
307 */ |
|
308 static void CleanupEndAtomicOperation( TAny* aService ); |
|
309 |
|
310 /** |
|
311 * Creates and pushes to cleanup stack a TCleanupItem that calls |
|
312 * EndAtomicOperation when CleanupStack::PopAndDestroy is called |
|
313 */ |
|
314 void CreateAndPushEndAtomicCleanupItemL(); |
|
315 |
|
316 private: |
|
317 // From MIntChangeNotifiable |
|
318 /** |
|
319 * Is called by the P&S property watcher to let this object know that |
|
320 * the global tick property has been changed |
|
321 */ |
|
322 void IntValueChanged( TInt aNewValue ); |
|
323 |
|
324 private: |
|
325 // Main access point to VAS |
|
326 CNssVASDBMgr* iVasDbManager; // Owned |
|
327 MNssTagMgr* iTagManager; // Not owned. |
|
328 |
|
329 // Stores the local tick count. When local tick count |
|
330 // is equal to the global tick count, this object is aware |
|
331 // of all the VAS updates |
|
332 TInt iLocalTickCount; |
|
333 |
|
334 // Commands in the system |
|
335 RVCommandArray iCommands; |
|
336 |
|
337 // Maximal used command id |
|
338 TInt iMaxCommandId; |
|
339 |
|
340 // Utility that plays back the voice commands |
|
341 CTagPlayer* iTagPlayer; |
|
342 |
|
343 RMutex iLock; |
|
344 |
|
345 // Client that should be notified about the playback events |
|
346 MNssPlayEventHandler* iPlaybackHandler; |
|
347 |
|
348 // Is used to check the global "tick count", i.e. |
|
349 // number of operations performed by this |
|
350 // and another instances of VCommand handler |
|
351 RProperty iGlobalTickProperty; |
|
352 |
|
353 MVCommandHandlerObserver* iObserver; |
|
354 |
|
355 // Watches for the global tick property to let the services observer |
|
356 // know when the local cache is out of date |
|
357 CIntPropertyWatcher* iGlobalTickWatcher; |
|
358 |
|
359 // Last time when this instance set the global tick count |
|
360 // it was this value. |
|
361 // Is used to distinguish own global tick changes from external global tick changes |
|
362 TInt iLastSetGlobalTickCount; |
|
363 }; |
|
364 |
|
365 #endif // VCOMMANDSERVICES_H |