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, that are private for the |
|
15 * : vcommand API implementation |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 |
|
21 #ifndef VCOMMANDINTERNALAPI_H |
|
22 #define VCOMMANDINTERNALAPI_H |
|
23 |
|
24 #include <e32def.h> |
|
25 #include <e32cmn.h> |
|
26 #include <s32strm.h> |
|
27 #include <vcommandapi.h> |
|
28 |
|
29 // context for voice commands tags |
|
30 _LIT( KVoiceCommandContext, "COMMAND" ); |
|
31 |
|
32 /** |
|
33 * VCommand with a link to the VAS. This link is a command id |
|
34 * Stored VCommand can be played back |
|
35 */ |
|
36 class CStoredVCommand : public CVCommand |
|
37 { |
|
38 private: |
|
39 // suppress inherited constructors by making them private |
|
40 /** |
|
41 * Factory function. Create a const snapshop of exe-ui-vastext collection |
|
42 * @param aText Text to be trained by VAS. Can be of any length, however |
|
43 * only first KNssVasDbTagName characters will be trained by VAS |
|
44 * @see KNssVasDbTagName in nssvasdbkonsts.h |
|
45 * @param aRunnable Executable to be fired when the command is recognized. |
|
46 * VCommand takes the ownership on the aRunnable |
|
47 * @param aUi visible strings to be displayed in VC App. VCommand takes |
|
48 * the ownership on the aUi |
|
49 */ |
|
50 static CVCommand* NewL( const TDesC& aText, const CVCRunnable& aRunnable, |
|
51 const CVCCommandUi& aUi ); |
|
52 |
|
53 /** |
|
54 * Internalizes the command from stream |
|
55 * @leave KErrNotSupported if the stream data format is unsupported |
|
56 * e.g. if it has been written by newer implementation |
|
57 */ |
|
58 static CVCommand* NewL( RReadStream &aStream ); |
|
59 |
|
60 public: |
|
61 // constructors with the commandId |
|
62 /** |
|
63 * Factory function. Create a const snapshop of exe-ui-vastext collection |
|
64 * @param aText Text to be trained by VAS. Can be of any length, however |
|
65 * only first KNssVasDbTagName characters will be trained by VAS |
|
66 * @see KNssVasDbTagName in nssvasdbkonsts.h |
|
67 * @param aRunnable Executable to be fired when the command is recognized. |
|
68 * VCommand takes the ownership on the aRunnable |
|
69 * @param aUi visible strings to be displayed in VC App. VCommand takes |
|
70 * the ownership on the aUi |
|
71 */ |
|
72 static CStoredVCommand* NewL( const TDesC& aText, const CVCRunnable& aRunnable, |
|
73 const CVCCommandUi& aUi, TInt aCommandId ); |
|
74 |
|
75 /** |
|
76 * Internalizes the command from stream |
|
77 * @leave KErrNotSupported if the stream data format is unsupported |
|
78 * e.g. if it has been written by newer implementation |
|
79 */ |
|
80 static CStoredVCommand* NewL( RReadStream &aStream, TInt aCommandId ); |
|
81 |
|
82 /** |
|
83 * @return CommandId |
|
84 */ |
|
85 TInt CommandId() const; |
|
86 |
|
87 /** |
|
88 * Attempts to play back the text expected to be recognized. |
|
89 * To be playable command has to be added to CVCommandHandler AND |
|
90 * then retrieved back |
|
91 * |
|
92 * @param aHandler CVCommandHandler where the command is stored |
|
93 * @todo Consider storing link to CVCommandHandler within the CStoredVCommand |
|
94 * Pros: No clumsy aHandler argument for the playback |
|
95 * Pros: No need to remember in which handler the command is stored |
|
96 * and why specifying storage is needed during the playback |
|
97 * Cons: In case of internal link the linked handler should still |
|
98 * exist. It cannot be e.g. destroyed and recreated later even |
|
99 * if the latter one is using the same VAS |
|
100 * |
|
101 * @param aPlayEventHandler Entity that handles the playback callbacks |
|
102 * @see NssVasMPlayEventHandler.h |
|
103 * |
|
104 * @leave KErrBadHandle if the current command has not been retrieved |
|
105 * from CVCommandHandler (i.e. was not trained for recognition) |
|
106 * @leave KErrNotFound if this command cannot be found in aHandler |
|
107 * @leave KErrNotReady @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
108 * EVasUnexpectedRequest |
|
109 * @leave KErrInUse @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
110 * EVasInUse |
|
111 * @leave KErrArgument @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
112 * EVasInvalidParameter |
|
113 * @leave KErrGeneral @see nssvasmspeechitem.h MNssSpeechItem::TNssSpeechItemResult |
|
114 * EVasPlayFailed |
|
115 */ |
|
116 void PlaySpokenTextL( const CVCommandHandler& aHandler, |
|
117 MNssPlayEventHandler& aPlayEventHandler ) const; |
|
118 |
|
119 /** |
|
120 * Plays back the user-specified alternative spoken text. |
|
121 * Otherwise is identical to PlaySpokenTextL |
|
122 * @see PlaySpokenTextL |
|
123 * @leave KErrNotFound if this command cannot be found in aHandler of if |
|
124 * it doesn't have a user-specified text |
|
125 */ |
|
126 void PlayAlternativeSpokenTextL( const CVCommandHandler& aHandler, |
|
127 MNssPlayEventHandler& aPlayEventHandler ) const; |
|
128 |
|
129 /** |
|
130 * Cancels playback of a spoken or alternative spoken text |
|
131 * To be playable command has to be added to CVCommandHandler AND |
|
132 * then retrieved back. After this function neither HandlePlayStarted, |
|
133 * nor HandlePlayComplete will be called |
|
134 * |
|
135 * @param aHandler CVCommandHandler where the command is stored |
|
136 * |
|
137 * @leave KErrBadHandle if the current command has not been retrieved |
|
138 * from CVCommandHandler (i.e. was not trained for recognition) |
|
139 * @leave KErrNotReady if playback has never been started |
|
140 * |
|
141 */ |
|
142 void CancelPlaybackL( const CVCommandHandler& aHandler ) const; |
|
143 |
|
144 protected: |
|
145 /** |
|
146 * @see CVCommand::ConstructL |
|
147 */ |
|
148 void ConstructL( const TDesC& aText, const CVCRunnable& aRunnable, |
|
149 const CVCCommandUi& aUi, TInt aCommandId ); |
|
150 /** |
|
151 * @see CVCommand::ConstructL |
|
152 */ |
|
153 void ConstructL( RReadStream& aStream, TInt aCommandId ); |
|
154 |
|
155 /** |
|
156 * Clone itself |
|
157 * Is used for copying via NewL( CVCommand& aOriginal ) |
|
158 */ |
|
159 CVCommand* CloneL() const; |
|
160 |
|
161 private: |
|
162 TInt iCommandId; |
|
163 }; |
|
164 |
|
165 |
|
166 /** |
|
167 * Interface for storing, listing and removing voice commands to/from VAS |
|
168 */ |
|
169 class MVCService |
|
170 { |
|
171 public: |
|
172 /** |
|
173 * Synchronous. Service doesn't take the ownership, but makes an own copy |
|
174 * Duplicates can be added |
|
175 * @todo should we check for duplicates and leave with KErrAlreadyExists? |
|
176 */ |
|
177 virtual void AddCommandL( const CVCommand& aCommand ) = 0; |
|
178 |
|
179 /** |
|
180 * Synchronous. Service doesn't take the ownership, but makes an own copy |
|
181 * Duplicates can be added |
|
182 * @todo Should we check for duplicates and leave with KErrAlreadyExists? |
|
183 * @param aIgnoreErrors If ETrue, even if some commands fail to be trained, |
|
184 * handler adds all that are trainable |
|
185 */ |
|
186 virtual void AddCommandsL( const RVCommandArray& aCommands, |
|
187 TBool aIgnoreErrors = EFalse ) = 0; |
|
188 |
|
189 /** |
|
190 * Synchronous. Removes the command from the system |
|
191 * @param aCommand Reference to the command to be removed. Existing commands are |
|
192 * compared against aCommand. All the matches are removed from VAS |
|
193 * @leave KErrNotFound No such command |
|
194 */ |
|
195 virtual void RemoveCommandL( const CVCommand& aCommand ) = 0; |
|
196 |
|
197 /** |
|
198 * Synchronous. |
|
199 * @param aCommands Reference to the list of commands to be removed. Existing commands are |
|
200 * compared against aCommands items. All the matches are removed from VAS |
|
201 * @param aIgnoreErrors If ETrue, even if some commands fail to be removed, |
|
202 * handler will remove as many as possible |
|
203 */ |
|
204 virtual void RemoveCommandsL( const RVCommandArray& aCommands, |
|
205 TBool aIgnoreErrors = EFalse ) = 0; |
|
206 |
|
207 |
|
208 /** |
|
209 * Synchronous |
|
210 * @return an array of the commands in the system |
|
211 * Ownership of the array is transfered to the client |
|
212 * The returned CVCommandArray contains copies of all the |
|
213 * commands currently stored in this handler |
|
214 */ |
|
215 virtual CVCommandArray* ListCommandsL() = 0; |
|
216 |
|
217 /** |
|
218 * This method is not intended to be called directly. |
|
219 * Use CVCommand::PlaySpokenTextL instead |
|
220 * @see CVCommand::PlaySpokenTextL |
|
221 * @see CStoredVCommand::PlaySpokenTextL |
|
222 */ |
|
223 virtual void PlaySpokenTextL( const CStoredVCommand& aCommand, |
|
224 MNssPlayEventHandler& aPlayEventHandler ) = 0; |
|
225 |
|
226 /** |
|
227 * This method is not intended to be called directly. |
|
228 * Use CVCommand::PlayAlternativeSpokenTextL instead |
|
229 * @see CVCommand::PlayAlternativeSpokenTextL |
|
230 * @see CStoredVCommand::PlayAlternativeSpokenTextL |
|
231 */ |
|
232 virtual void PlayAlternativeSpokenTextL( const CStoredVCommand& aCommand, |
|
233 MNssPlayEventHandler& aPlayEventHandler ) = 0; |
|
234 |
|
235 /** |
|
236 * This method is not intended to be called directly. |
|
237 * Use CVCommand::CancelPlaybackL instead |
|
238 * @see CVCommand::CancelPlaybackL |
|
239 * @see CStoredVCommand::CancelPlaybackL |
|
240 */ |
|
241 virtual void CancelPlaybackL( const CStoredVCommand& aCommand ) = 0; |
|
242 |
|
243 virtual ~MVCService() {}; |
|
244 }; |
|
245 |
|
246 #endif // VCOMMANDINTERNALAPI_H |
|