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 audio-in type.
  38 */
  39 #define VC_AUDIO_TYPE_BLUETOOTH         "VC_AUDIO_ID_BLUETOOTH"         /**< Bluetooth audio type */
  40
  41 /**
  42  * @brief Definition of audio-in type.
  43 */
  44 #define VC_AUDIO_TYPE_MSF               "VC_AUDIO_ID_MSF"               /**< MSF (wifi) 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 /**
 185 * @brief Initialize voice control manager.
 186 *
 187 * @remarks If the function succeeds, @a vc mgr must be released with vc_mgr_deinitialize().
 188 *
 189 * @return 0 on success, otherwise a negative error value
 190 * @retval #VC_ERROR_NONE Successful
 191 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 192 * @retval #VC_ERROR_OPERATION_FAILED Operation fail
 193 *
 194 * @pre The state should be #VC_STATE_NONE.
 195 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
 196 *
 197 * @see vc_mgr_deinitialize()
 198 */
 199 int vc_mgr_initialize();
 200
 201 /**
 202 * @brief Deinitialize voice control manager.
 203 *
 204 * @return 0 on success, otherwise a negative error value
 205 * @retval #VC_ERROR_NONE Successful
 206 * @retval #VC_ERROR_INVALID_STATE Invalid state
 207 *
 208 * @post If this function is called, the state will be #VC_STATE_NONE.
 209 *
 210 * @see vc_mgr_deinitialize()
 211 */
 212 int vc_mgr_deinitialize();
 213
 214 /**
 215 * @brief Connects the voice control service.
 216 *
 217 * @return 0 on success, otherwise a negative error value
 218 * @retval #VC_ERROR_NONE Successful
 219 * @retval #VC_ERROR_INVALID_STATE Invalid state
 220 *
 221 * @pre The state should be #VC_STATE_INITIALIZED.
 222 * @post If this function is called, the state will be #VC_STATE_READY.
 223 *
 224 * @see vc_mgr_unprepare()
 225 */
 226 int vc_mgr_prepare();
 227
 228 /**
 229 * @brief Disconnects the vc-daemon.
 230 *
 231 * @return 0 on success, otherwise a negative error value
 232 * @retval #VC_ERROR_NONE Successful
 233 * @retval #VC_ERROR_INVALID_STATE Invalid state
 234 *
 235 * @pre The state should be #VC_STATE_READY.
 236 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
 237 *
 238 * @see vc_mgr_prepare()
 239 */
 240 int vc_mgr_unprepare();
 241
 242 /**
 243 * @brief Retrieves all supported languages using callback function.
 244 *
 245 * @param[in] callback Callback function to invoke
 246 * @param[in] user_data The user data to be passed to the callback function
 247 *
 248 * @return 0 on success, otherwise a negative error value
 249 * @retval #VC_ERROR_NONE Successful
 250 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 251 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 252 * @retval #VC_ERROR_INVALID_STATE Invalid state
 253 *
 254 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
 255 * @post This function invokes vc_supported_language_cb() repeatedly for getting languages.
 256 *
 257 * @see vc_supported_language_cb()
 258 * @see vc_mgr_get_current_language()
 259 */
 260 int vc_mgr_foreach_supported_languages(vc_supported_language_cb callback, void* user_data);
 261
 262 /**
 263 * @brief Gets current language set by user.
 264 *
 265 * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it.
 266 *
 267 * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
 268 *                       followed by ISO 639-1 for the two-letter language code. \n
 269 *                       For example, "ko_KR" for Korean, "en_US" for American English.
 270 *
 271 * @return 0 on success, otherwise a negative error value
 272 * @retval #VC_ERROR_NONE Successful
 273 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 274 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 275 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 276 * @retval #VC_ERROR_INVALID_STATE Invalid state
 277 *
 278 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
 279 *
 280 * @see vc_mgr_foreach_supported_languages()
 281 */
 282 int vc_mgr_get_current_language(char** language);
 283
 284 /**
 285 * @brief Gets current state of voice control manager.
 286 *
 287 * @param[out] state The current state
 288 *
 289 * @return 0 on success, otherwise a negative error value
 290 * @retval #VC_ERROR_NONE Successful
 291 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 292 *
 293 * @pre The state should NOT be #VC_SERVICE_STATE_NONE.
 294 *
 295 * @see vc_state_changed_cb()
 296 * @see vc_set_state_changed_cb()
 297 */
 298 int vc_mgr_get_state(vc_state_e* state);
 299
 300 /**
 301 * @brief Gets current state of voice control service.
 302 *
 303 * @param[out] state The current state
 304 *
 305 * @return 0 on success, otherwise a negative error value
 306 * @retval #VC_ERROR_NONE Successful
 307 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 308 *
 309 * @pre The state should be #VC_STATE_READY.
 310 *
 311 * @see vc_mgr_start()
 312 * @see vc_mgr_stop()
 313 * @see vc_mgr_cancel()
 314 * @see vc_set_service_state_changed_cb()
 315 * @see vc_unset_service_state_changed_cb()
 316 */
 317 int vc_mgr_get_service_state(vc_service_state_e* state);
 318
 319 /**
 320 * @brief Sets demandable client list.
 321 *
 322 * @param[in] rule demandable client list rule path
 323 *
 324 * @return 0 on success, otherwise a negative error value
 325 * @retval #VC_ERROR_NONE Successful
 326 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 327 * @retval #VC_ERROR_INVALID_STATE Invalid state
 328 *
 329 * @pre The state should be #VC_STATE_READY.
 330 *
 331 * @see vc_mgr_get_demandable_client_rule()
 332 */
 333 int vc_mgr_set_demandable_client_rule(const char* rule);
 334
 335 /**
 336 * @brief Gets demandable client list.
 337 *
 338 * @return 0 on success, otherwise a negative error value
 339 * @retval #VC_ERROR_NONE Successful
 340 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 341 * @retval #VC_ERROR_INVALID_STATE Invalid state
 342 *
 343 * @pre The state should be #VC_STATE_READY.
 344 *
 345 * @see vc_mgr_set_demandable_client_rule()
 346 */
 347 int vc_mgr_unset_demandable_client_rule();
 348
 349 /**
 350 * @brief Checks whether the command format is supported.
 351 *
 352 * @param[in] format The command format
 353 * @param[out] support The result status @c true = supported, @c false = not supported
 354 *
 355 * @return 0 on success, otherwise a negative error value
 356 * @retval #VC_ERROR_NONE Successful
 357 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 358 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 359 * @retval #VC_ERROR_INVALID_STATE Invalid state
 360 *
 361 * @pre The state should be #VC_STATE_READY.
 362 */
 363 int vc_mgr_is_command_format_supported(vc_cmd_format_e format, bool* support);
 364
 365 /**
 366 * @brief Sets system or exclusive commands.
 367 *
 368 * @remarks The command type is valid for VC_COMMAND_TYPE_SYSTEM or VC_COMMAND_TYPE_EXCLUSIVE.
 369 *       The commands should include type, command text, format.
 370 *
 371 * @param[in] vc_cmd_list The command list handle
 372 *
 373 * @return 0 on success, otherwise a negative error value
 374 * @retval #VC_ERROR_NONE Successful
 375 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 376 * @retval #VC_ERROR_INVALID_STATE Invalid state
 377 *
 378 * @pre The state should be #VC_STATE_READY.
 379 *
 380 * @see vc_mgr_unset_command_list()
 381 */
 382 int vc_mgr_set_command_list(vc_cmd_list_h vc_cmd_list);
 383
 384 /**
 385 * @brief Unsets system or exclusive commands.
 386 *
 387 * @return 0 on success, otherwise a negative error value
 388 * @retval #VC_ERROR_NONE Successful
 389 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 390 * @retval #VC_ERROR_INVALID_STATE Invalid state
 391 *
 392 * @pre The state should be #VC_STATE_READY.
 393 *
 394 * @see vc_mgr_set_command_list()
 395 */
 396 int vc_mgr_unset_command_list();
 397
 398 /**
 399 * @brief Sets commands from file.
 400 *
 401 * @remarks The commands should include type, command text, format.
 402 *
 403 * @param[in] vc_cmd_list The command list handle
 404 * @param[in] type Command type
 405 *
 406 * @return 0 on success, otherwise a negative error value
 407 * @retval #VC_ERROR_NONE Successful
 408 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 409 * @retval #VC_ERROR_INVALID_STATE Invalid state
 410 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 411 *
 412 * @pre The state should be #VC_STATE_READY.
 413 *
 414 * @see vc_mgr_unset_command_list()
 415 */
 416 int vc_mgr_set_command_list_from_file(const char* file_path, int type);
 417
 418 /**
 419 * @brief Sets background commands of preloaded app from file.
 420 *
 421 * @remarks The command type is valid for VC_COMMAND_TYPE_BACKGROUND
 422 *       The commands should include type, command text, format.
 423 *
 424 * @param[in] vc_cmd_list The command list handle
 425 *
 426 * @return 0 on success, otherwise a negative error value
 427 * @retval #VC_ERROR_NONE Successful
 428 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 429 * @retval #VC_ERROR_INVALID_STATE Invalid state
 430 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 431 *
 432 * @pre The state should be #VC_STATE_READY.
 433 *
 434 * @see vc_mgr_unset_command_list()
 435 */
 436 int vc_mgr_set_preloaded_commands_from_file(const char* file_path);
 437
 438 /**
 439 * @brief Retrieves all available commands.
 440 *
 441 * @remarks If the function succeeds, @a vc_cmd_list must be released with vc_cmd_list_destroy(vc_cmd_list, true).
 442 *
 443 * @param[in] vc_cmd_list The command list
 444 *
 445 * @return 0 on success, otherwise a negative error value
 446 * @retval #VC_ERROR_NONE Successful
 447 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 448 * @retval #VC_ERROR_INVALID_STATE Invalid state
 449 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 450 *
 451 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 452 */
 453 int vc_mgr_get_current_commands(vc_cmd_list_h* vc_cmd_list);
 454
 455 /**
 456 * @brief Sets audio in type.
 457 *
 458 * @param[in] audio_id audio type (e.g. #VC_AUDIO_TYPE_BLUETOOTH or usb device id)
 459 *
 460 * @return 0 on success, otherwise a negative error value
 461 * @retval #VC_ERROR_NONE Successful
 462 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 463 * @retval #VC_ERROR_INVALID_STATE Invalid state
 464 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 465 *
 466 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 467 *
 468 * @see vc_mgr_get_audio_type()
 469 */
 470 int vc_mgr_set_audio_type(const char* audio_id);
 471
 472 /**
 473 * @brief Gets audio-in type.
 474 *
 475 * @remarks audio_id must be released using free() when it is no longer required.
 476 *
 477 * @param[out] audio_id audio id (e.g. #VC_AUDIO_TYPE_BLUETOOTH or usb device id)
 478 *
 479 * @return 0 on success, otherwise a negative error value
 480 * @retval #VC_ERROR_NONE Successful
 481 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 482 * @retval #VC_ERROR_INVALID_STATE Invalid state
 483 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 484 *
 485 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 486 *
 487 * @see vc_mgr_set_audio_type()
 488 */
 489 int vc_mgr_get_audio_type(char** audio_id);
 490
 491 /**
 492 * @brief Sets recognition mode.
 493 *
 494 * @param[in] mode recognition mode (e.g. #VC_RECOGNITION_MODE_STOP_BY_SILENCE is default value)
 495 *
 496 * @return 0 on success, otherwise a negative error value
 497 * @retval #VC_ERROR_NONE Successful
 498 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 499 * @retval #VC_ERROR_INVALID_STATE Invalid state
 500 *
 501 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 502 *
 503 * @see vc_mgr_set_recognition_mode()
 504 */
 505 int vc_mgr_set_recognition_mode(vc_recognition_mode_e mode);
 506
 507 /**
 508 * @brief Gets recognition mode.
 509 *
 510 * @param[out] mode recognition mode
 511 *
 512 * @return 0 on success, otherwise a negative error value
 513 * @retval #VC_ERROR_NONE Successful
 514 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 515 * @retval #VC_ERROR_INVALID_STATE Invalid state
 516 *
 517 * @pre The state should be #VC_STATE_READY.
 518 *
 519 * @see vc_mgr_get_recognition_mode()
 520 */
 521 int vc_mgr_get_recognition_mode(vc_recognition_mode_e* mode);
 522
 523 /**
 524 * @brief Sets private data between app and engine.
 525 *
 526 * @param[in] key Private key
 527 * @param[in] data Private data
 528 *
 529 * @return 0 on success, otherwise a negative error value
 530 * @retval #VC_ERROR_NONE Successful
 531 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
 532 * @retval #VC_ERROR_INVALID_STATE Invalid state
 533 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 534 *
 535 * @pre The service state should be #VC_SERVICE_STATE_READY.
 536 */
 537 int vc_mgr_set_private_data(const char* key, const char* data);
 538
 539 /**
 540 * @brief Gets private data between app and engine.
 541 *
 542 * @remarks data must be released using free() when it is no longer required.
 543 *
 544 * @param[in] key Private key
 545 * @param[out] data Private data
 546 *
 547 * @return 0 on success, otherwise a negative error value
 548 * @retval #VC_ERROR_NONE Successful
 549 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
 550 * @retval #VC_ERROR_INVALID_STATE Invalid state
 551 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 552 *
 553 * @pre The service state should be #VC_SERVICE_STATE_READY.
 554 */
 555 int vc_mgr_get_private_data(const char* key, char** data);
 556
 557 /**
 558 * @brief Sets domain such as agent or device type.
 559 *
 560 * @param[in] domain Available agent or device type
 561 *
 562 * @return 0 on success, otherwise a negative error value
 563 * @retval #VC_ERROR_NONE Successful
 564 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
 565 * @retval #VC_ERROR_INVALID_STATE Invalid state
 566 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 567 *
 568 * @pre The service state should be #VC_SERVICE_STATE_READY.
 569 */
 570 int vc_mgr_set_domain(const char* domain);
 571
 572 /**
 573 * @brief Request to do action as if utterence is spoken.
 574 *
 575 * @param[in] type Event type
 576 * @param[in] send_event  The string for send event
 577 *
 578 * @return 0 on success, otherwise a negative error value
 579 * @retval #VC_ERROR_NONE Successful
 580 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
 581 * @retval #VC_ERROR_INVALID_STATE Invalid state
 582 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 583 *
 584 * @pre The service state should be #VC_SERVICE_STATE_READY.
 585 */
 586 int vc_mgr_do_action(vc_send_event_type_e type, char* send_event);
 587
 588 /**
 589 * @brief Starts recognition.
 590 *
 591 * @remarks The default recognition mode is #VC_RECOGNITION_MODE_STOP_BY_SILENCE. \n
 592 * If you want to use other mode, you can set mode with vc_mgr_set_recognition_mode().
 593 *
 594 * @param[in] exclusive_command_option Exclusive command option
 595 *
 596 * @return 0 on success, otherwise a negative error value
 597 * @retval #VC_ERROR_NONE Successful
 598 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
 599 * @retval #VC_ERROR_INVALID_STATE Invalid state
 600 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 601 *
 602 * @pre The state should be #VC_STATE_READY and the service state should be #VC_SERVICE_STATE_READY.
 603 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
 604 * If this function succeeds, the service state will be #VC_SERVICE_STATE_RECORDING.
 605 *
 606 * @see vc_mgr_stop()
 607 * @see vc_mgr_cancel()
 608 * @see vc_service_state_changed_cb()
 609 * @see vc_mgr_set_recognition_mode()
 610 * @see vc_mgr_get_recognition_mode()
 611 */
 612 int vc_mgr_start(bool exclusive_command_option);
 613
 614 /**
 615 * @brief Stop recognition.
 616 *
 617 * @return 0 on success, otherwise a negative error value
 618 * @retval #VC_ERROR_NONE Successful
 619 * @retval #VC_ERROR_INVALID_STATE Invalid state
 620 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 621 *
 622 * @pre The service state should be #VC_SERVICE_STATE_RECORDING.
 623 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
 624 * If this function succeeds, the service state will be #VC_SERVICE_STATE_PROCESSING.
 625 *
 626 * @see vc_mgr_start()
 627 * @see vc_mgr_cancel()
 628 * @see vc_service_state_changed_cb()
 629 * @see vc_mgr_result_cb()
 630 */
 631 int vc_mgr_stop();
 632
 633 /**
 634 * @brief Cancels recognition.
 635 *
 636 * @return 0 on success, otherwise a negative error value
 637 * @retval #VC_ERROR_NONE Successful
 638 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
 639 * @retval #VC_ERROR_INVALID_STATE Invalid state
 640 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 641 *
 642 * @pre The service state should be #VC_SERVICE_STATE_RECORDING or #VC_SERVICE_STATE_PROCESSING.
 643 * @post It will invoke vc_service_state_changed_cb(), if you register a callback with vc_service_state_changed_cb(). \n
 644 * If this function succeeds, the service state will be #VC_SERVICE_STATE_READY.
 645 *
 646 * @see vc_mgr_start()
 647 * @see vc_mgr_stop()
 648 * @see vc_service_state_changed_cb()
 649 */
 650 int vc_mgr_cancel();
 651
 652 /**
 653 * @brief Gets the microphone volume during recording.
 654 *
 655 * @param[out] volume Recording volume
 656 *
 657 * @return 0 on success, otherwise a negative error value
 658 * @retval #VC_ERROR_NONE Successful
 659 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
 660 * @retval #VC_ERROR_INVALID_STATE Invalid state
 661 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 662 *
 663 * @pre The service state should be #VC_SERVICE_STATE_RECORDING.
 664 *
 665 * @see vc_mgr_start()
 666 */
 667 int vc_mgr_get_recording_volume(float* volume);
 668
 669 /**
 670 * @brief Select valid result from all results.
 671 *
 672 * @param[in] vc_cmd_list The valid result list
 673 *
 674 * @return 0 on success, otherwise a negative error value
 675 * @retval #VC_ERROR_NONE Successful
 676 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
 677 * @retval #VC_ERROR_INVALID_STATE Invalid state
 678 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 679 *
 680 * @pre vc_mgr_all_result_cb() should be called
 681 *
 682 * @see vc_mgr_all_result_cb()
 683 */
 684 int vc_mgr_set_selected_results(vc_cmd_list_h vc_cmd_list);
 685
 686
 687 /**
 688 * @brief Registers a callback function for getting recognition result.
 689 *
 690 * @param[in] callback Callback function to register
 691 * @param[in] user_data The user data to be passed to the callback function
 692 *
 693 * @return 0 on success, otherwise a negative error value
 694 * @retval #VC_ERROR_NONE Successful
 695 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 696 * @retval #VC_ERROR_INVALID_STATE Invalid state
 697 *
 698 * @pre The state should be #VC_STATE_INITIALIZED.
 699 *
 700 * @see vc_mgr_all_result_cb()
 701 * @see vc_mgr_unset_all_result_cb()
 702 */
 703 int vc_mgr_set_all_result_cb(vc_mgr_all_result_cb callback, void* user_data);
 704
 705 /**
 706 * @brief Unregisters the callback function.
 707 *
 708 * @return 0 on success, otherwise a negative error value
 709 * @retval #VC_ERROR_NONE Successful
 710 * @retval #VC_ERROR_INVALID_STATE Invalid state
 711 *
 712 * @pre The state should be #VC_STATE_INITIALIZED.
 713 *
 714 * @see vc_mgr_set_all_result_cb()
 715 */
 716 int vc_mgr_unset_all_result_cb();
 717
 718 /**
 719 * @brief Registers a callback function for getting pre recognition result.
 720 *
 721 * @param[in] callback Callback function to register
 722 * @param[in] user_data The user data to be passed to the callback function
 723 *
 724 * @return 0 on success, otherwise a negative error value
 725 * @retval #VC_ERROR_NONE Successful
 726 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 727 * @retval #VC_ERROR_INVALID_STATE Invalid state
 728 *
 729 * @pre The state should be #VC_STATE_INITIALIZED.
 730 *
 731 * @see vc_mgr_pre_result_cb()
 732 * @see vc_mgr_unset_pre_result_cb()
 733 */
 734 int vc_mgr_set_pre_result_cb(vc_mgr_pre_result_cb callback, void* user_data);
 735
 736 /**
 737 * @brief Unregisters the callback function.
 738 *
 739 * @return 0 on success, otherwise a negative error value
 740 * @retval #VC_ERROR_NONE Successful
 741 * @retval #VC_ERROR_INVALID_STATE Invalid state
 742 *
 743 * @pre The state should be #VC_STATE_INITIALIZED.
 744 *
 745 * @see vc_mgr_set_pre_result_cb()
 746 */
 747 int vc_mgr_unset_pre_result_cb();
 748
 749 /**
 750 * @brief Registers a callback function for getting system or exclusive recognition result.
 751 *
 752 * @param[in] callback Callback function to register
 753 * @param[in] user_data The user data to be passed to the callback function
 754 *
 755 * @return 0 on success, otherwise a negative error value
 756 * @retval #VC_ERROR_NONE Successful
 757 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 758 * @retval #VC_ERROR_INVALID_STATE Invalid state
 759 *
 760 * @pre The state should be #VC_STATE_INITIALIZED.
 761 *
 762 * @see vc_result_cb()
 763 * @see vc_mgr_unset_result_cb()
 764 */
 765 int vc_mgr_set_result_cb(vc_result_cb callback, void* user_data);
 766
 767 /**
 768 * @brief Unregisters the callback function.
 769 *
 770 * @return 0 on success, otherwise a negative error value
 771 * @retval #VC_ERROR_NONE Successful
 772 * @retval #VC_ERROR_INVALID_STATE Invalid state
 773 *
 774 * @pre The state should be #VC_STATE_INITIALIZED.
 775 *
 776 * @see vc_mgr_set_result_cb()
 777 */
 778 int vc_mgr_unset_result_cb();
 779
 780 /**
 781 * @brief Registers a callback function to be called when state is changed.
 782 *
 783 * @param[in] callback Callback function to register
 784 * @param[in] user_data The user data to be passed to the callback function
 785 *
 786 * @return 0 on success, otherwise a negative error value
 787 * @retval #VC_ERROR_NONE Successful
 788 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 789 * @retval #VC_ERROR_INVALID_STATE Invalid state
 790 *
 791 * @pre The state should be #VC_STATE_INITIALIZED.
 792 *
 793 * @see vc_state_changed_cb()
 794 * @see vc_mgr_unset_state_changed_cb()
 795 */
 796 int vc_mgr_set_state_changed_cb(vc_state_changed_cb callback, void* user_data);
 797
 798 /**
 799 * @brief Unregisters the callback function.
 800 *
 801 * @return 0 on success, otherwise a negative error value
 802 * @retval #VC_ERROR_NONE Successful
 803 * @retval #VC_ERROR_INVALID_STATE Invalid state
 804 *
 805 * @pre The state should be #VC_STATE_INITIALIZED.
 806 *
 807 * @see vc_mgr_set_state_changed_cb()
 808 */
 809 int vc_mgr_unset_state_changed_cb();
 810
 811 /**
 812 * @brief Registers a callback function to be called when state is changed.
 813 *
 814 * @param[in] callback Callback function to register
 815 * @param[in] user_data The user data to be passed to the callback function
 816 *
 817 * @return 0 on success, otherwise a negative error value
 818 * @retval #VC_ERROR_NONE Successful
 819 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 820 * @retval #VC_ERROR_INVALID_STATE Invalid state
 821 *
 822 * @pre The state should be #VC_STATE_INITIALIZED.
 823 *
 824 * @see vc_service_state_changed_cb()
 825 * @see vc_mgr_unset_service_state_changed_cb()
 826 */
 827 int vc_mgr_set_service_state_changed_cb(vc_service_state_changed_cb callback, void* user_data);
 828
 829 /**
 830 * @brief Unregisters the callback function.
 831 *
 832 * @return 0 on success, otherwise a negative error value
 833 * @retval #VC_ERROR_NONE Successful
 834 * @retval #VC_ERROR_INVALID_STATE Invalid state
 835 *
 836 * @pre The state should be #VC_STATE_INITIALIZED.
 837 *
 838 * @see vc_mgr_set_service_state_changed_cb()
 839 */
 840 int vc_mgr_unset_service_state_changed_cb();
 841
 842 /**
 843 * @brief Registers a callback function to be called when begin of speech is detected.
 844 *
 845 * @param[in] callback Callback function to register
 846 * @param[in] user_data The user data to be passed to the callback function
 847 *
 848 * @return 0 on success, otherwise a negative error value
 849 * @retval #VC_ERROR_NONE Successful
 850 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 851 * @retval #VC_ERROR_INVALID_STATE Invalid state
 852 *
 853 * @pre The state should be #VC_STATE_INITIALIZED.
 854 *
 855 * @see vc_mgr_begin_speech_detected_cb()
 856 * @see vc_mgr_unset_speech_detected_cb()
 857 */
 858 int vc_mgr_set_speech_detected_cb(vc_mgr_begin_speech_detected_cb callback, void* user_data);
 859
 860 /**
 861 * @brief Unregisters the callback function.
 862 *
 863 * @return 0 on success, otherwise a negative error value
 864 * @retval #VC_ERROR_NONE Successful
 865 * @retval #VC_ERROR_INVALID_STATE Invalid state
 866 *
 867 * @pre The state should be #VC_STATE_INITIALIZED.
 868 *
 869 * @see vc_mgr_set_speech_detected_cb()
 870 */
 871 int vc_mgr_unset_speech_detected_cb();
 872
 873 /**
 874 * @brief Registers a callback function to be called when current language is changed.
 875 *
 876 * @param[in] callback Callback function to register
 877 * @param[in] user_data The user data to be passed to the callback function
 878 *
 879 * @return 0 on success, otherwise a negative error value
 880 * @retval #VC_ERROR_NONE Successful
 881 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 882 * @retval #VC_ERROR_INVALID_STATE Invalid state
 883 *
 884 * @pre The state should be #VC_STATE_INITIALIZED.
 885 *
 886 * @see vc_current_language_changed_cb()
 887 * @see vc_mgr_unset_current_language_changed_cb()
 888 */
 889 int vc_mgr_set_current_language_changed_cb(vc_current_language_changed_cb callback, void* user_data);
 890
 891 /**
 892 * @brief Unregisters the callback function.
 893 *
 894 * @return 0 on success, otherwise a negative error value
 895 * @retval #VC_ERROR_NONE Successful
 896 * @retval #VC_ERROR_INVALID_STATE Invalid state
 897 *
 898 * @pre The state should be #VC_STATE_INITIALIZED.
 899 *
 900 * @see vc_mgr_set_current_language_changed_cb()
 901 */
 902 int vc_mgr_unset_current_language_changed_cb();
 903
 904 /**
 905 * @brief Gets the current error message.
 906 *
 907 * @remarks This function should be called during as vc error callback. If not, the error as operation failure will be returned. \n
 908 *        If the function succeeds, @a err_msg must be released using free() when it is no longer required.
 909 *
 910 * @param[out] err_msg The current error message
 911 *
 912 * @return 0 on success, otherwise a negative error value
 913 * @retval #VC_ERROR_NONE Successful
 914 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 915 * @retval #VC_ERROR_INVALID_STATE Invalid state
 916 * @retval $VC_ERROR_OPERATION_FAILED Operation failure
 917 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 918 *
 919 * @see vc_error_cb()
 920 */
 921 int vc_mgr_get_error_message(char** err_msg);
 922
 923 /**
 924 * @brief Registers a callback function to be called when an error occurred.
 925 *
 926 * @param[in] callback Callback function to register
 927 * @param[in] user_data The user data to be passed to the callback function
 928 *
 929 * @return 0 on success, otherwise a negative error value
 930 * @retval #VC_ERROR_NONE Successful
 931 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 932 * @retval #VC_ERROR_INVALID_STATE Invalid state
 933 *
 934 * @pre The state should be #VC_STATE_INITIALIZED.
 935 *
 936 * @see vc_error_cb()
 937 * @see vc_mgr_unset_error_cb()
 938 */
 939 int vc_mgr_set_error_cb(vc_error_cb callback, void* user_data);
 940
 941 /**
 942 * @brief Unregisters the callback function.
 943 *
 944 * @return 0 on success, otherwise a negative error value
 945 * @retval #VC_ERROR_NONE Successful
 946 * @retval #VC_ERROR_INVALID_STATE Invalid state
 947 *
 948 * @pre The state should be #VC_STATE_INITIALIZED.
 949 *
 950 * @see vc_mgr_set_error_cb()
 951 */
 952 int vc_mgr_unset_error_cb();
 953
 954
 955 /**
 956 * @brief Registers a callback function to be called when dialog requests.
 957 *
 958 * @param[in] callback Callback function to register
 959 * @param[in] user_data The user data to be passed to the callback function
 960 *
 961 * @return 0 on success, otherwise a negative error value
 962 * @retval #VC_ERROR_NONE Successful
 963 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 964 * @retval #VC_ERROR_INVALID_STATE Invalid state
 965 *
 966 * @pre The state should be #VC_STATE_INITIALIZED.
 967 *
 968 * @see vc_mgr_unset_dialog_request_cb()
 969 */
 970 int vc_mgr_set_dialog_request_cb(vc_mgr_dialog_request_cb callback, void* user_data);
 971
 972 /**
 973 * @brief Unregisters the callback function.
 974 *
 975 * @return 0 on success, otherwise a negative error value
 976 * @retval #VC_ERROR_NONE Successful
 977 * @retval #VC_ERROR_INVALID_STATE Invalid state
 978 *
 979 * @pre The state should be #VC_STATE_INITIALIZED.
 980 *
 981 * @see vc_mgr_set_dialog_request_cb()
 982 */
 983 int vc_mgr_unset_dialog_request_cb();
 984
 985 /**
 986 * @brief Enable command type as candidate command.
 987 *
 988 * @return 0 on success, otherwise a negative error value
 989 * @retval #VC_ERROR_NONE Successful
 990 * @retval #VC_ERROR_INVALID_STATE Invalid state
 991 *
 992 * @pre The state should be #VC_STATE_READY.
 993 *
 994 * @see vc_mgr_disable_command_type()
 995 */
 996 int vc_mgr_enable_command_type(int cmd_type);
 997
 998 /**
 999 * @brief Disable command type as candidate command.
1000 *
1001 * @return 0 on success, otherwise a negative error value
1002 * @retval #VC_ERROR_NONE Successful
1003 * @retval #VC_ERROR_INVALID_STATE Invalid state
1004 *
1005 * @pre The state should be #VC_STATE_READY.
1006 *
1007 * @see vc_mgr_enable_command_type()
1008 */
1009 int vc_mgr_disable_command_type(int cmd_type);
1010
1011 #ifdef __cplusplus
1012 }
1013 #endif
1014
1015 /**
1016  * @}@}
1017  */
1018
1019 #endif /* __VOICE_CONTROL_MANAGER_H__ */
1020