include/voice_control_manager.h

   1 /*
   2 * Copyright (c) 2011-2015 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   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
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  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.
  15 */
  16
  17
  18 #ifndef __VOICE_CONTROL_MANAGER_H__
  19 #define __VOICE_CONTROL_MANAGER_H__
  20
  21 #include <voice_control_command.h>
  22 #include <voice_control_command_expand.h>
  23 #include <voice_control_common.h>
  24
  25 /**
  26 * @addtogroup VOICE_CONTROL_MANAGER
  27 * @{
  28 */
  29
  30 #ifdef __cplusplus
  31 extern "C"
  32 {
  33 #endif
  34
  35
  36 /**
  37  * @brief Definition of bluetooth audio-in type.
  38 */
  39 #define VC_AUDIO_TYPE_BLUETOOTH         "VC_AUDIO_ID_BLUETOOTH"         /**< Bluetooth audio type */
  40
  41 /**
  42  * @brief Definition of Wi-Fi audio-in type.
  43 */
  44 #define VC_AUDIO_TYPE_WIFI              "VC_AUDIO_ID_WIFI"              /**< Wi-Fi audio type */
  45
  46 /**
  47 * @brief Definition for foreground command type.
  48 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  49 */
  50 #define VC_COMMAND_TYPE_FOREGROUND      1
  51
  52 /**
  53 * @brief Definition for background command type.
  54 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  55 */
  56 #define VC_COMMAND_TYPE_BACKGROUND      2
  57
  58 /**
  59 * @brief Definition for widget command type.
  60 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  61 */
  62 #define VC_COMMAND_TYPE_WIDGET          3
  63
  64 /**
  65 * @brief Definition for system command type.
  66 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  67 */
  68 #define VC_COMMAND_TYPE_SYSTEM          4
  69
  70 /**
  71 * @brief Definition for exclusive command type.
  72 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  73 */
  74 #define VC_COMMAND_TYPE_SYSTEM_BACKGROUND       5
  75
  76 /**
  77 * @brief Definitions for exclusive command type.
  78 * @since_tizen 2.4
  79 */
  80 #define VC_COMMAND_TYPE_EXCLUSIVE       6
  81
  82 /**
  83 * @brief Definition for none message.
  84 */
  85 #define VC_RESULT_MESSAGE_NONE                  "vc.result.message.none"
  86
  87 /**
  88 * @brief Definition for failed recognition because the speech is too loud to listen.
  89 */
  90 #define VC_RESULT_MESSAGE_ERROR_TOO_LOUD        "vc.result.message.error.too.loud"
  91
  92 /**
  93 * @brief Enumerations of recognition mode.
  94 */
  95 typedef enum {
  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;
 101
 102 /**
 103 * @brief Enumerations of send event type.
 104 */
 105 typedef enum {
 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;
 110
 111 /**
 112 * @brief Enumerations of pre result event.
 113 */
 114 typedef enum {
 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;
 119
 120 /**
 121 * @brief Called when client gets the all recognition results from vc-daemon.
 122 *
 123 * @remark temp_command is valid in callback function.
 124 *
 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
 130 *
 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().
 133 *
 134 * @see vc_mgr_set_all_result_cb()
 135 * @see vc_mgr_unset_all_result_cb()
 136 */
 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);
 139
 140 /**
 141 * @brief Called when client gets the pre recognition results(partial ASR) from vc-daemon.
 142 *
 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
 146 *
 147 * @pre An application registers callback function using vc_mgr_set_pre_result_cb().
 148 *
 149 * @see vc_mgr_set_pre_result_cb()
 150 * @see vc_mgr_unset_pre_result_cb()
 151 */
 152 typedef void (*vc_mgr_pre_result_cb)(vc_pre_result_event_e event, const char* result, void *user_data);
 153
 154 /**
 155 * @brief Called when user speaking is detected.
 156 *
 157 * @param[in] user_data The user data passed from the callback registration function
 158 *
 159 * @pre An application registers callback function using vc_mgr_set_speech_detected_cb().
 160 *
 161 * @see vc_mgr_set_speech_detected_cb()
 162 * @see vc_mgr_unset_speech_detected_cb()
 163 */
 164 typedef void (*vc_mgr_begin_speech_detected_cb)(void *user_data);
 165
 166
 167 /**
 168 * @brief Called when user request dialog
 169 *
 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
 175 *
 176 * @pre An application registers callback function using vc_mgr_set_dialog_request_cb().
 177 *
 178 * @see vc_mgr_set_dialog_request_cb()
 179 * @see vc_mgr_unset_dialog_request_cb()
 180 */
 181 typedef void (*vc_mgr_dialog_request_cb)(int pid, const char* disp_text, const char* utt_text, bool continuous, void *user_data);
 182
 183 /**
 184 * @brief Called when engine set private data to manager client
 185 *
 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
 189 *
 190 * @pre An application registers callback function using vc_mgr_set_private_data_set_cb().
 191 *
 192 * @see vc_mgr_set_private_data_set_cb()
 193 * @see vc_mgr_unset_private_data_set_cb()
 194 */
 195 typedef int (*vc_mgr_private_data_set_cb)(const char* key, const char* data, void *user_data);
 196
 197 /**
 198 * @brief Called when engine request private data from manager client
 199 *
 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
 203 *
 204 * @pre An application registers callback function using vc_mgr_set_private_data_requested_cb().
 205 *
 206 * @see vc_mgr_set_private_data_requested_cb()
 207 * @see vc_mgr_unset_private_data_requested_cb()
 208 */
 209 typedef int (*vc_mgr_private_data_requested_cb)(const char* key, char** data, void *user_data);
 210
 211
 212 /**
 213 * @brief Initialize voice control manager.
 214 *
 215 * @remarks If the function succeeds, @a vc mgr must be released with vc_mgr_deinitialize().
 216 *
 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
 221 *
 222 * @pre The state should be #VC_STATE_NONE.
 223 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
 224 *
 225 * @see vc_mgr_deinitialize()
 226 */
 227 int vc_mgr_initialize();
 228
 229 /**
 230 * @brief Deinitialize voice control manager.
 231 *
 232 * @return 0 on success, otherwise a negative error value
 233 * @retval #VC_ERROR_NONE Successful
 234 * @retval #VC_ERROR_INVALID_STATE Invalid state
 235 *
 236 * @post If this function is called, the state will be #VC_STATE_NONE.
 237 *
 238 * @see vc_mgr_deinitialize()
 239 */
 240 int vc_mgr_deinitialize();
 241
 242 /**
 243 * @brief Connects the voice control service.
 244 *
 245 * @return 0 on success, otherwise a negative error value
 246 * @retval #VC_ERROR_NONE Successful
 247 * @retval #VC_ERROR_INVALID_STATE Invalid state
 248 *
 249 * @pre The state should be #VC_STATE_INITIALIZED.
 250 * @post If this function is called, the state will be #VC_STATE_READY.
 251 *
 252 * @see vc_mgr_unprepare()
 253 */
 254 int vc_mgr_prepare();
 255
 256 /**
 257 * @brief Disconnects the vc-daemon.
 258 *
 259 * @return 0 on success, otherwise a negative error value
 260 * @retval #VC_ERROR_NONE Successful
 261 * @retval #VC_ERROR_INVALID_STATE Invalid state
 262 *
 263 * @pre The state should be #VC_STATE_READY.
 264 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
 265 *
 266 * @see vc_mgr_prepare()
 267 */
 268 int vc_mgr_unprepare();
 269
 270 /**
 271 * @brief Retrieves all supported languages using callback function.
 272 *
 273 * @param[in] callback Callback function to invoke
 274 * @param[in] user_data The user data to be passed to the callback function
 275 *
 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
 281 *
 282 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
 283 * @post This function invokes vc_supported_language_cb() repeatedly for getting languages.
 284 *
 285 * @see vc_supported_language_cb()
 286 * @see vc_mgr_get_current_language()
 287 */
 288 int vc_mgr_foreach_supported_languages(vc_supported_language_cb callback, void* user_data);
 289
 290 /**
 291 * @brief Gets current language set by user.
 292 *
 293 * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it.
 294 *
 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.
 298 *
 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
 305 *
 306 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
 307 *
 308 * @see vc_mgr_foreach_supported_languages()
 309 */
 310 int vc_mgr_get_current_language(char** language);
 311
 312 /**
 313 * @brief Gets current state of voice control manager.
 314 *
 315 * @param[out] state The current state
 316 *
 317 * @return 0 on success, otherwise a negative error value
 318 * @retval #VC_ERROR_NONE Successful
 319 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 320 *
 321 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
 322 *
 323 * @see vc_state_changed_cb()
 324 * @see vc_set_state_changed_cb()
 325 */
 326 int vc_mgr_get_state(vc_state_e* state);
 327
 328 /**
 329 * @brief Gets current state of voice control service.
 330 *
 331 * @param[out] state The current state
 332 *
 333 * @return 0 on success, otherwise a negative error value
 334 * @retval #VC_ERROR_NONE Successful
 335 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 336 *
 337 * @pre The state should be #VC_STATE_READY.
 338 *
 339 * @see vc_mgr_start()
 340 * @see vc_mgr_stop()
 341 * @see vc_mgr_cancel()
 342 * @see vc_set_service_state_changed_cb()
 343 * @see vc_unset_service_state_changed_cb()
 344 */
 345 int vc_mgr_get_service_state(vc_service_state_e* state);
 346
 347 /**
 348 * @brief Sets demandable client list.
 349 *
 350 * @param[in] rule demandable client list rule path
 351 *
 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
 356 *
 357 * @pre The state should be #VC_STATE_READY.
 358 *
 359 * @see vc_mgr_get_demandable_client_rule()
 360 */
 361 int vc_mgr_set_demandable_client_rule(const char* rule);
 362
 363 /**
 364 * @brief Gets demandable client list.
 365 *
 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
 370 *
 371 * @pre The state should be #VC_STATE_READY.
 372 *
 373 * @see vc_mgr_set_demandable_client_rule()
 374 */
 375 int vc_mgr_unset_demandable_client_rule();
 376
 377 /**
 378 * @brief Checks whether the command format is supported.
 379 *
 380 * @param[in] format The command format
 381 * @param[out] support The result status @c true = supported, @c false = not supported
 382 *
 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
 388 *
 389 * @pre The state should be #VC_STATE_READY.
 390 */
 391 int vc_mgr_is_command_format_supported(vc_cmd_format_e format, bool* support);
 392
 393 /**
 394 * @brief Sets system or exclusive commands.
 395 *
 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.
 398 *
 399 * @param[in] vc_cmd_list The command list handle
 400 *
 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
 405 *
 406 * @pre The state should be #VC_STATE_READY.
 407 *
 408 * @see vc_mgr_unset_command_list()
 409 */
 410 int vc_mgr_set_command_list(vc_cmd_list_h vc_cmd_list);
 411
 412 /**
 413 * @brief Unsets system or exclusive commands.
 414 *
 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
 419 *
 420 * @pre The state should be #VC_STATE_READY.
 421 *
 422 * @see vc_mgr_set_command_list()
 423 */
 424 int vc_mgr_unset_command_list();
 425
 426 /**
 427 * @brief Sets commands from file.
 428 *
 429 * @remarks The commands should include type, command text, format.
 430 *
 431 * @param[in] vc_cmd_list The command list handle
 432 * @param[in] type Command type
 433 *
 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
 439 *
 440 * @pre The state should be #VC_STATE_READY.
 441 *
 442 * @see vc_mgr_unset_command_list()
 443 */
 444 int vc_mgr_set_command_list_from_file(const char* file_path, int type);
 445
 446 /**
 447 * @brief Sets background commands of preloaded app from file.
 448 *
 449 * @remarks The command type is valid for VC_COMMAND_TYPE_BACKGROUND
 450 *       The commands should include type, command text, format.
 451 *
 452 * @param[in] vc_cmd_list The command list handle
 453 *
 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
 459 *
 460 * @pre The state should be #VC_STATE_READY.
 461 *
 462 * @see vc_mgr_unset_command_list()
 463 */
 464 int vc_mgr_set_preloaded_commands_from_file(const char* file_path);
 465
 466 /**
 467 * @brief Retrieves all available commands.
 468 *
 469 * @remarks If the function succeeds, @a vc_cmd_list must be released with vc_cmd_list_destroy(vc_cmd_list, true).
 470 *
 471 * @param[in] vc_cmd_list The command list
 472 *
 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
 478 *
 479 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 480 */
 481 int vc_mgr_get_current_commands(vc_cmd_list_h* vc_cmd_list);
 482
 483 /**
 484 * @brief Sets audio in type.
 485 *
 486 * @param[in] audio_id audio type (e.g. #VC_AUDIO_TYPE_BLUETOOTH or usb device id)
 487 *
 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
 493 *
 494 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 495 *
 496 * @see vc_mgr_get_audio_type()
 497 */
 498 int vc_mgr_set_audio_type(const char* audio_id);
 499
 500 /**
 501 * @brief Gets audio-in type.
 502 *
 503 * @remarks audio_id must be released using free() when it is no longer required.
 504 *
 505 * @param[out] audio_id audio id (e.g. #VC_AUDIO_TYPE_BLUETOOTH or usb device id)
 506 *
 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
 512 *
 513 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 514 *
 515 * @see vc_mgr_set_audio_type()
 516 */
 517 int vc_mgr_get_audio_type(char** audio_id);
 518
 519 /**
 520 * @brief Sets recognition mode.
 521 *
 522 * @param[in] mode recognition mode (e.g. #VC_RECOGNITION_MODE_STOP_BY_SILENCE is default value)
 523 *
 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
 528 *
 529 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 530 *
 531 * @see vc_mgr_set_recognition_mode()
 532 */
 533 int vc_mgr_set_recognition_mode(vc_recognition_mode_e mode);
 534
 535 /**
 536 * @brief Gets recognition mode.
 537 *
 538 * @param[out] mode recognition mode
 539 *
 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
 544 *
 545 * @pre The state should be #VC_STATE_READY.
 546 *
 547 * @see vc_mgr_get_recognition_mode()
 548 */
 549 int vc_mgr_get_recognition_mode(vc_recognition_mode_e* mode);
 550
 551 /**
 552 * @brief Sets private data between app and engine.
 553 *
 554 * @param[in] key Private key
 555 * @param[in] data Private data
 556 *
 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
 562 *
 563 * @pre The service state should be #VC_SERVICE_STATE_READY.
 564 */
 565 int vc_mgr_set_private_data(const char* key, const char* data);
 566
 567 /**
 568 * @brief Gets private data between app and engine.
 569 *
 570 * @remarks data must be released using free() when it is no longer required.
 571 *
 572 * @param[in] key Private key
 573 * @param[out] data Private data
 574 *
 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
 580 *
 581 * @pre The service state should be #VC_SERVICE_STATE_READY.
 582 */
 583 int vc_mgr_get_private_data(const char* key, char** data);
 584
 585 /**
 586 * @brief Sets domain such as agent or device type.
 587 *
 588 * @param[in] domain Available agent or device type
 589 *
 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
 595 *
 596 * @pre The service state should be #VC_SERVICE_STATE_READY.
 597 */
 598 int vc_mgr_set_domain(const char* domain);
 599
 600 /**
 601 * @brief Request to do action as if utterence is spoken.
 602 *
 603 * @param[in] type Event type
 604 * @param[in] send_event  The string for send event
 605 *
 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
 611 *
 612 * @pre The service state should be #VC_SERVICE_STATE_READY.
 613 */
 614 int vc_mgr_do_action(vc_send_event_type_e type, char* send_event);
 615
 616 /**
 617 * @brief Starts recognition.
 618 *
 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().
 621 *
 622 * @param[in] exclusive_command_option Exclusive command option
 623 *
 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
 629 *
 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.
 633 *
 634 * @see vc_mgr_stop()
 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()
 639 */
 640 int vc_mgr_start(bool exclusive_command_option);
 641
 642 /**
 643 * @brief Stop recognition.
 644 *
 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
 649 *
 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.
 653 *
 654 * @see vc_mgr_start()
 655 * @see vc_mgr_cancel()
 656 * @see vc_service_state_changed_cb()
 657 * @see vc_mgr_result_cb()
 658 */
 659 int vc_mgr_stop();
 660
 661 /**
 662 * @brief Cancels recognition.
 663 *
 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
 669 *
 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.
 673 *
 674 * @see vc_mgr_start()
 675 * @see vc_mgr_stop()
 676 * @see vc_service_state_changed_cb()
 677 */
 678 int vc_mgr_cancel();
 679
 680 /**
 681 * @brief Gets the microphone volume during recording.
 682 *
 683 * @param[out] volume Recording volume
 684 *
 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
 690 *
 691 * @pre The service state should be #VC_SERVICE_STATE_RECORDING.
 692 *
 693 * @see vc_mgr_start()
 694 */
 695 int vc_mgr_get_recording_volume(float* volume);
 696
 697 /**
 698 * @brief Select valid result from all results.
 699 *
 700 * @param[in] vc_cmd_list The valid result list
 701 *
 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
 707 *
 708 * @pre vc_mgr_all_result_cb() should be called
 709 *
 710 * @see vc_mgr_all_result_cb()
 711 */
 712 int vc_mgr_set_selected_results(vc_cmd_list_h vc_cmd_list);
 713
 714
 715 /**
 716 * @brief Registers a callback function for getting recognition result.
 717 *
 718 * @param[in] callback Callback function to register
 719 * @param[in] user_data The user data to be passed to the callback function
 720 *
 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
 725 *
 726 * @pre The state should be #VC_STATE_INITIALIZED.
 727 *
 728 * @see vc_mgr_all_result_cb()
 729 * @see vc_mgr_unset_all_result_cb()
 730 */
 731 int vc_mgr_set_all_result_cb(vc_mgr_all_result_cb callback, void* user_data);
 732
 733 /**
 734 * @brief Unregisters the callback function.
 735 *
 736 * @return 0 on success, otherwise a negative error value
 737 * @retval #VC_ERROR_NONE Successful
 738 * @retval #VC_ERROR_INVALID_STATE Invalid state
 739 *
 740 * @pre The state should be #VC_STATE_INITIALIZED.
 741 *
 742 * @see vc_mgr_set_all_result_cb()
 743 */
 744 int vc_mgr_unset_all_result_cb();
 745
 746 /**
 747 * @brief Registers a callback function for getting pre recognition result.
 748 *
 749 * @param[in] callback Callback function to register
 750 * @param[in] user_data The user data to be passed to the callback function
 751 *
 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
 756 *
 757 * @pre The state should be #VC_STATE_INITIALIZED.
 758 *
 759 * @see vc_mgr_pre_result_cb()
 760 * @see vc_mgr_unset_pre_result_cb()
 761 */
 762 int vc_mgr_set_pre_result_cb(vc_mgr_pre_result_cb callback, void* user_data);
 763
 764 /**
 765 * @brief Unregisters the callback function.
 766 *
 767 * @return 0 on success, otherwise a negative error value
 768 * @retval #VC_ERROR_NONE Successful
 769 * @retval #VC_ERROR_INVALID_STATE Invalid state
 770 *
 771 * @pre The state should be #VC_STATE_INITIALIZED.
 772 *
 773 * @see vc_mgr_set_pre_result_cb()
 774 */
 775 int vc_mgr_unset_pre_result_cb();
 776
 777 /**
 778 * @brief Registers a callback function for getting system or exclusive recognition result.
 779 *
 780 * @param[in] callback Callback function to register
 781 * @param[in] user_data The user data to be passed to the callback function
 782 *
 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
 787 *
 788 * @pre The state should be #VC_STATE_INITIALIZED.
 789 *
 790 * @see vc_result_cb()
 791 * @see vc_mgr_unset_result_cb()
 792 */
 793 int vc_mgr_set_result_cb(vc_result_cb callback, void* user_data);
 794
 795 /**
 796 * @brief Unregisters the callback function.
 797 *
 798 * @return 0 on success, otherwise a negative error value
 799 * @retval #VC_ERROR_NONE Successful
 800 * @retval #VC_ERROR_INVALID_STATE Invalid state
 801 *
 802 * @pre The state should be #VC_STATE_INITIALIZED.
 803 *
 804 * @see vc_mgr_set_result_cb()
 805 */
 806 int vc_mgr_unset_result_cb();
 807
 808 /**
 809 * @brief Registers a callback function to be called when state is changed.
 810 *
 811 * @param[in] callback Callback function to register
 812 * @param[in] user_data The user data to be passed to the callback function
 813 *
 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
 818 *
 819 * @pre The state should be #VC_STATE_INITIALIZED.
 820 *
 821 * @see vc_state_changed_cb()
 822 * @see vc_mgr_unset_state_changed_cb()
 823 */
 824 int vc_mgr_set_state_changed_cb(vc_state_changed_cb callback, void* user_data);
 825
 826 /**
 827 * @brief Unregisters the callback function.
 828 *
 829 * @return 0 on success, otherwise a negative error value
 830 * @retval #VC_ERROR_NONE Successful
 831 * @retval #VC_ERROR_INVALID_STATE Invalid state
 832 *
 833 * @pre The state should be #VC_STATE_INITIALIZED.
 834 *
 835 * @see vc_mgr_set_state_changed_cb()
 836 */
 837 int vc_mgr_unset_state_changed_cb();
 838
 839 /**
 840 * @brief Registers a callback function to be called when state is changed.
 841 *
 842 * @param[in] callback Callback function to register
 843 * @param[in] user_data The user data to be passed to the callback function
 844 *
 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
 849 *
 850 * @pre The state should be #VC_STATE_INITIALIZED.
 851 *
 852 * @see vc_service_state_changed_cb()
 853 * @see vc_mgr_unset_service_state_changed_cb()
 854 */
 855 int vc_mgr_set_service_state_changed_cb(vc_service_state_changed_cb callback, void* user_data);
 856
 857 /**
 858 * @brief Unregisters the callback function.
 859 *
 860 * @return 0 on success, otherwise a negative error value
 861 * @retval #VC_ERROR_NONE Successful
 862 * @retval #VC_ERROR_INVALID_STATE Invalid state
 863 *
 864 * @pre The state should be #VC_STATE_INITIALIZED.
 865 *
 866 * @see vc_mgr_set_service_state_changed_cb()
 867 */
 868 int vc_mgr_unset_service_state_changed_cb();
 869
 870 /**
 871 * @brief Registers a callback function to be called when begin of speech is detected.
 872 *
 873 * @param[in] callback Callback function to register
 874 * @param[in] user_data The user data to be passed to the callback function
 875 *
 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
 880 *
 881 * @pre The state should be #VC_STATE_INITIALIZED.
 882 *
 883 * @see vc_mgr_begin_speech_detected_cb()
 884 * @see vc_mgr_unset_speech_detected_cb()
 885 */
 886 int vc_mgr_set_speech_detected_cb(vc_mgr_begin_speech_detected_cb callback, void* user_data);
 887
 888 /**
 889 * @brief Unregisters the callback function.
 890 *
 891 * @return 0 on success, otherwise a negative error value
 892 * @retval #VC_ERROR_NONE Successful
 893 * @retval #VC_ERROR_INVALID_STATE Invalid state
 894 *
 895 * @pre The state should be #VC_STATE_INITIALIZED.
 896 *
 897 * @see vc_mgr_set_speech_detected_cb()
 898 */
 899 int vc_mgr_unset_speech_detected_cb();
 900
 901 /**
 902 * @brief Registers a callback function to be called when current language is changed.
 903 *
 904 * @param[in] callback Callback function to register
 905 * @param[in] user_data The user data to be passed to the callback function
 906 *
 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
 911 *
 912 * @pre The state should be #VC_STATE_INITIALIZED.
 913 *
 914 * @see vc_current_language_changed_cb()
 915 * @see vc_mgr_unset_current_language_changed_cb()
 916 */
 917 int vc_mgr_set_current_language_changed_cb(vc_current_language_changed_cb callback, void* user_data);
 918
 919 /**
 920 * @brief Unregisters the callback function.
 921 *
 922 * @return 0 on success, otherwise a negative error value
 923 * @retval #VC_ERROR_NONE Successful
 924 * @retval #VC_ERROR_INVALID_STATE Invalid state
 925 *
 926 * @pre The state should be #VC_STATE_INITIALIZED.
 927 *
 928 * @see vc_mgr_set_current_language_changed_cb()
 929 */
 930 int vc_mgr_unset_current_language_changed_cb();
 931
 932 /**
 933 * @brief Gets the current error message.
 934 *
 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.
 937 *
 938 * @param[out] err_msg The current error message
 939 *
 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
 946 *
 947 * @see vc_error_cb()
 948 */
 949 int vc_mgr_get_error_message(char** err_msg);
 950
 951 /**
 952 * @brief Registers a callback function to be called when an error occurred.
 953 *
 954 * @param[in] callback Callback function to register
 955 * @param[in] user_data The user data to be passed to the callback function
 956 *
 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
 961 *
 962 * @pre The state should be #VC_STATE_INITIALIZED.
 963 *
 964 * @see vc_error_cb()
 965 * @see vc_mgr_unset_error_cb()
 966 */
 967 int vc_mgr_set_error_cb(vc_error_cb callback, void* user_data);
 968
 969 /**
 970 * @brief Unregisters the callback function.
 971 *
 972 * @return 0 on success, otherwise a negative error value
 973 * @retval #VC_ERROR_NONE Successful
 974 * @retval #VC_ERROR_INVALID_STATE Invalid state
 975 *
 976 * @pre The state should be #VC_STATE_INITIALIZED.
 977 *
 978 * @see vc_mgr_set_error_cb()
 979 */
 980 int vc_mgr_unset_error_cb();
 981
 982
 983 /**
 984 * @brief Registers a callback function to be called when dialog requests.
 985 *
 986 * @param[in] callback Callback function to register
 987 * @param[in] user_data The user data to be passed to the callback function
 988 *
 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
 993 *
 994 * @pre The state should be #VC_STATE_INITIALIZED.
 995 *
 996 * @see vc_mgr_unset_dialog_request_cb()
 997 */
 998 int vc_mgr_set_dialog_request_cb(vc_mgr_dialog_request_cb callback, void* user_data);
 999
1000 /**
1001 * @brief Unregisters the callback function.
1002 *
1003 * @return 0 on success, otherwise a negative error value
1004 * @retval #VC_ERROR_NONE Successful
1005 * @retval #VC_ERROR_INVALID_STATE Invalid state
1006 *
1007 * @pre The state should be #VC_STATE_INITIALIZED.
1008 *
1009 * @see vc_mgr_set_dialog_request_cb()
1010 */
1011 int vc_mgr_unset_dialog_request_cb();
1012
1013 /**
1014 * @brief Enable command type as candidate command.
1015 *
1016 * @return 0 on success, otherwise a negative error value
1017 * @retval #VC_ERROR_NONE Successful
1018 * @retval #VC_ERROR_INVALID_STATE Invalid state
1019 *
1020 * @pre The state should be #VC_STATE_READY.
1021 *
1022 * @see vc_mgr_disable_command_type()
1023 */
1024 int vc_mgr_enable_command_type(int cmd_type);
1025
1026 /**
1027 * @brief Disable command type as candidate command.
1028 *
1029 * @return 0 on success, otherwise a negative error value
1030 * @retval #VC_ERROR_NONE Successful
1031 * @retval #VC_ERROR_INVALID_STATE Invalid state
1032 *
1033 * @pre The state should be #VC_STATE_READY.
1034 *
1035 * @see vc_mgr_enable_command_type()
1036 */
1037 int vc_mgr_disable_command_type(int cmd_type);
1038
1039 /**
1040 * @brief Registers a callback function to be called when engine set private data.
1041 *
1042 * @param[in] callback Callback function to register
1043 * @param[in] user_data The user data to be passed to the callback function
1044 *
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
1049 *
1050 * @pre The state should be #VC_STATE_INITIALIZED.
1051 *
1052 * @see vc_private_data_set_cb()
1053 * @see vc_mgr_unset_private_data_set_cb()
1054 */
1055 int vc_mgr_set_private_data_set_cb(vc_mgr_private_data_set_cb callback, void* user_data);
1056
1057 /**
1058 * @brief Unregisters the callback function.
1059 *
1060 * @return 0 on success, otherwise a negative error value
1061 * @retval #VC_ERROR_NONE Successful
1062 * @retval #VC_ERROR_INVALID_STATE Invalid state
1063 *
1064 * @pre The state should be #VC_STATE_INITIALIZED.
1065 *
1066 * @see vc_mgr_set_private_data_set_cb()
1067 */
1068 int vc_mgr_unset_private_data_set_cb();
1069
1070 /**
1071 * @brief Registers a callback function to be called when engine request private data.
1072 *
1073 * @param[in] callback Callback function to register
1074 * @param[in] user_data The user data to be passed to the callback function
1075 *
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
1080 *
1081 * @pre The state should be #VC_STATE_INITIALIZED.
1082 *
1083 * @see vc_private_data_requested_cb()
1084 * @see vc_mgr_unset_private_data_requested_cb()
1085 */
1086 int vc_mgr_set_private_data_requested_cb(vc_mgr_private_data_requested_cb callback, void* user_data);
1087
1088 /**
1089 * @brief Unregisters the callback function.
1090 *
1091 * @return 0 on success, otherwise a negative error value
1092 * @retval #VC_ERROR_NONE Successful
1093 * @retval #VC_ERROR_INVALID_STATE Invalid state
1094 *
1095 * @pre The state should be #VC_STATE_INITIALIZED.
1096 *
1097 * @see vc_mgr_set_private_data_requested_cb()
1098 */
1099 int vc_mgr_unset_private_data_requested_cb();
1100
1101 #ifdef __cplusplus
1102 }
1103 #endif
1104
1105 /**
1106  * @}@}
1107  */
1108
1109 #endif /* __VOICE_CONTROL_MANAGER_H__ */
1110