2 * Copyright (c) 2011-2015 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_WIDGET_H__
19 #define __VOICE_CONTROL_WIDGET_H__
21 #include <voice_control_command.h>
22 #include <voice_control_command_expand.h>
23 #include <voice_control_common.h>
24 #include <voice_control_internal.h>
26 typedef struct vc_s *vc_h;
29 * @addtogroup VOICE_CONTROL_WIDGET
39 * @brief Definitions for widget command type.
40 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
42 #define VC_COMMAND_TYPE_WIDGET 3
45 * @brief Called when widget should show or hide tooltip.
47 * @param[in] vc_widget The voice control handle
48 * @param[in] show Show or hide option
49 * @param[in] user_data The user data passed from the callback registration function
51 * @pre An application registers callback function using vc_widget_set_show_tooltip_cb().
53 * @see vc_widget_set_show_tooltip_cb()
54 * @see vc_widget_unset_show_tooltip_cb()
56 typedef void (*vc_widget_show_tooltip_cb)(bool show, void* user_data);
59 * @brief Called when widget send current command list to vc daemon.
61 * @param[in] vc_widget The voice control handle
62 * @param[out] vc_cmd_list Current command list
63 * @param[in] user_data The user data passed from the callback registration function
65 * @pre An application registers callback function using vc_widget_set_send_current_command_group_cb().
67 * @see vc_widget_set_send_current_command_list_cb()
68 * @see vc_widget_unset_send_current_command_list_cb()
70 typedef void (*vc_widget_send_current_command_list_cb)(vc_cmd_list_h* vc_cmd_list, void* user_data);
74 * @brief Initialize voice control for widget.
76 * @param[in] vc_widget The voice control handle
78 * @remarks If the function succeeds, @a vc widget must be released with vc_widget_deinitialize().
80 * @param[out] vc_widget The voice control handle
82 * @return 0 on success, otherwise a negative error value
83 * @retval #VC_ERROR_NONE Successful
84 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
85 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
86 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
88 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
90 * @see vc_widget_deinitialize()
92 int vc_widget_initialize(vc_h* vc);
95 * @brief Deinitialize voice control for widget.
97 * @param[in] vc_widget The voice control handle
99 * @return 0 on success, otherwise a negative error value
100 * @retval #VC_ERROR_NONE Successful
101 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
102 * @retval #VC_ERROR_INVALID_STATE Invalid state
104 * @see vc_widget_initialize()
106 int vc_widget_deinitialize(vc_h vc);
109 * @brief Connects the voice control service asynchronously.
111 * @param[in] vc_widget The voice control handle
113 * @return 0 on success, otherwise a negative error value
114 * @retval #VC_ERROR_NONE Successful
115 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
116 * @retval #VC_ERROR_INVALID_STATE Invalid state
118 * @pre The state should be #VC_STATE_INITIALIZED.
119 * @post If this function is called, the state will be #VC_STATE_READY.
121 * @see vc_widget_unprepare()
123 int vc_widget_prepare(vc_h vc);
126 * @brief Disconnects the voice control service.
128 * @param[in] vc_widget The voice control handle
130 * @return 0 on success, otherwise a negative error value
131 * @retval #VC_ERROR_NONE Successful
132 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
133 * @retval #VC_ERROR_INVALID_STATE Invalid state
135 * @pre The state should be #VC_STATE_READY.
136 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
138 * @see vc_widget_prepare()
140 int vc_widget_unprepare(vc_h vc);
143 * @brief Retrieves all supported languages using callback function.
145 * @param[in] vc_widget The voice control handle
146 * @param[in] callback Callback function to invoke
147 * @param[in] user_data The user data to be passed to the callback function
149 * @return 0 on success, otherwise a negative error value
150 * @retval #VC_ERROR_NONE Successful
151 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
152 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
153 * @retval #VC_ERROR_INVALID_STATE Invalid state
155 * @pre The state should be #VC_STATE_READY.
156 * @post This function invokes vc_supported_language_cb() repeatedly for getting languages.
158 * @see vc_supported_language_cb()
159 * @see vc_widget_get_current_language()
161 int vc_widget_foreach_supported_languages(vc_h vc, vc_supported_language_cb callback, void* user_data);
164 * @brief Gets current language set by user.
166 * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it.
168 * @param[in] vc_widget The voice control handle
169 * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
170 * followed by ISO 639-1 for the two-letter language code. \n
171 * For example, "ko_KR" for Korean, "en_US" for American English.
173 * @return 0 on success, otherwise a negative error value
174 * @retval #VC_ERROR_NONE Successful
175 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
176 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
177 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
178 * @retval #VC_ERROR_INVALID_STATE Invalid state
180 * @pre The state should be #VC_STATE_READY.
182 * @see vc_widget_foreach_supported_languages()
184 int vc_widget_get_current_language(vc_h vc, char** language);
187 * @brief Gets current state of voice control widget.
189 * @param[in] vc_widget The voice control handle
190 * @param[out] state Current state
192 * @return 0 on success, otherwise a negative error value
193 * @retval #VC_ERROR_NONE Successful
194 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
196 * @see vc_widget_initialize()
197 * @see vc_widget_deinitialize()
198 * @see vc_widget_prepare()
199 * @see vc_widget_unprepare()
200 * @see vc_widget_set_state_changed_cb()
201 * @see vc_widget_unset_state_changed_cb()
203 int vc_widget_get_state(vc_h vc, vc_state_e* state);
206 * @brief Gets current state of voice control service.
208 * @param[in] vc_widget The voice control handle
209 * @param[out] state The current state
211 * @return 0 on success, otherwise a negative error value
212 * @retval #VC_ERROR_NONE Successful
213 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
215 * @see vc_widget_start()
216 * @see vc_widget_stop()
217 * @see vc_widget_cancel()
218 * @see vc_set_service_state_changed_cb()
219 * @see vc_unset_service_state_changed_cb()
221 int vc_widget_get_service_state(vc_h vc, vc_service_state_e* state);
224 * @brief Checks whether the command format is supported.
226 * @param[in] vc_widget The voice control handle
227 * @param[in] format The command format
228 * @param[out] support The result status @c true = supported, @c false = not supported
230 * @return 0 on success, otherwise a negative error value
231 * @retval #VC_ERROR_NONE Successful
232 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
233 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
234 * @retval #VC_ERROR_INVALID_STATE Invalid state
236 * @pre The state should be #VC_STATE_READY.
238 int vc_widget_is_command_format_supported(vc_h vc, vc_cmd_format_e format, bool* support);
242 * @brief Sets foreground state of application.
244 * @param[in] vc_widget The voice control handle
245 * @param[in] value value @c true foreground, \n @c false background.
247 * @return 0 on success, otherwise a negative error value
248 * @retval #VC_ERROR_NONE Successful
249 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
250 * @retval #VC_ERROR_INVALID_STATE Invalid state
251 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
253 * @pre The state should be #VC_STATE_READY.
255 int vc_widget_set_foreground(vc_h vc, bool value);
258 * @brief Cancels recognition.
260 * @param[in] vc_widget The voice control handle
262 * @return 0 on success, otherwise a negative error value
263 * @retval #VC_ERROR_NONE Successful
264 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
265 * @retval #VC_ERROR_INVALID_STATE Invalid state
266 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
268 * @pre The service state should be #VC_SERVICE_STATE_RECORDING or #VC_SERVICE_STATE_PROCESSING.
269 * @post It will invoke vc_state_changed_cb(), if you register a callback with vc_state_changed_cb(). \n
270 * If this function succeeds, the state will be #VC_STATE_READY.
272 * @see vc_widget_start()
273 * @see vc_widget_stop()
274 * @see vc_state_changed_cb()
276 int vc_widget_cancel(vc_h vc);
279 * @brief Registers a callback function for getting recognition result.
281 * @param[in] vc_widget The voice control handle
282 * @param[in] callback Callback function to register
283 * @param[in] user_data The user data to be passed to the callback function
285 * @return 0 on success, otherwise a negative error value
286 * @retval #VC_ERROR_NONE Successful
287 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
288 * @retval #VC_ERROR_INVALID_STATE Invalid state
290 * @pre The state should be #VC_STATE_INITIALIZED.
292 * @see vc_widget_result_cb()
293 * @see vc_widget_unset_result_cb()
295 int vc_widget_set_result_cb(vc_h vc, vc_result_cb callback, void* user_data);
299 * @brief Unregisters the callback function.
301 * @param[in] vc_widget The voice control handle
303 * @return 0 on success, otherwise a negative error value
304 * @retval #VC_ERROR_NONE Successful
305 * @retval #VC_ERROR_INVALID_STATE Invalid state
307 * @pre The state should be #VC_STATE_INITIALIZED.
309 * @see vc_widget_set_result_cb()
311 int vc_widget_unset_result_cb(vc_h vc);
314 * @brief Registers a callback function for showing or hiding tooltip.
316 * @param[in] vc_widget The voice control handle
317 * @param[in] callback Callback function to register
318 * @param[in] user_data The user data to be passed to the callback function
320 * @return 0 on success, otherwise a negative error value
321 * @retval #VC_ERROR_NONE Successful
322 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
323 * @retval #VC_ERROR_INVALID_STATE Invalid state
325 * @pre The state should be #VC_STATE_INITIALIZED.
327 * @see vc_widget_show_tooltip_cb()
328 * @see vc_widget_unset_show_tooltip_cb()
330 int vc_widget_set_show_tooltip_cb(vc_h vc, vc_widget_show_tooltip_cb callback, void* user_data);
333 * @brief Unregisters the callback function.
335 * @param[in] vc_widget The voice control handle
337 * @return 0 on success, otherwise a negative error value
338 * @retval #VC_ERROR_NONE Successful
339 * @retval #VC_ERROR_INVALID_STATE Invalid state
341 * @pre The state should be #VC_STATE_INITIALIZED.
343 * @see vc_widget_set_show_tooltip_cb()
345 int vc_widget_unset_show_tooltip_cb(vc_h vc);
348 * @brief Registers a callback function for setting current command.
350 * @param[in] vc_widget The voice control handle
351 * @param[in] callback Callback function to register
352 * @param[in] user_data The user data to be passed to the callback function
354 * @return 0 on success, otherwise a negative error value
355 * @retval #VC_ERROR_NONE Successful
356 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
357 * @retval #VC_ERROR_INVALID_STATE Invalid state
359 * @pre The state should be #VC_STATE_INITIALIZED.
361 * @see vc_widget_send_current_command_list_cb()
362 * @see vc_widget_unset_send_current_command_list_cb()
364 int vc_widget_set_send_current_command_list_cb(vc_h vc, vc_widget_send_current_command_list_cb callback, void* user_data);
367 * @brief Unregisters the callback function.
369 * @param[in] vc_widget The voice control handle
371 * @return 0 on success, otherwise a negative error value
372 * @retval #VC_ERROR_NONE Successful
373 * @retval #VC_ERROR_INVALID_STATE Invalid state
375 * @pre The state should be #VC_STATE_INITIALIZED.
377 * @see vc_widget_set_send_current_command_list_cb()
379 int vc_widget_unset_send_current_command_list_cb(vc_h vc);
382 * @brief Registers a callback function to be called when service state is changed.
384 * @param[in] vc_widget The voice control handle
385 * @param[in] callback Callback function to register
386 * @param[in] user_data The user data to be passed to the callback function
388 * @return 0 on success, otherwise a negative error value
389 * @retval #VC_ERROR_NONE Successful
390 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
391 * @retval #VC_ERROR_INVALID_STATE Invalid state
393 * @pre The state should be #VC_STATE_INITIALIZED.
395 * @see vc_service_state_changed_cb()
396 * @see vc_widget_unset_service_state_changed_cb()
398 int vc_widget_set_service_state_changed_cb(vc_h vc, vc_service_state_changed_cb callback, void* user_data);
401 * @brief Unregisters the callback function.
403 * @param[in] vc_widget The voice control handle
405 * @return 0 on success, otherwise a negative error value
406 * @retval #VC_ERROR_NONE Successful
407 * @retval #VC_ERROR_INVALID_STATE Invalid state
409 * @pre The state should be #VC_STATE_INITIALIZED.
411 * @see vc_widget_set_service_state_changed_cb()
413 int vc_widget_unset_service_state_changed_cb(vc_h vc);
416 * @brief Registers a callback function for getting state changed.
418 * @param[in] vc_widget The voice control handle
420 * @param[in] callback Callback function to register
421 * @param[in] user_data The user data to be passed to the callback function
423 * @return 0 on success, 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
428 * @pre The state should be #VC_STATE_INITIALIZED.
430 * @see vc_state_changed_cb()
431 * @see vc_widget_unset_state_changed_cb()
433 int vc_widget_set_state_changed_cb(vc_h vc, vc_state_changed_cb callback, void* user_data);
436 * @brief Unregisters the callback function.
438 * @param[in] vc_widget The voice control handle
440 * @return 0 on success, otherwise a negative error value
441 * @retval #VC_ERROR_NONE Successful
442 * @retval #VC_ERROR_INVALID_STATE Invalid state
444 * @pre The state should be #VC_STATE_INITIALIZED.
446 * @see vc_widget_set_state_changed_cb()
448 int vc_widget_unset_state_changed_cb(vc_h vc);
451 * @brief Registers a callback function to be called when current language is changed.
453 * @param[in] vc_widget The voice control handle
455 * @param[in] callback Callback function to register
456 * @param[in] user_data The user data to be passed to the callback function
458 * @return 0 on success, otherwise a negative error value
459 * @retval #VC_ERROR_NONE Successful
460 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
461 * @retval #VC_ERROR_INVALID_STATE Invalid state
463 * @pre The state should be #VC_STATE_INITIALIZED.
465 * @see vc_current_language_changed_cb()
466 * @see vc_widget_unset_current_language_changed_cb()
468 int vc_widget_set_current_language_changed_cb(vc_h vc, vc_current_language_changed_cb callback, void* user_data);
471 * @brief Unregisters the callback function.
473 * @param[in] vc_widget The voice control handle
475 * @return 0 on success, otherwise a negative error value
476 * @retval #VC_ERROR_NONE Successful
477 * @retval #VC_ERROR_INVALID_STATE Invalid state
479 * @pre The state should be #VC_STATE_INITIALIZED.
481 * @see vc_widget_set_current_language_changed_cb()
483 int vc_widget_unset_current_language_changed_cb(vc_h vc);
486 * @brief Registers a callback function for an error occurred.
488 * @param[in] vc_widget The voice control handle
490 * @param[in] callback Callback function to register
491 * @param[in] user_data The user data to be passed to the callback function
493 * @return 0 on success, otherwise a negative error value
494 * @retval #VC_ERROR_NONE Successful
495 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
496 * @retval #VC_ERROR_INVALID_STATE Invalid state
498 * @pre The state should be #VC_STATE_INITIALIZED.
501 * @see vc_widget_unset_error_cb()
503 int vc_widget_set_error_cb(vc_h vc, vc_error_cb callback, void* user_data);
506 * @brief Unregisters the callback function.
508 * @param[in] vc_widget The voice control handle
510 * @return 0 on success, otherwise a negative error value
511 * @retval #VC_ERROR_NONE Successful
512 * @retval #VC_ERROR_INVALID_STATE Invalid state
514 * @pre The state should be #VC_STATE_INITIALIZED.
516 * @see vc_widget_set_error_cb()
518 int vc_widget_unset_error_cb(vc_h vc);
521 * @brief Sets option for obtain ASR result as dictation via result callback.
524 * @privilege %http://tizen.org/privilege/recorder
526 * @param[in] enable enable to get asr result
528 * @return 0 on success, otherwise a negative error value
529 * @retval #VC_ERROR_NONE Successful
530 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
531 * @retval #VC_ERROR_INVALID_STATE Invalid state
532 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
533 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
535 * @pre The state should be #VC_STATE_READY.
538 int vc_widget_enable_asr_result(vc_h vc, bool enable);
541 * @brief Registers a callback function for an asr result.
543 * @param[in] callback Callback function to register
544 * @param[in] user_data The user data to be passed to the callback function
546 * @return 0 on success, otherwise a negative error value
547 * @retval #VC_ERROR_NONE Successful
548 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
549 * @retval #VC_ERROR_INVALID_STATE Invalid state
551 * @pre The state should be #VC_STATE_INITIALIZED.
553 * @see vc_asr_result_cb()
554 * @see vc_widget_enable_asr_result()
555 * @see vc_widget_unset_asr_result_cb()
557 int vc_widget_set_asr_result_cb(vc_h vc, vc_asr_result_cb callback, void* user_data);
560 * @brief Unregisters the callback function.
562 * @return 0 on success, otherwise a negative error value
563 * @retval #VC_ERROR_NONE Successful
564 * @retval #VC_ERROR_INVALID_STATE Invalid state
566 * @pre The state should be #VC_STATE_INITIALIZED.
568 * @see vc_widget_set_asr_result_cb()
570 int vc_widget_unset_asr_result_cb(vc_h vc);
580 #endif /* __VOICE_CONTROL_WIDGET_H__ */