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_MANAGER_H__
19 #define __VOICE_CONTROL_MANAGER_H__
21 #include <voice_control_command.h>
22 #include <voice_control_command_expand.h>
23 #include <voice_control_common.h>
26 * @addtogroup VOICE_CONTROL_MANAGER
37 * @brief Definition of bluetooth audio-in type.
39 #define VC_AUDIO_TYPE_BLUETOOTH "VC_AUDIO_ID_BLUETOOTH" /**< Bluetooth audio type */
42 * @brief Definition of Wi-Fi audio-in type.
44 #define VC_AUDIO_TYPE_WIFI "VC_AUDIO_ID_WIFI" /**< Wi-Fi audio type */
47 * @brief Definition for foreground command type.
48 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
50 #define VC_COMMAND_TYPE_FOREGROUND 1
53 * @brief Definition for background command type.
54 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
56 #define VC_COMMAND_TYPE_BACKGROUND 2
59 * @brief Definition for widget command type.
60 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
62 #define VC_COMMAND_TYPE_WIDGET 3
65 * @brief Definition for system command type.
66 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
68 #define VC_COMMAND_TYPE_SYSTEM 4
71 * @brief Definition for exclusive command type.
72 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
74 #define VC_COMMAND_TYPE_SYSTEM_BACKGROUND 5
77 * @brief Definitions for exclusive command type.
80 #define VC_COMMAND_TYPE_EXCLUSIVE 6
83 * @brief Definition for none message.
85 #define VC_RESULT_MESSAGE_NONE "vc.result.message.none"
88 * @brief Definition for failed recognition because the speech is too loud to listen.
90 #define VC_RESULT_MESSAGE_ERROR_TOO_LOUD "vc.result.message.error.too.loud"
93 * @brief Enumerations of recognition mode.
96 VC_RECOGNITION_MODE_STOP_BY_SILENCE, /**< Default mode */
97 VC_RECOGNITION_MODE_RESTART_AFTER_REJECT, /**< Restart recognition after rejected result */
98 VC_RECOGNITION_MODE_RESTART_CONTINUOUSLY, /**< Continuously restart recognition - not support yet*/
99 VC_RECOGNITION_MODE_MANUAL /**< Start and stop manually without silence */
100 } vc_recognition_mode_e;
103 * @brief Enumerations of send event type.
106 VC_SEND_EVENT_TYPE_TEXT, /**< send text event to vc engine*/
107 VC_SEND_EVENT_TYPE_LIST_EVENT, /**< send list event to vc engine */
108 VC_SEND_EVENT_TYPE_HAPTIC_EVENT /**< send haptic event to vc engine */
109 } vc_send_event_type_e;
112 * @brief Enumerations of pre result event.
115 VC_PRE_RESULT_EVENT_FINAL_RESULT = 0,
116 VC_PRE_RESULT_EVENT_PARTIAL_RESULT,
117 VC_PRE_RESULT_EVENT_ERROR
118 } vc_pre_result_event_e;
121 * @brief Called when client gets the all recognition results from vc-daemon.
123 * @remark temp_command is valid in callback function.
125 * @param[in] event The result event
126 * @param[in] vc_cmd_list_h Command list handle
127 * @param[in] result Command text
128 * @param[in] msg Engine message (e.g. #VC_RESULT_MESSAGE_NONE, #VC_RESULT_MESSAGE_ERROR_TOO_LOUD)
129 * @param[in] user_data The user data passed from the callback registration function
131 * @return @c true to release command to client, \n @c false to wait for selecting command.
132 * @pre An application registers callback function using vc_mgr_set_all_result_cb().
134 * @see vc_mgr_set_all_result_cb()
135 * @see vc_mgr_unset_all_result_cb()
137 typedef bool (*vc_mgr_all_result_cb)(vc_result_event_e event, vc_cmd_list_h vc_cmd_list,
138 const char* result, const char* msg, void *user_data);
141 * @brief Called when client gets the pre recognition results(partial ASR) from vc-daemon.
143 * @param[in] event The pre result event
144 * @param[in] result ASR text
145 * @param[in] user_data The user data passed from the callback registration function
147 * @pre An application registers callback function using vc_mgr_set_pre_result_cb().
149 * @see vc_mgr_set_pre_result_cb()
150 * @see vc_mgr_unset_pre_result_cb()
152 typedef void (*vc_mgr_pre_result_cb)(vc_pre_result_event_e event, const char* result, void *user_data);
155 * @brief Called when user speaking is detected.
157 * @param[in] user_data The user data passed from the callback registration function
159 * @pre An application registers callback function using vc_mgr_set_speech_detected_cb().
161 * @see vc_mgr_set_speech_detected_cb()
162 * @see vc_mgr_unset_speech_detected_cb()
164 typedef void (*vc_mgr_begin_speech_detected_cb)(void *user_data);
168 * @brief Called when user request dialog
170 * @param[in] pid Pid of VC client to request dialog
171 * @param[in] disp_text Text that wants to be displayed
172 * @param[in] utt_text Text that wants to be spoken
173 * @param[in] continuous Continue dialog session
174 * @param[in] user_data The user data passed from the callback registration function
176 * @pre An application registers callback function using vc_mgr_set_dialog_request_cb().
178 * @see vc_mgr_set_dialog_request_cb()
179 * @see vc_mgr_unset_dialog_request_cb()
181 typedef void (*vc_mgr_dialog_request_cb)(int pid, const char* disp_text, const char* utt_text, bool continuous, void *user_data);
184 * @brief Called when engine set private data to manager client
186 * @param[in] key Private key
187 * @param[in] data Private data
188 * @param[in] user_data The user data passed from the callback registration function
190 * @pre An application registers callback function using vc_mgr_set_private_data_set_cb().
192 * @see vc_mgr_set_private_data_set_cb()
193 * @see vc_mgr_unset_private_data_set_cb()
195 typedef int (*vc_mgr_private_data_set_cb)(const char* key, const char* data, void *user_data);
198 * @brief Called when engine request private data from manager client
200 * @param[in] key Private key
201 * @param[out] data Private data
202 * @param[in] user_data The user data passed from the callback registration function
204 * @pre An application registers callback function using vc_mgr_set_private_data_requested_cb().
206 * @see vc_mgr_set_private_data_requested_cb()
207 * @see vc_mgr_unset_private_data_requested_cb()
209 typedef int (*vc_mgr_private_data_requested_cb)(const char* key, char** data, void *user_data);
213 * @brief Initialize voice control manager.
215 * @remarks If the function succeeds, @a vc mgr must be released with vc_mgr_deinitialize().
217 * @return 0 on success, otherwise a negative error value
218 * @retval #VC_ERROR_NONE Successful
219 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
220 * @retval #VC_ERROR_OPERATION_FAILED Operation fail
222 * @pre The state should be #VC_STATE_NONE.
223 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
225 * @see vc_mgr_deinitialize()
227 int vc_mgr_initialize();
230 * @brief Deinitialize voice control manager.
232 * @return 0 on success, otherwise a negative error value
233 * @retval #VC_ERROR_NONE Successful
234 * @retval #VC_ERROR_INVALID_STATE Invalid state
236 * @post If this function is called, the state will be #VC_STATE_NONE.
238 * @see vc_mgr_deinitialize()
240 int vc_mgr_deinitialize();
243 * @brief Connects the voice control service.
245 * @return 0 on success, otherwise a negative error value
246 * @retval #VC_ERROR_NONE Successful
247 * @retval #VC_ERROR_INVALID_STATE Invalid state
249 * @pre The state should be #VC_STATE_INITIALIZED.
250 * @post If this function is called, the state will be #VC_STATE_READY.
252 * @see vc_mgr_unprepare()
254 int vc_mgr_prepare();
257 * @brief Disconnects the vc-daemon.
259 * @return 0 on success, otherwise a negative error value
260 * @retval #VC_ERROR_NONE Successful
261 * @retval #VC_ERROR_INVALID_STATE Invalid state
263 * @pre The state should be #VC_STATE_READY.
264 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
266 * @see vc_mgr_prepare()
268 int vc_mgr_unprepare();
271 * @brief Retrieves all supported languages using callback function.
273 * @param[in] callback Callback function to invoke
274 * @param[in] user_data The user data to be passed to the callback function
276 * @return 0 on success, otherwise a negative error value
277 * @retval #VC_ERROR_NONE Successful
278 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
279 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
280 * @retval #VC_ERROR_INVALID_STATE Invalid state
282 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
283 * @post This function invokes vc_supported_language_cb() repeatedly for getting languages.
285 * @see vc_supported_language_cb()
286 * @see vc_mgr_get_current_language()
288 int vc_mgr_foreach_supported_languages(vc_supported_language_cb callback, void* user_data);
291 * @brief Gets current language set by user.
293 * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it.
295 * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
296 * followed by ISO 639-1 for the two-letter language code. \n
297 * For example, "ko_KR" for Korean, "en_US" for American English.
299 * @return 0 on success, otherwise a negative error value
300 * @retval #VC_ERROR_NONE Successful
301 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
302 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
303 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
304 * @retval #VC_ERROR_INVALID_STATE Invalid state
306 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
308 * @see vc_mgr_foreach_supported_languages()
310 int vc_mgr_get_current_language(char** language);
313 * @brief Gets current state of voice control manager.
315 * @param[out] state The current state
317 * @return 0 on success, otherwise a negative error value
318 * @retval #VC_ERROR_NONE Successful
319 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
321 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
323 * @see vc_state_changed_cb()
324 * @see vc_set_state_changed_cb()
326 int vc_mgr_get_state(vc_state_e* state);
329 * @brief Gets current state of voice control service.
331 * @param[out] state The current state
333 * @return 0 on success, otherwise a negative error value
334 * @retval #VC_ERROR_NONE Successful
335 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
337 * @pre The state should be #VC_STATE_READY.
339 * @see vc_mgr_start()
341 * @see vc_mgr_cancel()
342 * @see vc_set_service_state_changed_cb()
343 * @see vc_unset_service_state_changed_cb()
345 int vc_mgr_get_service_state(vc_service_state_e* state);
348 * @brief Sets demandable client list.
350 * @param[in] rule demandable client list rule path
352 * @return 0 on success, otherwise a negative error value
353 * @retval #VC_ERROR_NONE Successful
354 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
355 * @retval #VC_ERROR_INVALID_STATE Invalid state
357 * @pre The state should be #VC_STATE_READY.
359 * @see vc_mgr_get_demandable_client_rule()
361 int vc_mgr_set_demandable_client_rule(const char* rule);
364 * @brief Gets demandable client list.
366 * @return 0 on success, otherwise a negative error value
367 * @retval #VC_ERROR_NONE Successful
368 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
369 * @retval #VC_ERROR_INVALID_STATE Invalid state
371 * @pre The state should be #VC_STATE_READY.
373 * @see vc_mgr_set_demandable_client_rule()
375 int vc_mgr_unset_demandable_client_rule();
378 * @brief Checks whether the command format is supported.
380 * @param[in] format The command format
381 * @param[out] support The result status @c true = supported, @c false = not supported
383 * @return 0 on success, otherwise a negative error value
384 * @retval #VC_ERROR_NONE Successful
385 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
386 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
387 * @retval #VC_ERROR_INVALID_STATE Invalid state
389 * @pre The state should be #VC_STATE_READY.
391 int vc_mgr_is_command_format_supported(vc_cmd_format_e format, bool* support);
394 * @brief Sets system or exclusive commands.
396 * @remarks The command type is valid for VC_COMMAND_TYPE_SYSTEM or VC_COMMAND_TYPE_EXCLUSIVE.
397 * The commands should include type, command text, format.
399 * @param[in] vc_cmd_list The command list handle
401 * @return 0 on success, otherwise a negative error value
402 * @retval #VC_ERROR_NONE Successful
403 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
404 * @retval #VC_ERROR_INVALID_STATE Invalid state
406 * @pre The state should be #VC_STATE_READY.
408 * @see vc_mgr_unset_command_list()
410 int vc_mgr_set_command_list(vc_cmd_list_h vc_cmd_list);
413 * @brief Unsets system or exclusive commands.
415 * @return 0 on success, otherwise a negative error value
416 * @retval #VC_ERROR_NONE Successful
417 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
418 * @retval #VC_ERROR_INVALID_STATE Invalid state
420 * @pre The state should be #VC_STATE_READY.
422 * @see vc_mgr_set_command_list()
424 int vc_mgr_unset_command_list();
427 * @brief Sets commands from file.
429 * @remarks The commands should include type, command text, format.
431 * @param[in] vc_cmd_list The command list handle
432 * @param[in] type Command type
434 * @return 0 on success, otherwise a negative error value
435 * @retval #VC_ERROR_NONE Successful
436 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
437 * @retval #VC_ERROR_INVALID_STATE Invalid state
438 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
440 * @pre The state should be #VC_STATE_READY.
442 * @see vc_mgr_unset_command_list()
444 int vc_mgr_set_command_list_from_file(const char* file_path, int type);
447 * @brief Sets background commands of preloaded app from file.
449 * @remarks The command type is valid for VC_COMMAND_TYPE_BACKGROUND
450 * The commands should include type, command text, format.
452 * @param[in] vc_cmd_list The command list handle
454 * @return 0 on success, otherwise a negative error value
455 * @retval #VC_ERROR_NONE Successful
456 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
457 * @retval #VC_ERROR_INVALID_STATE Invalid state
458 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
460 * @pre The state should be #VC_STATE_READY.
462 * @see vc_mgr_unset_command_list()
464 int vc_mgr_set_preloaded_commands_from_file(const char* file_path);
467 * @brief Retrieves all available commands.
469 * @remarks If the function succeeds, @a vc_cmd_list must be released with vc_cmd_list_destroy(vc_cmd_list, true).
471 * @param[in] vc_cmd_list The command list
473 * @return 0 on success, otherwise a negative error value
474 * @retval #VC_ERROR_NONE Successful
475 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
476 * @retval #VC_ERROR_INVALID_STATE Invalid state
477 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
479 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
481 int vc_mgr_get_current_commands(vc_cmd_list_h* vc_cmd_list);
484 * @brief Sets audio in type.
486 * @param[in] audio_id audio type (e.g. #VC_AUDIO_TYPE_BLUETOOTH or usb device id)
488 * @return 0 on success, otherwise a negative error value
489 * @retval #VC_ERROR_NONE Successful
490 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
491 * @retval #VC_ERROR_INVALID_STATE Invalid state
492 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
494 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
496 * @see vc_mgr_get_audio_type()
498 int vc_mgr_set_audio_type(const char* audio_id);
501 * @brief Gets audio-in type.
503 * @remarks audio_id must be released using free() when it is no longer required.
505 * @param[out] audio_id audio id (e.g. #VC_AUDIO_TYPE_BLUETOOTH or usb device id)
507 * @return 0 on success, otherwise a negative error value
508 * @retval #VC_ERROR_NONE Successful
509 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
510 * @retval #VC_ERROR_INVALID_STATE Invalid state
511 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
513 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
515 * @see vc_mgr_set_audio_type()
517 int vc_mgr_get_audio_type(char** audio_id);
520 * @brief Sets recognition mode.
522 * @param[in] mode recognition mode (e.g. #VC_RECOGNITION_MODE_STOP_BY_SILENCE is default value)
524 * @return 0 on success, otherwise a negative error value
525 * @retval #VC_ERROR_NONE Successful
526 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
527 * @retval #VC_ERROR_INVALID_STATE Invalid state
529 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
531 * @see vc_mgr_set_recognition_mode()
533 int vc_mgr_set_recognition_mode(vc_recognition_mode_e mode);
536 * @brief Gets recognition mode.
538 * @param[out] mode recognition mode
540 * @return 0 on success, otherwise a negative error value
541 * @retval #VC_ERROR_NONE Successful
542 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
543 * @retval #VC_ERROR_INVALID_STATE Invalid state
545 * @pre The state should be #VC_STATE_READY.
547 * @see vc_mgr_get_recognition_mode()
549 int vc_mgr_get_recognition_mode(vc_recognition_mode_e* mode);
552 * @brief Sets private data between app and engine.
554 * @param[in] key Private key
555 * @param[in] data Private data
557 * @return 0 on success, otherwise a negative error value
558 * @retval #VC_ERROR_NONE Successful
559 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
560 * @retval #VC_ERROR_INVALID_STATE Invalid state
561 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
563 * @pre The service state should be #VC_SERVICE_STATE_READY.
565 int vc_mgr_set_private_data(const char* key, const char* data);
568 * @brief Gets private data between app and engine.
570 * @remarks data must be released using free() when it is no longer required.
572 * @param[in] key Private key
573 * @param[out] data Private data
575 * @return 0 on success, otherwise a negative error value
576 * @retval #VC_ERROR_NONE Successful
577 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
578 * @retval #VC_ERROR_INVALID_STATE Invalid state
579 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
581 * @pre The service state should be #VC_SERVICE_STATE_READY.
583 int vc_mgr_get_private_data(const char* key, char** data);
586 * @brief Sets domain such as agent or device type.
588 * @param[in] domain Available agent or device type
590 * @return 0 on success, otherwise a negative error value
591 * @retval #VC_ERROR_NONE Successful
592 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
593 * @retval #VC_ERROR_INVALID_STATE Invalid state
594 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
596 * @pre The service state should be #VC_SERVICE_STATE_READY.
598 int vc_mgr_set_domain(const char* domain);
601 * @brief Request to do action as if utterence is spoken.
603 * @param[in] type Event type
604 * @param[in] send_event The string for send event
606 * @return 0 on success, otherwise a negative error value
607 * @retval #VC_ERROR_NONE Successful
608 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
609 * @retval #VC_ERROR_INVALID_STATE Invalid state
610 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
612 * @pre The service state should be #VC_SERVICE_STATE_READY.
614 int vc_mgr_do_action(vc_send_event_type_e type, char* send_event);
617 * @brief Starts recognition.
619 * @remarks The default recognition mode is #VC_RECOGNITION_MODE_STOP_BY_SILENCE. \n
620 * If you want to use other mode, you can set mode with vc_mgr_set_recognition_mode().
622 * @param[in] exclusive_command_option Exclusive command option
624 * @return 0 on success, otherwise a negative error value
625 * @retval #VC_ERROR_NONE Successful
626 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
627 * @retval #VC_ERROR_INVALID_STATE Invalid state
628 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
630 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
631 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
632 * If this function succeeds, the service state will be #VC_SERVICE_STATE_RECORDING.
635 * @see vc_mgr_cancel()
636 * @see vc_service_state_changed_cb()
637 * @see vc_mgr_set_recognition_mode()
638 * @see vc_mgr_get_recognition_mode()
640 int vc_mgr_start(bool exclusive_command_option);
643 * @brief Stop recognition.
645 * @return 0 on success, otherwise a negative error value
646 * @retval #VC_ERROR_NONE Successful
647 * @retval #VC_ERROR_INVALID_STATE Invalid state
648 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
650 * @pre The service state should be #VC_SERVICE_STATE_RECORDING.
651 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
652 * If this function succeeds, the service state will be #VC_SERVICE_STATE_PROCESSING.
654 * @see vc_mgr_start()
655 * @see vc_mgr_cancel()
656 * @see vc_service_state_changed_cb()
657 * @see vc_mgr_result_cb()
662 * @brief Cancels recognition.
664 * @return 0 on success, otherwise a negative error value
665 * @retval #VC_ERROR_NONE Successful
666 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
667 * @retval #VC_ERROR_INVALID_STATE Invalid state
668 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
670 * @pre The service state should be #VC_SERVICE_STATE_RECORDING or #VC_SERVICE_STATE_PROCESSING.
671 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
672 * If this function succeeds, the service state will be #VC_SERVICE_STATE_READY.
674 * @see vc_mgr_start()
676 * @see vc_service_state_changed_cb()
681 * @brief Gets the microphone volume during recording.
683 * @param[out] volume Recording volume
685 * @return 0 on success, otherwise a negative error value
686 * @retval #VC_ERROR_NONE Successful
687 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
688 * @retval #VC_ERROR_INVALID_STATE Invalid state
689 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
691 * @pre The service state should be #VC_SERVICE_STATE_RECORDING.
693 * @see vc_mgr_start()
695 int vc_mgr_get_recording_volume(float* volume);
698 * @brief Select valid result from all results.
700 * @param[in] vc_cmd_list The valid result list
702 * @return 0 on success, otherwise a negative error value
703 * @retval #VC_ERROR_NONE Successful
704 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
705 * @retval #VC_ERROR_INVALID_STATE Invalid state
706 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
708 * @pre vc_mgr_all_result_cb() should be called
710 * @see vc_mgr_all_result_cb()
712 int vc_mgr_set_selected_results(vc_cmd_list_h vc_cmd_list);
716 * @brief Registers a callback function for getting recognition result.
718 * @param[in] callback Callback function to register
719 * @param[in] user_data The user data to be passed to the callback function
721 * @return 0 on success, otherwise a negative error value
722 * @retval #VC_ERROR_NONE Successful
723 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
724 * @retval #VC_ERROR_INVALID_STATE Invalid state
726 * @pre The state should be #VC_STATE_INITIALIZED.
728 * @see vc_mgr_all_result_cb()
729 * @see vc_mgr_unset_all_result_cb()
731 int vc_mgr_set_all_result_cb(vc_mgr_all_result_cb callback, void* user_data);
734 * @brief Unregisters the callback function.
736 * @return 0 on success, otherwise a negative error value
737 * @retval #VC_ERROR_NONE Successful
738 * @retval #VC_ERROR_INVALID_STATE Invalid state
740 * @pre The state should be #VC_STATE_INITIALIZED.
742 * @see vc_mgr_set_all_result_cb()
744 int vc_mgr_unset_all_result_cb();
747 * @brief Registers a callback function for getting pre recognition result.
749 * @param[in] callback Callback function to register
750 * @param[in] user_data The user data to be passed to the callback function
752 * @return 0 on success, otherwise a negative error value
753 * @retval #VC_ERROR_NONE Successful
754 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
755 * @retval #VC_ERROR_INVALID_STATE Invalid state
757 * @pre The state should be #VC_STATE_INITIALIZED.
759 * @see vc_mgr_pre_result_cb()
760 * @see vc_mgr_unset_pre_result_cb()
762 int vc_mgr_set_pre_result_cb(vc_mgr_pre_result_cb callback, void* user_data);
765 * @brief Unregisters the callback function.
767 * @return 0 on success, otherwise a negative error value
768 * @retval #VC_ERROR_NONE Successful
769 * @retval #VC_ERROR_INVALID_STATE Invalid state
771 * @pre The state should be #VC_STATE_INITIALIZED.
773 * @see vc_mgr_set_pre_result_cb()
775 int vc_mgr_unset_pre_result_cb();
778 * @brief Registers a callback function for getting system or exclusive recognition result.
780 * @param[in] callback Callback function to register
781 * @param[in] user_data The user data to be passed to the callback function
783 * @return 0 on success, otherwise a negative error value
784 * @retval #VC_ERROR_NONE Successful
785 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
786 * @retval #VC_ERROR_INVALID_STATE Invalid state
788 * @pre The state should be #VC_STATE_INITIALIZED.
790 * @see vc_result_cb()
791 * @see vc_mgr_unset_result_cb()
793 int vc_mgr_set_result_cb(vc_result_cb callback, void* user_data);
796 * @brief Unregisters the callback function.
798 * @return 0 on success, otherwise a negative error value
799 * @retval #VC_ERROR_NONE Successful
800 * @retval #VC_ERROR_INVALID_STATE Invalid state
802 * @pre The state should be #VC_STATE_INITIALIZED.
804 * @see vc_mgr_set_result_cb()
806 int vc_mgr_unset_result_cb();
809 * @brief Registers a callback function to be called when state is changed.
811 * @param[in] callback Callback function to register
812 * @param[in] user_data The user data to be passed to the callback function
814 * @return 0 on success, otherwise a negative error value
815 * @retval #VC_ERROR_NONE Successful
816 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
817 * @retval #VC_ERROR_INVALID_STATE Invalid state
819 * @pre The state should be #VC_STATE_INITIALIZED.
821 * @see vc_state_changed_cb()
822 * @see vc_mgr_unset_state_changed_cb()
824 int vc_mgr_set_state_changed_cb(vc_state_changed_cb callback, void* user_data);
827 * @brief Unregisters the callback function.
829 * @return 0 on success, otherwise a negative error value
830 * @retval #VC_ERROR_NONE Successful
831 * @retval #VC_ERROR_INVALID_STATE Invalid state
833 * @pre The state should be #VC_STATE_INITIALIZED.
835 * @see vc_mgr_set_state_changed_cb()
837 int vc_mgr_unset_state_changed_cb();
840 * @brief Registers a callback function to be called when state is changed.
842 * @param[in] callback Callback function to register
843 * @param[in] user_data The user data to be passed to the callback function
845 * @return 0 on success, otherwise a negative error value
846 * @retval #VC_ERROR_NONE Successful
847 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
848 * @retval #VC_ERROR_INVALID_STATE Invalid state
850 * @pre The state should be #VC_STATE_INITIALIZED.
852 * @see vc_service_state_changed_cb()
853 * @see vc_mgr_unset_service_state_changed_cb()
855 int vc_mgr_set_service_state_changed_cb(vc_service_state_changed_cb callback, void* user_data);
858 * @brief Unregisters the callback function.
860 * @return 0 on success, otherwise a negative error value
861 * @retval #VC_ERROR_NONE Successful
862 * @retval #VC_ERROR_INVALID_STATE Invalid state
864 * @pre The state should be #VC_STATE_INITIALIZED.
866 * @see vc_mgr_set_service_state_changed_cb()
868 int vc_mgr_unset_service_state_changed_cb();
871 * @brief Registers a callback function to be called when begin of speech is detected.
873 * @param[in] callback Callback function to register
874 * @param[in] user_data The user data to be passed to the callback function
876 * @return 0 on success, otherwise a negative error value
877 * @retval #VC_ERROR_NONE Successful
878 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
879 * @retval #VC_ERROR_INVALID_STATE Invalid state
881 * @pre The state should be #VC_STATE_INITIALIZED.
883 * @see vc_mgr_begin_speech_detected_cb()
884 * @see vc_mgr_unset_speech_detected_cb()
886 int vc_mgr_set_speech_detected_cb(vc_mgr_begin_speech_detected_cb callback, void* user_data);
889 * @brief Unregisters the callback function.
891 * @return 0 on success, otherwise a negative error value
892 * @retval #VC_ERROR_NONE Successful
893 * @retval #VC_ERROR_INVALID_STATE Invalid state
895 * @pre The state should be #VC_STATE_INITIALIZED.
897 * @see vc_mgr_set_speech_detected_cb()
899 int vc_mgr_unset_speech_detected_cb();
902 * @brief Registers a callback function to be called when current language is changed.
904 * @param[in] callback Callback function to register
905 * @param[in] user_data The user data to be passed to the callback function
907 * @return 0 on success, otherwise a negative error value
908 * @retval #VC_ERROR_NONE Successful
909 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
910 * @retval #VC_ERROR_INVALID_STATE Invalid state
912 * @pre The state should be #VC_STATE_INITIALIZED.
914 * @see vc_current_language_changed_cb()
915 * @see vc_mgr_unset_current_language_changed_cb()
917 int vc_mgr_set_current_language_changed_cb(vc_current_language_changed_cb callback, void* user_data);
920 * @brief Unregisters the callback function.
922 * @return 0 on success, otherwise a negative error value
923 * @retval #VC_ERROR_NONE Successful
924 * @retval #VC_ERROR_INVALID_STATE Invalid state
926 * @pre The state should be #VC_STATE_INITIALIZED.
928 * @see vc_mgr_set_current_language_changed_cb()
930 int vc_mgr_unset_current_language_changed_cb();
933 * @brief Gets the current error message.
935 * @remarks This function should be called during as vc error callback. If not, the error as operation failure will be returned. \n
936 * If the function succeeds, @a err_msg must be released using free() when it is no longer required.
938 * @param[out] err_msg The current error message
940 * @return 0 on success, otherwise a negative error value
941 * @retval #VC_ERROR_NONE Successful
942 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
943 * @retval #VC_ERROR_INVALID_STATE Invalid state
944 * @retval $VC_ERROR_OPERATION_FAILED Operation failure
945 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
949 int vc_mgr_get_error_message(char** err_msg);
952 * @brief Registers a callback function to be called when an error occurred.
954 * @param[in] callback Callback function to register
955 * @param[in] user_data The user data to be passed to the callback function
957 * @return 0 on success, otherwise a negative error value
958 * @retval #VC_ERROR_NONE Successful
959 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
960 * @retval #VC_ERROR_INVALID_STATE Invalid state
962 * @pre The state should be #VC_STATE_INITIALIZED.
965 * @see vc_mgr_unset_error_cb()
967 int vc_mgr_set_error_cb(vc_error_cb callback, void* user_data);
970 * @brief Unregisters the callback function.
972 * @return 0 on success, otherwise a negative error value
973 * @retval #VC_ERROR_NONE Successful
974 * @retval #VC_ERROR_INVALID_STATE Invalid state
976 * @pre The state should be #VC_STATE_INITIALIZED.
978 * @see vc_mgr_set_error_cb()
980 int vc_mgr_unset_error_cb();
984 * @brief Registers a callback function to be called when dialog requests.
986 * @param[in] callback Callback function to register
987 * @param[in] user_data The user data to be passed to the callback function
989 * @return 0 on success, otherwise a negative error value
990 * @retval #VC_ERROR_NONE Successful
991 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
992 * @retval #VC_ERROR_INVALID_STATE Invalid state
994 * @pre The state should be #VC_STATE_INITIALIZED.
996 * @see vc_mgr_unset_dialog_request_cb()
998 int vc_mgr_set_dialog_request_cb(vc_mgr_dialog_request_cb callback, void* user_data);
1001 * @brief Unregisters the callback function.
1003 * @return 0 on success, otherwise a negative error value
1004 * @retval #VC_ERROR_NONE Successful
1005 * @retval #VC_ERROR_INVALID_STATE Invalid state
1007 * @pre The state should be #VC_STATE_INITIALIZED.
1009 * @see vc_mgr_set_dialog_request_cb()
1011 int vc_mgr_unset_dialog_request_cb();
1014 * @brief Enable command type as candidate command.
1016 * @return 0 on success, otherwise a negative error value
1017 * @retval #VC_ERROR_NONE Successful
1018 * @retval #VC_ERROR_INVALID_STATE Invalid state
1020 * @pre The state should be #VC_STATE_READY.
1022 * @see vc_mgr_disable_command_type()
1024 int vc_mgr_enable_command_type(int cmd_type);
1027 * @brief Disable command type as candidate command.
1029 * @return 0 on success, otherwise a negative error value
1030 * @retval #VC_ERROR_NONE Successful
1031 * @retval #VC_ERROR_INVALID_STATE Invalid state
1033 * @pre The state should be #VC_STATE_READY.
1035 * @see vc_mgr_enable_command_type()
1037 int vc_mgr_disable_command_type(int cmd_type);
1040 * @brief Registers a callback function to be called when engine set private data.
1042 * @param[in] callback Callback function to register
1043 * @param[in] user_data The user data to be passed to the callback function
1045 * @return 0 on success, otherwise a negative error value
1046 * @retval #VC_ERROR_NONE Successful
1047 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
1048 * @retval #VC_ERROR_INVALID_STATE Invalid state
1050 * @pre The state should be #VC_STATE_INITIALIZED.
1052 * @see vc_private_data_set_cb()
1053 * @see vc_mgr_unset_private_data_set_cb()
1055 int vc_mgr_set_private_data_set_cb(vc_mgr_private_data_set_cb callback, void* user_data);
1058 * @brief Unregisters the callback function.
1060 * @return 0 on success, otherwise a negative error value
1061 * @retval #VC_ERROR_NONE Successful
1062 * @retval #VC_ERROR_INVALID_STATE Invalid state
1064 * @pre The state should be #VC_STATE_INITIALIZED.
1066 * @see vc_mgr_set_private_data_set_cb()
1068 int vc_mgr_unset_private_data_set_cb();
1071 * @brief Registers a callback function to be called when engine request private data.
1073 * @param[in] callback Callback function to register
1074 * @param[in] user_data The user data to be passed to the callback function
1076 * @return 0 on success, otherwise a negative error value
1077 * @retval #VC_ERROR_NONE Successful
1078 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
1079 * @retval #VC_ERROR_INVALID_STATE Invalid state
1081 * @pre The state should be #VC_STATE_INITIALIZED.
1083 * @see vc_private_data_requested_cb()
1084 * @see vc_mgr_unset_private_data_requested_cb()
1086 int vc_mgr_set_private_data_requested_cb(vc_mgr_private_data_requested_cb callback, void* user_data);
1089 * @brief Unregisters the callback function.
1091 * @return 0 on success, otherwise a negative error value
1092 * @retval #VC_ERROR_NONE Successful
1093 * @retval #VC_ERROR_INVALID_STATE Invalid state
1095 * @pre The state should be #VC_STATE_INITIALIZED.
1097 * @see vc_mgr_set_private_data_requested_cb()
1099 int vc_mgr_unset_private_data_requested_cb();
1109 #endif /* __VOICE_CONTROL_MANAGER_H__ */