include/voice_control.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_H__
  19 #define __VOICE_CONTROL_H__
  20
  21 #include <voice_control_command.h>
  22 #include <voice_control_common.h>
  23
  24 /**
  25 * @addtogroup CAPI_UIX_VOICE_CONTROL_MODULE
  26 * @{
  27 */
  28
  29 #ifdef __cplusplus
  30 extern "C"
  31 {
  32 #endif
  33
  34 /**
  35 * @file voice_control.h
  36 * @brief This file contains the voice control client API and related callback definitions and enums.
  37 */
  38
  39 /**
  40 * @file voice_control_command.h
  41 * @brief This file contains the command list and command API and related handle definitions and enums.
  42 */
  43
  44 /**
  45 * @file voice_control_common.h
  46 * @brief This file contains the callback function definitions and enums.
  47 */
  48
  49 /**
  50 * @brief Definitions for foreground command type.
  51 * @since_tizen 2.4
  52 */
  53 #define VC_COMMAND_TYPE_FOREGROUND      1
  54
  55 /**
  56 * @brief Definitions for background command type.
  57 * @since_tizen 2.4
  58 */
  59 #define VC_COMMAND_TYPE_BACKGROUND      2
  60
  61
  62 /**
  63 * @brief Initializes voice control.
  64 * @since_tizen 2.4
  65 * @privlevel public
  66 * @privilege %http://tizen.org/privilege/recorder
  67 *
  68 * @remarks If the function succeeds, @a vc must be released with vc_deinitialize().
  69 *
  70 * @return 0 on success, otherwise a negative error value
  71 * @retval #VC_ERROR_NONE Successful
  72 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
  73 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
  74 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
  75 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
  76 *
  77 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
  78 *
  79 * @see vc_deinitialize()
  80 */
  81 int vc_initialize(void);
  82
  83 /**
  84 * @brief Deinitializes voice control.
  85 * @since_tizen 2.4
  86 * @privlevel public
  87 * @privilege %http://tizen.org/privilege/recorder
  88 *
  89 * @return 0 on success, otherwise a negative error value
  90 * @retval #VC_ERROR_NONE Successful
  91 * @retval #VC_ERROR_INVALID_STATE Invalid state
  92 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
  93 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
  94 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
  95 *
  96 * @see vc_deinitialize()
  97 */
  98 int vc_deinitialize(void);
  99
 100 /**
 101 * @brief Connects the voice control service.
 102 * @since_tizen 2.4
 103 * @privlevel public
 104 * @privilege %http://tizen.org/privilege/recorder
 105 *
 106 * @return 0 on success, otherwise a negative error value
 107 * @retval #VC_ERROR_NONE Successful
 108 * @retval #VC_ERROR_INVALID_STATE Invalid state
 109 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 110 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 111 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 112 *
 113 * @pre The state should be #VC_STATE_INITIALIZED.
 114 * @post If this function is called, the state will be #VC_STATE_READY.
 115 *
 116 * @see vc_unprepare()
 117 */
 118 int vc_prepare(void);
 119
 120 /**
 121 * @brief Disconnects the voice control service.
 122 * @since_tizen 2.4
 123 * @privlevel public
 124 * @privilege %http://tizen.org/privilege/recorder
 125 *
 126 * @return 0 on success, otherwise a negative error value
 127 * @retval #VC_ERROR_NONE Successful
 128 * @retval #VC_ERROR_INVALID_STATE Invalid state
 129 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 130 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 131 *
 132 * @pre The state should be #VC_STATE_READY.
 133 * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
 134 *
 135 * @see vc_prepare()
 136 */
 137 int vc_unprepare(void);
 138
 139 /**
 140 * @brief Retrieves all supported languages using callback function.
 141 * @since_tizen 2.4
 142 * @privlevel public
 143 * @privilege %http://tizen.org/privilege/recorder
 144 *
 145 * @param[in] callback Callback function to invoke
 146 * @param[in] user_data The user data to be passed to the callback function
 147 *
 148 * @return 0 on success, otherwise a negative error value
 149 * @retval #VC_ERROR_NONE Successful
 150 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 151 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 152 * @retval #VC_ERROR_INVALID_STATE Invalid state
 153 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 154 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 155 *
 156 * @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY.
 157 * @post This function invokes vc_supported_language_cb() repeatedly for getting languages.
 158 *
 159 * @see vc_supported_language_cb()
 160 * @see vc_get_current_language()
 161 */
 162 int vc_foreach_supported_languages(vc_supported_language_cb callback, void* user_data);
 163
 164 /**
 165 * @brief Gets current language.
 166 * @since_tizen 2.4
 167 * @privlevel public
 168 * @privilege %http://tizen.org/privilege/recorder
 169 *
 170 * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it.
 171 *
 172 * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
 173 *                       followed by ISO 639-1 for the two-letter language code. \n
 174 *                       For example, "ko_KR" for Korean, "en_US" for American English.
 175 *
 176 * @return 0 on success, otherwise a negative error value
 177 * @retval #VC_ERROR_NONE Successful
 178 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 179 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 180 * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 181 * @retval #VC_ERROR_INVALID_STATE Invalid state
 182 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 183 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 184 *
 185 * @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY.
 186 *
 187 * @see vc_foreach_supported_languages()
 188 */
 189 int vc_get_current_language(char** language);
 190
 191 /**
 192 * @brief Gets current state of voice control client.
 193 * @since_tizen 2.4
 194 * @privlevel public
 195 * @privilege %http://tizen.org/privilege/recorder
 196 *
 197 * @param[out] state The current state
 198 *
 199 * @return 0 on success, otherwise a negative error value
 200 * @retval #VC_ERROR_NONE Successful
 201 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 202 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 203 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 204 *
 205 * @see vc_state_changed_cb()
 206 * @see vc_set_state_changed_cb()
 207 */
 208 int vc_get_state(vc_state_e* state);
 209
 210 /**
 211 * @brief Gets current state of voice control service.
 212 * @since_tizen 2.4
 213 * @privlevel public
 214 * @privilege %http://tizen.org/privilege/recorder
 215 *
 216 * @param[out] state The current state
 217 *
 218 * @return 0 on success, otherwise a negative error value
 219 * @retval #VC_ERROR_NONE Successful
 220 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 221 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 222 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 223 *
 224 * @pre The state should be #VC_STATE_READY.
 225 *
 226 * @see vc_request_start()
 227 * @see vc_request_stop()
 228 * @see vc_request_cancel()
 229 * @see vc_set_service_state_changed_cb()
 230 * @see vc_unset_service_state_changed_cb()
 231 */
 232 int vc_get_service_state(vc_service_state_e* state);
 233
 234 /**
 235 * @brief Sets command list.
 236 * @since_tizen 2.4
 237 * @privlevel public
 238 * @privilege %http://tizen.org/privilege/recorder
 239 *
 240 * @remarks The command type is valid for #VC_COMMAND_TYPE_FOREGROUND or #VC_COMMAND_TYPE_BACKGROUND. \n
 241 *       The matched commands of command list should be set and they should include type and command text at least.
 242 *
 243 * @param[in] vc_cmd_list Command list handle
 244 * @param[in] type Command type
 245 *
 246 * @return 0 on success, otherwise a negative error value
 247 * @retval #VC_ERROR_NONE Successful
 248 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 249 * @retval #VC_ERROR_INVALID_STATE Invalid state
 250 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 251 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 252 *
 253 * @pre The state should be #VC_STATE_READY.
 254 *
 255 * @see vc_unset_command_list()
 256 */
 257 int vc_set_command_list(vc_cmd_list_h vc_cmd_list, int type);
 258
 259 /**
 260 * @brief Unsets command list.
 261 * @since_tizen 2.4
 262 * @privlevel public
 263 * @privilege %http://tizen.org/privilege/recorder
 264 *
 265 * @param[in] type Command type
 266 *
 267 * @return 0 on success, otherwise a negative error value
 268 * @retval #VC_ERROR_NONE Successful
 269 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 270 * @retval #VC_ERROR_INVALID_STATE Invalid state
 271 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 272 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 273 *
 274 * @pre The state should be #VC_STATE_READY.
 275 *
 276 * @see vc_set_command_list()
 277 */
 278 int vc_unset_command_list(int type);
 279
 280
 281 /**
 282 * @brief Registers a callback function for getting recognition result.
 283 * @since_tizen 2.4
 284 * @privlevel public
 285 * @privilege %http://tizen.org/privilege/recorder
 286 *
 287 * @param[in] callback Callback function to register
 288 * @param[in] user_data The user data to be passed to the callback function
 289 *
 290 * @return 0 on success, otherwise a negative error value
 291 * @retval #VC_ERROR_NONE Successful
 292 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 293 * @retval #VC_ERROR_INVALID_STATE Invalid state
 294 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 295 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 296 *
 297 * @pre The state should be #VC_STATE_INITIALIZED.
 298 *
 299 * @see vc_result_cb()
 300 * @see vc_unset_result_cb()
 301 */
 302 int vc_set_result_cb(vc_result_cb callback, void* user_data);
 303
 304 /**
 305 * @brief Unregisters the callback function.
 306 * @since_tizen 2.4
 307 * @privlevel public
 308 * @privilege %http://tizen.org/privilege/recorder
 309 *
 310 * @return 0 on success, otherwise a negative error value
 311 * @retval #VC_ERROR_NONE Successful
 312 * @retval #VC_ERROR_INVALID_STATE Invalid state
 313 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 314 *
 315 * @pre The state should be #VC_STATE_INITIALIZED.
 316 *
 317 * @see vc_set_result_cb()
 318 */
 319 int vc_unset_result_cb(void);
 320
 321 /**
 322 * @brief Registers a callback function to be called when state is changed.
 323 * @since_tizen 2.4
 324 * @privlevel public
 325 * @privilege %http://tizen.org/privilege/recorder
 326 *
 327 * @param[in] callback Callback function to register
 328 * @param[in] user_data The user data to be passed to the callback function
 329 *
 330 * @return 0 on success, otherwise a negative error value
 331 * @retval #VC_ERROR_NONE Successful
 332 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 333 * @retval #VC_ERROR_INVALID_STATE Invalid state
 334 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 335 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 336 *
 337 * @pre The state should be #VC_STATE_INITIALIZED.
 338 *
 339 * @see vc_service_state_changed_cb()
 340 * @see vc_unset_service_state_changed_cb()
 341 */
 342 int vc_set_service_state_changed_cb(vc_service_state_changed_cb callback, void* user_data);
 343
 344 /**
 345 * @brief Unregisters the callback function.
 346 * @since_tizen 2.4
 347 * @privlevel public
 348 * @privilege %http://tizen.org/privilege/recorder
 349 *
 350 * @return 0 on success, otherwise a negative error value
 351 * @retval #VC_ERROR_NONE Successful
 352 * @retval #VC_ERROR_INVALID_STATE Invalid state
 353 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 354 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 355 *
 356 * @pre The state should be #VC_STATE_INITIALIZED.
 357 *
 358 * @see vc_set_service_state_changed_cb()
 359 */
 360 int vc_unset_service_state_changed_cb(void);
 361
 362 /**
 363 * @brief Registers a callback function to be called when state is changed.
 364 * @since_tizen 2.4
 365 * @privlevel public
 366 * @privilege %http://tizen.org/privilege/recorder
 367 *
 368 * @param[in] callback Callback function to register
 369 * @param[in] user_data The user data to be passed to the callback function
 370 *
 371 * @return 0 on success, otherwise a negative error value
 372 * @retval #VC_ERROR_NONE Successful
 373 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 374 * @retval #VC_ERROR_INVALID_STATE Invalid state
 375 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 376 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 377 *
 378 * @pre The state should be #VC_STATE_INITIALIZED.
 379 *
 380 * @see vc_state_changed_cb()
 381 * @see vc_unset_state_changed_cb()
 382 */
 383 int vc_set_state_changed_cb(vc_state_changed_cb callback, void* user_data);
 384
 385 /**
 386 * @brief Unregisters the callback function.
 387 * @since_tizen 2.4
 388 * @privlevel public
 389 * @privilege %http://tizen.org/privilege/recorder
 390 *
 391 * @return 0 on success, otherwise a negative error value
 392 * @retval #VC_ERROR_NONE Successful
 393 * @retval #VC_ERROR_INVALID_STATE Invalid state
 394 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 395 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 396 *
 397 * @pre The state should be #VC_STATE_INITIALIZED.
 398 *
 399 * @see vc_set_state_changed_cb()
 400 */
 401 int vc_unset_state_changed_cb(void);
 402
 403 /**
 404 * @brief Registers a callback function to be called when current language is changed.
 405 * @since_tizen 2.4
 406 * @privlevel public
 407 * @privilege %http://tizen.org/privilege/recorder
 408 *
 409 * @param[in] callback Callback function to register
 410 * @param[in] user_data The user data to be passed to the callback function
 411 *
 412 * @return 0 on success, otherwise a negative error value
 413 * @retval #VC_ERROR_NONE Successful
 414 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 415 * @retval #VC_ERROR_INVALID_STATE Invalid state
 416 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 417 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 418 *
 419 * @pre The state should be #VC_STATE_INITIALIZED.
 420 *
 421 * @see vc_current_language_changed_cb()
 422 * @see vc_unset_current_language_changed_cb()
 423 */
 424 int vc_set_current_language_changed_cb(vc_current_language_changed_cb callback, void* user_data);
 425
 426 /**
 427 * @brief Unregisters the callback function.
 428 * @since_tizen 2.4
 429 * @privlevel public
 430 * @privilege %http://tizen.org/privilege/recorder
 431 *
 432 * @return 0 on success, otherwise a negative error value
 433 * @retval #VC_ERROR_NONE Successful
 434 * @retval #VC_ERROR_INVALID_STATE Invalid state
 435 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 436 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 437 *
 438 * @pre The state should be #VC_STATE_INITIALIZED.
 439 *
 440 * @see vc_set_current_language_changed_cb()
 441 */
 442 int vc_unset_current_language_changed_cb(void);
 443
 444 /**
 445 * @brief Registers a callback function to be called when an error occurred.
 446 * @since_tizen 2.4
 447 * @privlevel public
 448 * @privilege %http://tizen.org/privilege/recorder
 449 *
 450 * @param[in] callback Callback function to register
 451 * @param[in] user_data The user data to be passed to the callback function
 452 *
 453 * @return 0 on success, otherwise a negative error value
 454 * @retval #VC_ERROR_NONE Successful
 455 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 456 * @retval #VC_ERROR_INVALID_STATE Invalid state
 457 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 458 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 459 *
 460 * @pre The state should be #VC_STATE_INITIALIZED.
 461 *
 462 * @see vc_error_cb()
 463 * @see vc_unset_error_cb()
 464 */
 465 int vc_set_error_cb(vc_error_cb callback, void* user_data);
 466
 467 /**
 468 * @brief Unregisters the callback function.
 469 * @since_tizen 2.4
 470 * @privlevel public
 471 * @privilege %http://tizen.org/privilege/recorder
 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 * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 477 * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 478 *
 479 * @pre The state should be #VC_STATE_INITIALIZED.
 480 *
 481 * @see vc_set_error_cb()
 482 */
 483 int vc_unset_error_cb(void);
 484
 485
 486 #ifdef __cplusplus
 487 }
 488 #endif
 489
 490 /**
 491  * @}@}
 492  */
 493
 494 #endif /* __VOICE_CONTROL_H__ */