include/voice_control_widget.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_WIDGET_H__
  19 #define __VOICE_CONTROL_WIDGET_H__
  20
  21 #include <voice_control_command.h>
  22 #include <voice_control_command_expand.h>
  23 #include <voice_control_common.h>
  24 #include <voice_control_internal.h>
  25
  26 typedef struct vc_s *vc_h;
  27
  28 /**
  29 * @addtogroup VOICE_CONTROL_WIDGET
  30 * @{
  31 */
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #endif
  37
  38 /**
  39 * @brief Definitions for widget command type.
  40 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  41 */
  42 #define VC_COMMAND_TYPE_WIDGET          3
  43
  44 /**
  45 * @brief Called when widget should show or hide tooltip.
  46 *
  47 * @param[in] vc_widget The voice control handle
  48 * @param[in] show Show or hide option
  49 * @param[in] user_data The user data passed from the callback registration function
  50 *
  51 * @pre An application registers callback function using vc_widget_set_show_tooltip_cb().
  52 *
  53 * @see vc_widget_set_show_tooltip_cb()
  54 * @see vc_widget_unset_show_tooltip_cb()
  55 */
  56 typedef void (*vc_widget_show_tooltip_cb)(bool show, void* user_data);
  57
  58 /**
  59 * @brief Called when widget send current command list to vc daemon.
  60 *
  61 * @param[in] vc_widget The voice control handle
  62 * @param[out] vc_cmd_list Current command list
  63 * @param[in] user_data The user data passed from the callback registration function
  64 *
  65 * @pre An application registers callback function using vc_widget_set_send_current_command_group_cb().
  66 *
  67 * @see vc_widget_set_send_current_command_list_cb()
  68 * @see vc_widget_unset_send_current_command_list_cb()
  69 */
  70 typedef void (*vc_widget_send_current_command_list_cb)(vc_cmd_list_h* vc_cmd_list, void* user_data);
  71
  72
  73 /**
  74 * @brief Initialize voice control for widget.
  75 *
  76 * @param[in] vc_widget The voice control handle
  77 *
  78 * @remarks If the function succeeds, @a vc widget must be released with vc_widget_deinitialize().
  79 *
  80 * @param[out] vc_widget The voice control handle
  81 *
  82 * @return 0 on success, otherwise a negative error value
  83 * @retval #VC_ERROR_NONE Successful
  84 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
  85 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
  86 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
  87 *
  88 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
  89 *
  90 * @see vc_widget_deinitialize()
  91 */
  92 int vc_widget_initialize(vc_h* vc);
  93
  94 /**
  95 * @brief Deinitialize voice control for widget.
  96 *
  97 * @param[in] vc_widget The voice control handle
  98 *
  99 * @return 0 on success, otherwise a negative error value
 100 * @retval #VC_ERROR_NONE Successful
 101 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 102 * @retval #VC_ERROR_INVALID_STATE Invalid state
 103 *
 104 * @see vc_widget_initialize()
 105 */
 106 int vc_widget_deinitialize(vc_h vc);
 107
 108 /**
 109 * @brief Connects the voice control service asynchronously.
 110 *
 111 * @param[in] vc_widget The voice control handle
 112 *
 113 * @return 0 on success, otherwise a negative error value
 114 * @retval #VC_ERROR_NONE Successful
 115 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 116 * @retval #VC_ERROR_INVALID_STATE Invalid state
 117 *
 118 * @pre The state should be #VC_STATE_INITIALIZED.
 119 * @post If this function is called, the state will be #VC_STATE_READY.
 120 *
 121 * @see vc_widget_unprepare()
 122 */
 123 int vc_widget_prepare(vc_h vc);
 124
 125 /**
 126 * @brief Disconnects the voice control service.
 127 *
 128 * @param[in] vc_widget The voice control handle
 129 *
 130 * @return 0 on success, otherwise a negative error value
 131 * @retval #VC_ERROR_NONE Successful
 132 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 133 * @retval #VC_ERROR_INVALID_STATE Invalid state
 134 *
 135 * @pre The state should be #VC_STATE_READY.
 136 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
 137 *
 138 * @see vc_widget_prepare()
 139 */
 140 int vc_widget_unprepare(vc_h vc);
 141
 142 /**
 143 * @brief Retrieves all supported languages using callback function.
 144 *
 145 * @param[in] vc_widget The voice control handle
 146 * @param[in] callback Callback function to invoke
 147 * @param[in] user_data The user data to be passed to the callback function
 148 *
 149 * @return 0 on success, otherwise a negative error value
 150 * @retval #VC_ERROR_NONE Successful
 151 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 152 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 153 * @retval #VC_ERROR_INVALID_STATE Invalid state
 154 *
 155 * @pre The state should be #VC_STATE_READY.
 156 * @post This function invokes vc_supported_language_cb() repeatedly for getting languages.
 157 *
 158 * @see vc_supported_language_cb()
 159 * @see vc_widget_get_current_language()
 160 */
 161 int vc_widget_foreach_supported_languages(vc_h vc, vc_supported_language_cb callback, void* user_data);
 162
 163 /**
 164 * @brief Gets current language set by user.
 165 *
 166 * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it.
 167 *
 168 * @param[in] vc_widget The voice control handle
 169 * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
 170 *                       followed by ISO 639-1 for the two-letter language code. \n
 171 *                       For example, "ko_KR" for Korean, "en_US" for American English.
 172 *
 173 * @return 0 on success, otherwise a negative error value
 174 * @retval #VC_ERROR_NONE Successful
 175 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 176 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 177 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 178 * @retval #VC_ERROR_INVALID_STATE Invalid state
 179 *
 180 * @pre The state should be #VC_STATE_READY.
 181 *
 182 * @see vc_widget_foreach_supported_languages()
 183 */
 184 int vc_widget_get_current_language(vc_h vc, char** language);
 185
 186 /**
 187 * @brief Gets current state of voice control widget.
 188 *
 189 * @param[in] vc_widget The voice control handle
 190 * @param[out] state Current state
 191 *
 192 * @return 0 on success, otherwise a negative error value
 193 * @retval #VC_ERROR_NONE Successful
 194 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 195 *
 196 * @see vc_widget_initialize()
 197 * @see vc_widget_deinitialize()
 198 * @see vc_widget_prepare()
 199 * @see vc_widget_unprepare()
 200 * @see vc_widget_set_state_changed_cb()
 201 * @see vc_widget_unset_state_changed_cb()
 202 */
 203 int vc_widget_get_state(vc_h vc, vc_state_e* state);
 204
 205 /**
 206 * @brief Gets current state of voice control service.
 207 *
 208 * @param[in] vc_widget The voice control handle
 209 * @param[out] state The current state
 210 *
 211 * @return 0 on success, otherwise a negative error value
 212 * @retval #VC_ERROR_NONE Successful
 213 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 214 *
 215 * @see vc_widget_start()
 216 * @see vc_widget_stop()
 217 * @see vc_widget_cancel()
 218 * @see vc_set_service_state_changed_cb()
 219 * @see vc_unset_service_state_changed_cb()
 220 */
 221 int vc_widget_get_service_state(vc_h vc, vc_service_state_e* state);
 222
 223 /**
 224 * @brief Checks whether the command format is supported.
 225 *
 226 * @param[in] vc_widget The voice control handle
 227 * @param[in] format The command format
 228 * @param[out] support The result status @c true = supported, @c false = not supported
 229 *
 230 * @return 0 on success, otherwise a negative error value
 231 * @retval #VC_ERROR_NONE Successful
 232 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 233 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 234 * @retval #VC_ERROR_INVALID_STATE Invalid state
 235 *
 236 * @pre The state should be #VC_STATE_READY.
 237 */
 238 int vc_widget_is_command_format_supported(vc_h vc, vc_cmd_format_e format, bool* support);
 239
 240
 241 /**
 242 * @brief Sets foreground state of application.
 243 *
 244 * @param[in] vc_widget The voice control handle
 245 * @param[in] value value @c true foreground, \n @c false background.
 246 *
 247 * @return 0 on success, otherwise a negative error value
 248 * @retval #VC_ERROR_NONE Successful
 249 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 250 * @retval #VC_ERROR_INVALID_STATE Invalid state
 251 * @retval #VC_ERROR_OPERATION_FAILED Operation failed
 252 *
 253 * @pre The state should be #VC_STATE_READY.
 254 */
 255 int vc_widget_set_foreground(vc_h vc, bool value);
 256
 257 /**
 258 * @brief Cancels recognition.
 259 *
 260 * @param[in] vc_widget The voice control handle
 261 *
 262 * @return 0 on success, otherwise a negative error value
 263 * @retval #VC_ERROR_NONE Successful
 264 * @retval #VC_ERROR_OUT_OF_MEMORY Not enough memory
 265 * @retval #VC_ERROR_INVALID_STATE Invalid state
 266 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 267 *
 268 * @pre The service state should be #VC_SERVICE_STATE_RECORDING or #VC_SERVICE_STATE_PROCESSING.
 269 * @post It will invoke vc_state_changed_cb(), if you register a callback with vc_state_changed_cb(). \n
 270 * If this function succeeds, the state will be #VC_STATE_READY.
 271 *
 272 * @see vc_widget_start()
 273 * @see vc_widget_stop()
 274 * @see vc_state_changed_cb()
 275 */
 276 int vc_widget_cancel(vc_h vc);
 277
 278 /**
 279 * @brief Registers a callback function for getting recognition result.
 280 *
 281 * @param[in] vc_widget The voice control handle
 282 * @param[in] callback Callback function to register
 283 * @param[in] user_data The user data to be passed to the callback function
 284 *
 285 * @return 0 on success, otherwise a negative error value
 286 * @retval #VC_ERROR_NONE Successful
 287 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 288 * @retval #VC_ERROR_INVALID_STATE Invalid state
 289 *
 290 * @pre The state should be #VC_STATE_INITIALIZED.
 291 *
 292 * @see vc_widget_result_cb()
 293 * @see vc_widget_unset_result_cb()
 294 */
 295 int vc_widget_set_result_cb(vc_h vc, vc_result_cb callback, void* user_data);
 296
 297
 298 /**
 299 * @brief Unregisters the callback function.
 300 *
 301 * @param[in] vc_widget The voice control handle
 302 *
 303 * @return 0 on success, otherwise a negative error value
 304 * @retval #VC_ERROR_NONE Successful
 305 * @retval #VC_ERROR_INVALID_STATE Invalid state
 306 *
 307 * @pre The state should be #VC_STATE_INITIALIZED.
 308 *
 309 * @see vc_widget_set_result_cb()
 310 */
 311 int vc_widget_unset_result_cb(vc_h vc);
 312
 313 /**
 314 * @brief Registers a callback function for showing or hiding tooltip.
 315 *
 316 * @param[in] vc_widget The voice control handle
 317 * @param[in] callback Callback function to register
 318 * @param[in] user_data The user data to be passed to the callback function
 319 *
 320 * @return 0 on success, otherwise a negative error value
 321 * @retval #VC_ERROR_NONE Successful
 322 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 323 * @retval #VC_ERROR_INVALID_STATE Invalid state
 324 *
 325 * @pre The state should be #VC_STATE_INITIALIZED.
 326 *
 327 * @see vc_widget_show_tooltip_cb()
 328 * @see vc_widget_unset_show_tooltip_cb()
 329 */
 330 int vc_widget_set_show_tooltip_cb(vc_h vc, vc_widget_show_tooltip_cb callback, void* user_data);
 331
 332 /**
 333 * @brief Unregisters the callback function.
 334 *
 335 * @param[in] vc_widget The voice control handle
 336 *
 337 * @return 0 on success, otherwise a negative error value
 338 * @retval #VC_ERROR_NONE Successful
 339 * @retval #VC_ERROR_INVALID_STATE Invalid state
 340 *
 341 * @pre The state should be #VC_STATE_INITIALIZED.
 342 *
 343 * @see vc_widget_set_show_tooltip_cb()
 344 */
 345 int vc_widget_unset_show_tooltip_cb(vc_h vc);
 346
 347 /**
 348 * @brief Registers a callback function for setting current command.
 349 *
 350 * @param[in] vc_widget The voice control handle
 351 * @param[in] callback Callback function to register
 352 * @param[in] user_data The user data to be passed to the callback function
 353 *
 354 * @return 0 on success, otherwise a negative error value
 355 * @retval #VC_ERROR_NONE Successful
 356 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 357 * @retval #VC_ERROR_INVALID_STATE Invalid state
 358 *
 359 * @pre The state should be #VC_STATE_INITIALIZED.
 360 *
 361 * @see vc_widget_send_current_command_list_cb()
 362 * @see vc_widget_unset_send_current_command_list_cb()
 363 */
 364 int vc_widget_set_send_current_command_list_cb(vc_h vc, vc_widget_send_current_command_list_cb callback, void* user_data);
 365
 366 /**
 367 * @brief Unregisters the callback function.
 368 *
 369 * @param[in] vc_widget The voice control handle
 370 *
 371 * @return 0 on success, otherwise a negative error value
 372 * @retval #VC_ERROR_NONE Successful
 373 * @retval #VC_ERROR_INVALID_STATE Invalid state
 374 *
 375 * @pre The state should be #VC_STATE_INITIALIZED.
 376 *
 377 * @see vc_widget_set_send_current_command_list_cb()
 378 */
 379 int vc_widget_unset_send_current_command_list_cb(vc_h vc);
 380
 381 /**
 382 * @brief Registers a callback function to be called when service state is changed.
 383 *
 384 * @param[in] vc_widget The voice control handle
 385 * @param[in] callback Callback function to register
 386 * @param[in] user_data The user data to be passed to the callback function
 387 *
 388 * @return 0 on success, otherwise a negative error value
 389 * @retval #VC_ERROR_NONE Successful
 390 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 391 * @retval #VC_ERROR_INVALID_STATE Invalid state
 392 *
 393 * @pre The state should be #VC_STATE_INITIALIZED.
 394 *
 395 * @see vc_service_state_changed_cb()
 396 * @see vc_widget_unset_service_state_changed_cb()
 397 */
 398 int vc_widget_set_service_state_changed_cb(vc_h vc, vc_service_state_changed_cb callback, void* user_data);
 399
 400 /**
 401 * @brief Unregisters the callback function.
 402 *
 403 * @param[in] vc_widget The voice control handle
 404 *
 405 * @return 0 on success, otherwise a negative error value
 406 * @retval #VC_ERROR_NONE Successful
 407 * @retval #VC_ERROR_INVALID_STATE Invalid state
 408 *
 409 * @pre The state should be #VC_STATE_INITIALIZED.
 410 *
 411 * @see vc_widget_set_service_state_changed_cb()
 412 */
 413 int vc_widget_unset_service_state_changed_cb(vc_h vc);
 414
 415 /**
 416 * @brief Registers a callback function for getting state changed.
 417 *
 418 * @param[in] vc_widget The voice control handle
 419 *
 420 * @param[in] callback Callback function to register
 421 * @param[in] user_data The user data to be passed to the callback function
 422 *
 423 * @return 0 on success, otherwise a negative error value
 424 * @retval #VC_ERROR_NONE Successful
 425 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 426 * @retval #VC_ERROR_INVALID_STATE Invalid state
 427 *
 428 * @pre The state should be #VC_STATE_INITIALIZED.
 429 *
 430 * @see vc_state_changed_cb()
 431 * @see vc_widget_unset_state_changed_cb()
 432 */
 433 int vc_widget_set_state_changed_cb(vc_h vc, vc_state_changed_cb callback, void* user_data);
 434
 435 /**
 436 * @brief Unregisters the callback function.
 437 *
 438 * @param[in] vc_widget The voice control handle
 439 *
 440 * @return 0 on success, otherwise a negative error value
 441 * @retval #VC_ERROR_NONE Successful
 442 * @retval #VC_ERROR_INVALID_STATE Invalid state
 443 *
 444 * @pre The state should be #VC_STATE_INITIALIZED.
 445 *
 446 * @see vc_widget_set_state_changed_cb()
 447 */
 448 int vc_widget_unset_state_changed_cb(vc_h vc);
 449
 450 /**
 451 * @brief Registers a callback function to be called when current language is changed.
 452 *
 453 * @param[in] vc_widget The voice control handle
 454 *
 455 * @param[in] callback Callback function to register
 456 * @param[in] user_data The user data to be passed to the callback function
 457 *
 458 * @return 0 on success, otherwise a negative error value
 459 * @retval #VC_ERROR_NONE Successful
 460 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 461 * @retval #VC_ERROR_INVALID_STATE Invalid state
 462 *
 463 * @pre The state should be #VC_STATE_INITIALIZED.
 464 *
 465 * @see vc_current_language_changed_cb()
 466 * @see vc_widget_unset_current_language_changed_cb()
 467 */
 468 int vc_widget_set_current_language_changed_cb(vc_h vc, vc_current_language_changed_cb callback, void* user_data);
 469
 470 /**
 471 * @brief Unregisters the callback function.
 472 *
 473 * @param[in] vc_widget The voice control handle
 474 *
 475 * @return 0 on success, otherwise a negative error value
 476 * @retval #VC_ERROR_NONE Successful
 477 * @retval #VC_ERROR_INVALID_STATE Invalid state
 478 *
 479 * @pre The state should be #VC_STATE_INITIALIZED.
 480 *
 481 * @see vc_widget_set_current_language_changed_cb()
 482 */
 483 int vc_widget_unset_current_language_changed_cb(vc_h vc);
 484
 485 /**
 486 * @brief Registers a callback function for an error occurred.
 487 *
 488 * @param[in] vc_widget The voice control handle
 489 *
 490 * @param[in] callback Callback function to register
 491 * @param[in] user_data The user data to be passed to the callback function
 492 *
 493 * @return 0 on success, otherwise a negative error value
 494 * @retval #VC_ERROR_NONE Successful
 495 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 496 * @retval #VC_ERROR_INVALID_STATE Invalid state
 497 *
 498 * @pre The state should be #VC_STATE_INITIALIZED.
 499 *
 500 * @see vc_error_cb()
 501 * @see vc_widget_unset_error_cb()
 502 */
 503 int vc_widget_set_error_cb(vc_h vc, vc_error_cb callback, void* user_data);
 504
 505 /**
 506 * @brief Unregisters the callback function.
 507 *
 508 * @param[in] vc_widget The voice control handle
 509 *
 510 * @return 0 on success, otherwise a negative error value
 511 * @retval #VC_ERROR_NONE Successful
 512 * @retval #VC_ERROR_INVALID_STATE Invalid state
 513 *
 514 * @pre The state should be #VC_STATE_INITIALIZED.
 515 *
 516 * @see vc_widget_set_error_cb()
 517 */
 518 int vc_widget_unset_error_cb(vc_h vc);
 519
 520 /**
 521  * @brief Sets option for obtain ASR result as dictation via result callback.
 522  * @since_tizen 3.0
 523  * @privlevel public
 524  * @privilege %http://tizen.org/privilege/recorder
 525  *
 526  * @param[in] enable enable to get asr result
 527  *
 528  * @return 0 on success, otherwise a negative error value
 529  * @retval #VC_ERROR_NONE Successful
 530  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 531  * @retval #VC_ERROR_INVALID_STATE Invalid state
 532  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 533  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 534  *
 535  * @pre The state should be #VC_STATE_READY.
 536  *
 537  */
 538 int vc_widget_enable_asr_result(vc_h vc, bool enable);
 539
 540 /**
 541 * @brief Registers a callback function for an asr result.
 542 *
 543 * @param[in] callback Callback function to register
 544 * @param[in] user_data The user data to be passed to the callback function
 545 *
 546 * @return 0 on success, otherwise a negative error value
 547 * @retval #VC_ERROR_NONE Successful
 548 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 549 * @retval #VC_ERROR_INVALID_STATE Invalid state
 550 *
 551 * @pre The state should be #VC_STATE_INITIALIZED.
 552 *
 553 * @see vc_asr_result_cb()
 554 * @see vc_widget_enable_asr_result()
 555 * @see vc_widget_unset_asr_result_cb()
 556 */
 557 int vc_widget_set_asr_result_cb(vc_h vc, vc_asr_result_cb callback, void* user_data);
 558
 559 /**
 560 * @brief Unregisters the callback function.
 561 *
 562 * @return 0 on success, otherwise a negative error value
 563 * @retval #VC_ERROR_NONE Successful
 564 * @retval #VC_ERROR_INVALID_STATE Invalid state
 565 *
 566 * @pre The state should be #VC_STATE_INITIALIZED.
 567 *
 568 * @see vc_widget_set_asr_result_cb()
 569 */
 570 int vc_widget_unset_asr_result_cb(vc_h vc);
 571
 572 #ifdef __cplusplus
 573 }
 574 #endif
 575
 576 /**
 577  * @}@}
 578  */
 579
 580 #endif /* __VOICE_CONTROL_WIDGET_H__ */