2 * Copyright (c) 2011-2016 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __VOICE_CONTROL_H__
19 #define __VOICE_CONTROL_H__
22 #include <voice_control_command.h>
23 #include <voice_control_common.h>
27 * @addtogroup CAPI_UIX_VOICE_CONTROL_MODULE
39 * @file voice_control.h
40 * @brief This file contains the voice control client API and related callback definitions and enums.
45 * @file voice_control_command.h
46 * @brief This file contains the command list and command API and related handle definitions and enums.
51 * @file voice_control_common.h
52 * @brief This file contains the callback function definitions and enums.
57 * @brief Definition for foreground command type.
58 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
60 #define VC_COMMAND_TYPE_FOREGROUND 1
64 * @brief Definition for background command type.
65 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
67 #define VC_COMMAND_TYPE_BACKGROUND 2
71 * @brief Definition for ended dialog.
74 #define VC_DIALOG_END 0
78 * @brief Definition for continued dialog.
81 #define VC_DIALOG_CONTINUE 1
85 * @brief Initializes voice control.
86 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
88 * @privilege %http://tizen.org/privilege/recorder
89 * @remarks If the function succeeds, @a vc must be released with vc_deinitialize().
90 * @return @c 0 on success,
91 * otherwise a negative error value
92 * @retval #VC_ERROR_NONE Successful
93 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
94 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
95 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
96 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
97 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
98 * @see vc_deinitialize()
100 int vc_initialize(void);
104 * @brief Deinitializes voice control.
105 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
107 * @privilege %http://tizen.org/privilege/recorder
108 * @return @c 0 on success,
109 * otherwise a negative error value
110 * @retval #VC_ERROR_NONE Successful
111 * @retval #VC_ERROR_INVALID_STATE Invalid state
112 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
113 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
114 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
115 * @see vc_deinitialize()
117 int vc_deinitialize(void);
121 * @brief Connects the voice control service.
122 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
124 * @privilege %http://tizen.org/privilege/recorder
125 * @return @c 0 on success,
126 * otherwise a negative error value
127 * @retval #VC_ERROR_NONE Successful
128 * @retval #VC_ERROR_INVALID_STATE Invalid state
129 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
130 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
131 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
132 * @pre The state should be #VC_STATE_INITIALIZED.
133 * @post If this function is called, the state will be #VC_STATE_READY.
134 * @see vc_unprepare()
136 int vc_prepare(void);
140 * @brief Disconnects the voice control service.
141 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
143 * @privilege %http://tizen.org/privilege/recorder
144 * @return @c 0 on success,
145 * otherwise a negative error value
146 * @retval #VC_ERROR_NONE Successful
147 * @retval #VC_ERROR_INVALID_STATE Invalid state
148 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
149 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
150 * @pre The state should be #VC_STATE_READY.
151 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
154 int vc_unprepare(void);
158 * @brief Retrieves all supported languages using callback function.
159 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
161 * @privilege %http://tizen.org/privilege/recorder
162 * @param[in] callback Callback function to invoke
163 * @param[in] user_data The user data to be passed to the callback function
164 * @return @c 0 on success,
165 * otherwise a negative error value
166 * @retval #VC_ERROR_NONE Successful
167 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
168 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
169 * @retval #VC_ERROR_INVALID_STATE Invalid state
170 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
171 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
172 * @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY.
173 * @post This function invokes vc_supported_language_cb() repeatedly for getting languages.
174 * @see vc_supported_language_cb()
175 * @see vc_get_current_language()
177 int vc_foreach_supported_languages(vc_supported_language_cb callback, void* user_data);
181 * @brief Gets current language.
182 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
184 * @privilege %http://tizen.org/privilege/recorder
185 * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it.
186 * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code
187 * followed by ISO 639-1 for the two-letter language code.
188 * For example, "ko_KR" for Korean, "en_US" for American English
189 * @return @c 0 on success,
190 * otherwise a negative error value
191 * @retval #VC_ERROR_NONE Successful
192 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
193 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
194 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
195 * @retval #VC_ERROR_INVALID_STATE Invalid state
196 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
197 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
198 * @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY.
199 * @see vc_foreach_supported_languages()
201 int vc_get_current_language(char** language);
205 * @brief Gets current state of voice control client.
206 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
208 * @privilege %http://tizen.org/privilege/recorder
209 * @param[out] state The current state
210 * @return @c 0 on success,
211 * otherwise a negative error value
212 * @retval #VC_ERROR_NONE Successful
213 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
214 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
215 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
216 * @see vc_state_changed_cb()
217 * @see vc_set_state_changed_cb()
219 int vc_get_state(vc_state_e* state);
223 * @brief Gets current state of voice control service.
224 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
226 * @privilege %http://tizen.org/privilege/recorder
227 * @param[out] state The current state
228 * @return @c 0 on success,
229 * otherwise a negative error value
230 * @retval #VC_ERROR_NONE Successful
231 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
232 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
233 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
234 * @pre The state should be #VC_STATE_READY.
235 * @see vc_request_start()
236 * @see vc_request_stop()
237 * @see vc_request_cancel()
238 * @see vc_set_service_state_changed_cb()
239 * @see vc_unset_service_state_changed_cb()
241 int vc_get_service_state(vc_service_state_e* state);
245 * @brief Gets the system command list.
248 * @privilege %http://tizen.org/privilege/recorder
249 * @remarks In the system command list, there are system commands predefined by product manufacturers. Those commands have the highest priority.
250 * Therefore, the user can not set any commands same with the system commands.
251 * The @a vc_sys_cmd_list must be released using free() when it is no longer required.
252 * @param[out] vc_sys_cmd_list System command list handle
253 * @return @c 0 on success,
254 * otherwise a negative error value
255 * @retval #VC_ERROR_NONE Successful
256 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
257 * @retval #VC_ERROR_INVALID_STATE Invalid state
258 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
259 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
260 * @pre The service state should be #VC_SERVICE_STATE_READY.
261 * @see vc_unset_command_list()
263 int vc_get_system_command_list(vc_cmd_list_h* vc_sys_cmd_list);
267 * @brief Sets the invocation name.
270 * @privilege %http://tizen.org/privilege/recorder
271 * @remarks Invocation name is used to activate background commands. The invocation name can be the same as the application name or any other phrase.
272 * For example, an application "Tizen Sample" has a background command, "Play music", and the invocation name of the application is set to "Tizen Sample".
273 * In order to activate the background command, users can say "Tizen Sample, Play music".
274 * The invocation name is dependent on the current language. For example, if the current language is "en_US"(English), the invocation name is also "en_US".
275 * If the current language is "ja_JP"(Japanese) and the invocation name is "en_US", the invocation name will not be recognized.
276 * This function should be called before vc_set_command_list().
277 * @param[in] name Invocation name that an application wants to be invoked by
278 * @return @c 0 on success,
279 * otherwise a negative error value
280 * @retval #VC_ERROR_NONE Successful
281 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
282 * @retval #VC_ERROR_INVALID_STATE Invalid state
283 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
284 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
285 * @pre The state should be #VC_STATE_READY.
286 * @see vc_set_command_list()
288 int vc_set_invocation_name(const char* name);
292 * @brief Requests to start the dialogue.
293 * @details Using this function, the developer can request starting the dialogue to the framework.
294 * When the developer requests the dialogue, two types of texts, @a disp_text and @a utt_text, can be sent by this function.
295 * @a disp_text is a text for displaying, and @a utt_text is that for uttering.
296 * For example, if @a disp_text is "October 10th" and @a utt_text is "Today is October 10th.", "October 10th" will be displayed on the screen and "Today is October 10th." will be spoken.
297 * Also, the developer can set whether the dialogue starts automatically or not, using @a auto_start.
298 * If the developer sets @a auto_start as @c true, the framework will start to record next speech and continue the dialogue.
301 * @privilege %http://tizen.org/privilege/recorder
302 * @remarks If @a auto_start is @c true, the recognition will start again. In this case, it can be restarted up to 4 times.
303 * @param[in] disp_text Text to be displayed on the screen
304 * @param[in] utt_text Text to be spoken
305 * @param[in] auto_start A variable for setting whether the dialog session will be restarted automatically or not
306 * @return @c 0 on success,
307 * otherwise a negative error value
308 * @retval #VC_ERROR_NONE Successful
309 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
310 * @retval #VC_ERROR_INVALID_STATE Invalid state
311 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
312 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
313 * @pre The service state should be #VC_SERVICE_STATE_READY.
315 int vc_request_dialog(const char* disp_text, const char* utt_text, bool auto_start);
319 * @brief Sets command list.
320 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
322 * @privilege %http://tizen.org/privilege/recorder
323 * @remarks The command type is valid for #VC_COMMAND_TYPE_FOREGROUND or #VC_COMMAND_TYPE_BACKGROUND.
324 * The matched commands of command list should be set and they should include type and command text at least.
325 * @param[in] vc_cmd_list Command list handle
326 * @param[in] type Command type
327 * @return @c 0 on success,
328 * otherwise a negative error value
329 * @retval #VC_ERROR_NONE Successful
330 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
331 * @retval #VC_ERROR_INVALID_STATE Invalid state
332 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
333 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
334 * @pre The state should be #VC_STATE_READY.
335 * @see vc_unset_command_list()
337 int vc_set_command_list(vc_cmd_list_h vc_cmd_list, int type);
341 * @brief Unsets command list.
342 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
344 * @privilege %http://tizen.org/privilege/recorder
345 * @param[in] type Command type
346 * @return @c 0 on success,
347 * otherwise a negative error value
348 * @retval #VC_ERROR_NONE Successful
349 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
350 * @retval #VC_ERROR_INVALID_STATE Invalid state
351 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
352 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
353 * @pre The state should be #VC_STATE_READY.
354 * @see vc_set_command_list()
356 int vc_unset_command_list(int type);
360 * @brief Gets the recognition result.
363 * @privilege %http://tizen.org/privilege/recorder
364 * @param[in] callback Callback function to get recognition result
365 * @param[in] user_data The user data to be passed to the callback function
366 * @return @c 0 on success,
367 * otherwise a negative error value
368 * @retval #VC_ERROR_NONE Successful
369 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
370 * @retval #VC_ERROR_INVALID_STATE Invalid state
371 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
372 * @pre The state should be #VC_STATE_READY.
373 * @see vc_result_cb()
375 int vc_get_result(vc_result_cb callback, void* user_data);
379 * @brief Registers a callback function for getting recognition result.
380 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
382 * @privilege %http://tizen.org/privilege/recorder
383 * @param[in] callback Callback function to register
384 * @param[in] user_data The user data to be passed to the callback function
385 * @return @c 0 on success,
386 * otherwise a negative error value
387 * @retval #VC_ERROR_NONE Successful
388 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
389 * @retval #VC_ERROR_INVALID_STATE Invalid state
390 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
391 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
392 * @pre The state should be #VC_STATE_INITIALIZED.
393 * @see vc_result_cb()
394 * @see vc_unset_result_cb()
396 int vc_set_result_cb(vc_result_cb callback, void* user_data);
400 * @brief Unregisters the callback function.
401 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
403 * @privilege %http://tizen.org/privilege/recorder
404 * @return @c 0 on success,
405 * otherwise a negative error value
406 * @retval #VC_ERROR_NONE Successful
407 * @retval #VC_ERROR_INVALID_STATE Invalid state
408 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
409 * @pre The state should be #VC_STATE_INITIALIZED.
410 * @see vc_set_result_cb()
412 int vc_unset_result_cb(void);
416 * @brief Registers a callback function to be called when state is changed.
417 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
419 * @privilege %http://tizen.org/privilege/recorder
420 * @param[in] callback Callback function to register
421 * @param[in] user_data The user data to be passed to the callback function
422 * @return @c 0 on success,
423 * otherwise a negative error value
424 * @retval #VC_ERROR_NONE Successful
425 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
426 * @retval #VC_ERROR_INVALID_STATE Invalid state
427 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
428 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
429 * @pre The state should be #VC_STATE_INITIALIZED.
430 * @see vc_service_state_changed_cb()
431 * @see vc_unset_service_state_changed_cb()
433 int vc_set_service_state_changed_cb(vc_service_state_changed_cb callback, void* user_data);
437 * @brief Unregisters the callback function.
438 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
440 * @privilege %http://tizen.org/privilege/recorder
441 * @return @c 0 on success,
442 * otherwise a negative error value
443 * @retval #VC_ERROR_NONE Successful
444 * @retval #VC_ERROR_INVALID_STATE Invalid state
445 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
446 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
447 * @pre The state should be #VC_STATE_INITIALIZED.
448 * @see vc_set_service_state_changed_cb()
450 int vc_unset_service_state_changed_cb(void);
454 * @brief Registers a callback function to be called when state is changed.
455 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
457 * @privilege %http://tizen.org/privilege/recorder
458 * @param[in] callback Callback function to register
459 * @param[in] user_data The user data to be passed to the callback function
460 * @return @c 0 on success,
461 * otherwise a negative error value
462 * @retval #VC_ERROR_NONE Successful
463 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
464 * @retval #VC_ERROR_INVALID_STATE Invalid state
465 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
466 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
467 * @pre The state should be #VC_STATE_INITIALIZED.
468 * @see vc_state_changed_cb()
469 * @see vc_unset_state_changed_cb()
471 int vc_set_state_changed_cb(vc_state_changed_cb callback, void* user_data);
475 * @brief Unregisters the callback function.
476 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
478 * @privilege %http://tizen.org/privilege/recorder
479 * @return @c 0 on success,
480 * otherwise a negative error value
481 * @retval #VC_ERROR_NONE Successful
482 * @retval #VC_ERROR_INVALID_STATE Invalid state
483 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
484 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
485 * @pre The state should be #VC_STATE_INITIALIZED.
486 * @see vc_set_state_changed_cb()
488 int vc_unset_state_changed_cb(void);
492 * @brief Registers a callback function to be called when current language is changed.
493 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
495 * @privilege %http://tizen.org/privilege/recorder
496 * @param[in] callback Callback function to register
497 * @param[in] user_data The user data to be passed to the callback function
498 * @return @c 0 on success,
499 * otherwise a negative error value
500 * @retval #VC_ERROR_NONE Successful
501 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
502 * @retval #VC_ERROR_INVALID_STATE Invalid state
503 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
504 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
505 * @pre The state should be #VC_STATE_INITIALIZED.
506 * @see vc_current_language_changed_cb()
507 * @see vc_unset_current_language_changed_cb()
509 int vc_set_current_language_changed_cb(vc_current_language_changed_cb callback, void* user_data);
513 * @brief Unregisters the callback function.
514 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
516 * @privilege %http://tizen.org/privilege/recorder
517 * @return @c 0 on success,
518 * otherwise a negative error value
519 * @retval #VC_ERROR_NONE Successful
520 * @retval #VC_ERROR_INVALID_STATE Invalid state
521 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
522 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
523 * @pre The state should be #VC_STATE_INITIALIZED.
524 * @see vc_set_current_language_changed_cb()
526 int vc_unset_current_language_changed_cb(void);
530 * @brief Registers a callback function to be called when an error occurred.
531 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
533 * @privilege %http://tizen.org/privilege/recorder
534 * @param[in] callback Callback function to register
535 * @param[in] user_data The user data to be passed to the callback function
536 * @return @c 0 on success,
537 * otherwise a negative error value
538 * @retval #VC_ERROR_NONE Successful
539 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
540 * @retval #VC_ERROR_INVALID_STATE Invalid state
541 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
542 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
543 * @pre The state should be #VC_STATE_INITIALIZED.
545 * @see vc_unset_error_cb()
547 int vc_set_error_cb(vc_error_cb callback, void* user_data);
551 * @brief Unregisters the callback function.
552 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
554 * @privilege %http://tizen.org/privilege/recorder
555 * @return @c 0 on success,
556 * otherwise a negative error value
557 * @retval #VC_ERROR_NONE Successful
558 * @retval #VC_ERROR_INVALID_STATE Invalid state
559 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
560 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
561 * @pre The state should be #VC_STATE_INITIALIZED.
562 * @see vc_set_error_cb()
564 int vc_unset_error_cb(void);
575 #endif /* __VOICE_CONTROL_H__ */