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