include/voice_control.h

   1 /**
   2  * Copyright (c) 2011-2016 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
  22 #include <voice_control_command.h>
  23 #include <voice_control_common.h>
  24
  25
  26 /**
  27  * @addtogroup CAPI_UIX_VOICE_CONTROL_MODULE
  28  * @{
  29  */
  30
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #endif
  36
  37
  38 /**
  39  * @file voice_control.h
  40  * @brief This file contains the voice control client API and related callback definitions and enums.
  41  */
  42
  43
  44 /**
  45  * @file voice_control_command.h
  46  * @brief This file contains the command list and command API and related handle definitions and enums.
  47  */
  48
  49
  50 /**
  51  * @file voice_control_common.h
  52  * @brief This file contains the callback function definitions and enums.
  53  */
  54
  55
  56 /**
  57  * @brief Definition for foreground command type.
  58  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  59  */
  60 #define VC_COMMAND_TYPE_FOREGROUND      1
  61
  62
  63 /**
  64  * @brief Definition for background command type.
  65  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  66  */
  67 #define VC_COMMAND_TYPE_BACKGROUND      2
  68
  69
  70 /**
  71  * @brief Definition for ended dialog.
  72  * @since_tizen 3.0
  73  */
  74 #define VC_DIALOG_END           0
  75
  76
  77 /**
  78  * @brief Definition for continued dialog.
  79  * @since_tizen 3.0
  80  */
  81 #define VC_DIALOG_CONTINUE      1
  82
  83
  84 /**
  85  * @brief Initializes voice control.
  86  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  87  * @privlevel public
  88  * @privilege %http://tizen.org/privilege/recorder
  89  * @remarks If the function succeeds, vc must be released with vc_deinitialize().
  90  * @return @c 0 on success,
  91  *         otherwise a negative error value
  92  * @retval #VC_ERROR_NONE Successful
  93  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
  94  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
  95  * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
  96  * @retval #VC_ERROR_OPERATION_FAILED Operation failure
  97  * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
  98  * @see vc_deinitialize()
  99  */
 100 int vc_initialize(void);
 101
 102
 103 /**
 104  * @brief Deinitializes voice control.
 105  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 106  * @privlevel public
 107  * @privilege %http://tizen.org/privilege/recorder
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  * @retval #VC_ERROR_NONE Successful
 111  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 112  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 113  * @retval #VC_ERROR_INVALID_STATE Invalid state
 114  * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 115  * @see vc_initialize()
 116  */
 117 int vc_deinitialize(void);
 118
 119
 120 /**
 121  * @brief Connects the voice control service.
 122  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 123  * @privlevel public
 124  * @privilege %http://tizen.org/privilege/recorder
 125  * @return @c 0 on success,
 126  *         otherwise a negative error value
 127  * @retval #VC_ERROR_NONE Successful
 128  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 129  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 130  * @retval #VC_ERROR_INVALID_STATE Invalid state
 131  * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 132  * @pre The state should be #VC_STATE_INITIALIZED.
 133  * @post If this function is called, the state will be #VC_STATE_READY.
 134  * @see vc_unprepare()
 135  */
 136 int vc_prepare(void);
 137
 138
 139 /**
 140  * @brief Disconnects the voice control service.
 141  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 142  * @privlevel public
 143  * @privilege %http://tizen.org/privilege/recorder
 144  * @return @c 0 on success,
 145  *         otherwise a negative error value
 146  * @retval #VC_ERROR_NONE Successful
 147  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 148  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 149  * @retval #VC_ERROR_INVALID_STATE Invalid state
 150  * @pre The state should be #VC_STATE_READY.
 151  * @post If this function is called, the state will be #VC_STATE_INITIALIZED.
 152  * @see vc_prepare()
 153  */
 154 int vc_unprepare(void);
 155
 156
 157 /**
 158  * @brief Retrieves all supported languages using callback function.
 159  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 160  * @privlevel public
 161  * @privilege %http://tizen.org/privilege/recorder
 162  * @param[in] callback Callback function to invoke
 163  * @param[in] user_data The user data to be passed to the callback function
 164  * @return @c 0 on success,
 165  *         otherwise a negative error value
 166  * @retval #VC_ERROR_NONE Successful
 167  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 168  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 169  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 170  * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 171  * @retval #VC_ERROR_INVALID_STATE Invalid state
 172  * @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY.
 173  * @post This function invokes vc_supported_language_cb() repeatedly for getting languages.
 174  * @see vc_supported_language_cb()
 175  * @see vc_get_current_language()
 176  */
 177 int vc_foreach_supported_languages(vc_supported_language_cb callback, void* user_data);
 178
 179
 180 /**
 181  * @brief Gets current language.
 182  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 183  * @privlevel public
 184  * @privilege %http://tizen.org/privilege/recorder
 185  * @remarks If the function succeeds, @a language must be released with free() by you when you no longer need it.
 186  * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code
 187  *                      followed by ISO 639-1 for the two-letter language code.
 188  *                      For example, "ko_KR" for Korean, "en_US" for American English
 189  * @return @c 0 on success,
 190  *         otherwise a negative error value
 191  * @retval #VC_ERROR_NONE Successful
 192  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 193  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 194  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 195  * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory
 196  * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 197  * @retval #VC_ERROR_INVALID_STATE Invalid state
 198  * @pre The state should be #VC_STATE_INITIALIZED or #VC_STATE_READY.
 199  * @see vc_foreach_supported_languages()
 200  */
 201 int vc_get_current_language(char** language);
 202
 203
 204 /**
 205  * @brief Gets current state of voice control client.
 206  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 207  * @privlevel public
 208  * @privilege %http://tizen.org/privilege/recorder
 209  * @param[out] state The current state
 210  * @return @c 0 on success,
 211  *         otherwise a negative error value
 212  * @retval #VC_ERROR_NONE Successful
 213  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 214  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 215  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 216  * @see vc_state_changed_cb()
 217  * @see vc_set_state_changed_cb()
 218  */
 219 int vc_get_state(vc_state_e* state);
 220
 221
 222 /**
 223  * @brief Gets current state of voice control service.
 224  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 225  * @privlevel public
 226  * @privilege %http://tizen.org/privilege/recorder
 227  * @param[out] state The current state
 228  * @return @c 0 on success,
 229  *         otherwise a negative error value
 230  * @retval #VC_ERROR_NONE Successful
 231  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 232  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 233  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 234  * @pre The state should be #VC_STATE_READY.
 235  * @see vc_set_service_state_changed_cb()
 236  * @see vc_unset_service_state_changed_cb()
 237  */
 238 int vc_get_service_state(vc_service_state_e* state);
 239
 240
 241 /**
 242  * @brief Gets the system command list.
 243  * @since_tizen 3.0
 244  * @privlevel public
 245  * @privilege %http://tizen.org/privilege/recorder
 246  * @remarks In the system command list, there are system commands predefined by product manufacturers. Those commands have the highest priority.
 247  *          Therefore, the user can not set any commands same with the system commands.
 248  *          The @a vc_sys_cmd_list must be released using vc_cmd_list_destroy() when it is no longer required.
 249  * @param[out] vc_sys_cmd_list System command list handle
 250  * @return @c 0 on success,
 251  *         otherwise a negative error value
 252  * @retval #VC_ERROR_NONE Successful
 253  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 254  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 255  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 256  * @retval #VC_ERROR_INVALID_STATE Invalid state
 257  * @pre The service state should be #VC_SERVICE_STATE_READY.
 258  * @see vc_cmd_list_destroy()
 259  */
 260 int vc_get_system_command_list(vc_cmd_list_h* vc_sys_cmd_list);
 261
 262
 263 /**
 264  * @brief Sets the invocation name.
 265  * @details Invocation name is used to activate background commands. The invocation name can be the same as the application name or any other phrase.
 266  *          For example, an application "Tizen Sample" has a background command, "Play music", and the invocation name of the application is set to "Tizen Sample".
 267  *          In order to activate the background command, users can say "Tizen Sample, Play music".
 268  *          The invocation name is dependent on the current language. For example, if the current language is "en_US"(English), the invocation name is also "en_US".
 269  *          If the current language is "ja_JP"(Japanese) and the invocation name is "en_US", the invocation name will not be recognized.
 270  *          This function should be called before vc_set_command_list().
 271  * @since_tizen 3.0
 272  * @privlevel public
 273  * @privilege %http://tizen.org/privilege/recorder
 274  * @remarks If @a name is @c NULL, the invocation name will be unset.
 275  * @param[in] name Invocation name that an application wants to be invoked by
 276  * @return @c 0 on success,
 277  *         otherwise a negative error value
 278  * @retval #VC_ERROR_NONE Successful
 279  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 280  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 281  * @retval #VC_ERROR_INVALID_STATE Invalid state
 282  * @pre The state should be #VC_STATE_READY.
 283  * @see vc_set_command_list()
 284  */
 285 int vc_set_invocation_name(const char* name);
 286
 287
 288 /**
 289  * @brief Requests to set app id which is to want to ask the server dialogue.
 290  * @details Using this function, the developer can request registering the application on vc framework.
 291  *          If developer requests to register @a app_id with @a credential which is valid, the application will be set on vc framework.
 292  *          and then, when the developer requests the dialogue using vc_request_dialog(), dialog from specific engine server will be played by vc framework.
 293  * @since_tizen 5.0
 294  * @privlevel public
 295  * @privilege %http://tizen.org/privilege/recorder
 296  * @remarks If @a app_id is @c NULL, the API tries to get app ID using app manager framework.
 297  *          However, getting app ID may be failed.
 298  * @param[in] app_id App id which is to want to ask server dialog.
 299  * @param[in] credential Credential key.
 300  * @return @c 0 on success,
 301  *         otherwise a negative error value
 302  * @retval #VC_ERROR_NONE Successful
 303  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 304  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 305  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 306  * @retval #VC_ERROR_INVALID_STATE Invalid state
 307  * @pre The service state should be #VC_SERVICE_STATE_READY.
 308  * @see vc_unset_server_dialog()
 309  */
 310 int vc_set_server_dialog(const char* app_id, const char* credential);
 311
 312
 313 /**
 314  * @brief Requests to unset app id which is to not want to ask the server dialogue.
 315  * @details Using this function, the developer can disable function to ask dialog based on server.
 316  * @since_tizen 5.0
 317  * @privlevel public
 318  * @privilege %http://tizen.org/privilege/recorder
 319  * @remarks If @a app_id is @c NULL, the API tries to get app ID using app manager framework.
 320  *          However, getting app ID may be failed.
 321  * @param[in] app_id App id which is to not want to ask server dialog.
 322  * @return @c 0 on success,
 323  *         otherwise a negative error value
 324  * @retval #VC_ERROR_NONE Successful
 325  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 326  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 327  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 328  * @retval #VC_ERROR_INVALID_STATE Invalid state
 329  * @pre The service state should be #VC_SERVICE_STATE_READY.
 330  * @see vc_set_server_dialog()
 331  */
 332 int vc_unset_server_dialog(const char* app_id);
 333
 334
 335 /**
 336  * @brief Requests to start the dialogue.
 337  * @details Using this function, the developer can request starting the dialogue to the framework.
 338  *          When the developer requests the dialogue, two types of texts, @a disp_text and @a utt_text, can be sent by this function.
 339  *          @a disp_text is a text for displaying, and @a utt_text is that for uttering.
 340  *          For example, if @a disp_text is "October 10th" and @a utt_text is "Today is October 10th.", "October 10th" will be displayed on the screen and "Today is October 10th." will be spoken.
 341  *          Also, the developer can set whether the dialogue starts automatically or not, using @a auto_start.
 342  *          If the developer sets @a auto_start as @c true, the framework will start to record next speech and continue the dialogue.
 343  * @since_tizen 3.0
 344  * @privlevel public
 345  * @privilege %http://tizen.org/privilege/recorder
 346  * @remarks If @a auto_start is @c true, the recognition will start again. In this case, it can be restarted up to 4 times.
 347  *          @a disp_text and @a utt_text allow @c NULL. However, it is not allowed to set both @a disp_text and @a utt_text as @c NULL.
 348  * @param[in] disp_text Text to be displayed on the screen
 349  * @param[in] utt_text Text to be spoken
 350  * @param[in] auto_start A variable for setting whether the dialog session will be restarted automatically or not
 351  * @return @c 0 on success,
 352  *         otherwise a negative error value
 353  * @retval #VC_ERROR_NONE Successful
 354  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 355  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 356  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 357  * @retval #VC_ERROR_INVALID_STATE Invalid state
 358  * @pre The service state should be #VC_SERVICE_STATE_READY.
 359  */
 360 int vc_request_dialog(const char* disp_text, const char* utt_text, bool auto_start);
 361
 362
 363 /**
 364  * @brief Sets command list.
 365  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 366  * @privlevel public
 367  * @privilege %http://tizen.org/privilege/recorder
 368  * @remarks The command type is valid for #VC_COMMAND_TYPE_FOREGROUND or #VC_COMMAND_TYPE_BACKGROUND.
 369  *          The matched commands of command list should be set and they should include type and command text at least.
 370  * @param[in] vc_cmd_list Command list handle
 371  * @param[in] type Command type
 372  * @return @c 0 on success,
 373  *         otherwise a negative error value
 374  * @retval #VC_ERROR_NONE Successful
 375  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 376  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 377  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 378  * @retval #VC_ERROR_INVALID_STATE Invalid state
 379  * @pre The state should be #VC_STATE_READY.
 380  * @see vc_unset_command_list()
 381  */
 382 int vc_set_command_list(vc_cmd_list_h vc_cmd_list, int type);
 383
 384
 385 /**
 386  * @brief Unsets command list.
 387  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 388  * @privlevel public
 389  * @privilege %http://tizen.org/privilege/recorder
 390  * @param[in] type Command type
 391  * @return @c 0 on success,
 392  *         otherwise a negative error value
 393  * @retval #VC_ERROR_NONE Successful
 394  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 395  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 396  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 397  * @retval #VC_ERROR_INVALID_STATE Invalid state
 398  * @pre The state should be #VC_STATE_READY.
 399  * @see vc_set_command_list()
 400  */
 401 int vc_unset_command_list(int type);
 402
 403
 404 /**
 405  * @brief Gets the recognition result.
 406  * @since_tizen 3.0
 407  * @privlevel public
 408  * @privilege %http://tizen.org/privilege/recorder
 409  * @param[in] callback Callback function to get recognition result
 410  * @param[in] user_data The user data to be passed to the callback function
 411  * @return @c 0 on success,
 412  *         otherwise a negative error value
 413  * @retval #VC_ERROR_NONE Successful
 414  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 415  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 416  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 417  * @retval #VC_ERROR_INVALID_STATE Invalid state
 418  * @pre The state should be #VC_STATE_READY.
 419  * @see vc_result_cb()
 420  */
 421 int vc_get_result(vc_result_cb callback, void* user_data);
 422
 423
 424 /**
 425  * @brief Sets a callback function for getting recognition result.
 426  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 427  * @privlevel public
 428  * @privilege %http://tizen.org/privilege/recorder
 429  * @param[in] callback Callback function to register
 430  * @param[in] user_data The user data to be passed to the callback function
 431  * @return @c 0 on success,
 432  *         otherwise a negative error value
 433  * @retval #VC_ERROR_NONE Successful
 434  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 435  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 436  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 437  * @retval #VC_ERROR_INVALID_STATE Invalid state
 438  * @pre The state should be #VC_STATE_INITIALIZED.
 439  * @see vc_result_cb()
 440  * @see vc_unset_result_cb()
 441  */
 442 int vc_set_result_cb(vc_result_cb callback, void* user_data);
 443
 444
 445 /**
 446  * @brief Unsets the callback function.
 447  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 448  * @privlevel public
 449  * @privilege %http://tizen.org/privilege/recorder
 450  * @return @c 0 on success,
 451  *         otherwise a negative error value
 452  * @retval #VC_ERROR_NONE Successful
 453  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 454  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 455  * @retval #VC_ERROR_INVALID_STATE Invalid state
 456  * @pre The state should be #VC_STATE_INITIALIZED.
 457  * @see vc_set_result_cb()
 458  */
 459 int vc_unset_result_cb(void);
 460
 461
 462 /**
 463  * @brief Sets a callback function to be called when service state is changed.
 464  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 465  * @privlevel public
 466  * @privilege %http://tizen.org/privilege/recorder
 467  * @param[in] callback Callback function to register
 468  * @param[in] user_data The user data to be passed to the callback function
 469  * @return @c 0 on success,
 470  *         otherwise a negative error value
 471  * @retval #VC_ERROR_NONE Successful
 472  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 473  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 474  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 475  * @retval #VC_ERROR_INVALID_STATE Invalid state
 476  * @pre The state should be #VC_STATE_INITIALIZED.
 477  * @see vc_service_state_changed_cb()
 478  * @see vc_unset_service_state_changed_cb()
 479  */
 480 int vc_set_service_state_changed_cb(vc_service_state_changed_cb callback, void* user_data);
 481
 482
 483 /**
 484  * @brief Unsets the callback function.
 485  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 486  * @privlevel public
 487  * @privilege %http://tizen.org/privilege/recorder
 488  * @return @c 0 on success,
 489  *         otherwise a negative error value
 490  * @retval #VC_ERROR_NONE Successful
 491  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 492  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 493  * @retval #VC_ERROR_INVALID_STATE Invalid state
 494  * @pre The state should be #VC_STATE_INITIALIZED.
 495  * @see vc_set_service_state_changed_cb()
 496  */
 497 int vc_unset_service_state_changed_cb(void);
 498
 499
 500 /**
 501  * @brief Sets a callback function to be called when state is changed.
 502  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 503  * @privlevel public
 504  * @privilege %http://tizen.org/privilege/recorder
 505  * @param[in] callback Callback function to register
 506  * @param[in] user_data The user data to be passed to the callback function
 507  * @return @c 0 on success,
 508  *         otherwise a negative error value
 509  * @retval #VC_ERROR_NONE Successful
 510  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 511  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 512  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 513  * @retval #VC_ERROR_INVALID_STATE Invalid state
 514  * @pre The state should be #VC_STATE_INITIALIZED.
 515  * @see vc_state_changed_cb()
 516  * @see vc_unset_state_changed_cb()
 517  */
 518 int vc_set_state_changed_cb(vc_state_changed_cb callback, void* user_data);
 519
 520
 521 /**
 522  * @brief Unsets the callback function.
 523  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 524  * @privlevel public
 525  * @privilege %http://tizen.org/privilege/recorder
 526  * @return @c 0 on success,
 527  *         otherwise a negative error value
 528  * @retval #VC_ERROR_NONE Successful
 529  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 530  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 531  * @retval #VC_ERROR_INVALID_STATE Invalid state
 532  * @pre The state should be #VC_STATE_INITIALIZED.
 533  * @see vc_set_state_changed_cb()
 534  */
 535 int vc_unset_state_changed_cb(void);
 536
 537
 538 /**
 539  * @brief Sets a callback function to be called when current language is changed.
 540  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 541  * @privlevel public
 542  * @privilege %http://tizen.org/privilege/recorder
 543  * @param[in] callback Callback function to register
 544  * @param[in] user_data The user data to be passed to the callback function
 545  * @return @c 0 on success,
 546  *         otherwise a negative error value
 547  * @retval #VC_ERROR_NONE Successful
 548  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 549  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 550  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 551  * @retval #VC_ERROR_INVALID_STATE Invalid state
 552  * @pre The state should be #VC_STATE_INITIALIZED.
 553  * @see vc_current_language_changed_cb()
 554  * @see vc_unset_current_language_changed_cb()
 555  */
 556 int vc_set_current_language_changed_cb(vc_current_language_changed_cb callback, void* user_data);
 557
 558
 559 /**
 560  * @brief Unsets the callback function.
 561  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 562  * @privlevel public
 563  * @privilege %http://tizen.org/privilege/recorder
 564  * @return @c 0 on success,
 565  *         otherwise a negative error value
 566  * @retval #VC_ERROR_NONE Successful
 567  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 568  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 569  * @retval #VC_ERROR_INVALID_STATE Invalid state
 570  * @pre The state should be #VC_STATE_INITIALIZED.
 571  * @see vc_set_current_language_changed_cb()
 572  */
 573 int vc_unset_current_language_changed_cb(void);
 574
 575
 576 /**
 577  * @brief Sets a callback function to be called when an error occurred.
 578  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 579  * @privlevel public
 580  * @privilege %http://tizen.org/privilege/recorder
 581  * @param[in] callback Callback function to register
 582  * @param[in] user_data The user data to be passed to the callback function
 583  * @return @c 0 on success,
 584  *         otherwise a negative error value
 585  * @retval #VC_ERROR_NONE Successful
 586  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 587  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 588  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 589  * @retval #VC_ERROR_INVALID_STATE Invalid state
 590  * @pre The state should be #VC_STATE_INITIALIZED.
 591  * @see vc_error_cb()
 592  * @see vc_unset_error_cb()
 593  */
 594 int vc_set_error_cb(vc_error_cb callback, void* user_data);
 595
 596
 597 /**
 598  * @brief Unsets the callback function.
 599  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 600  * @privlevel public
 601  * @privilege %http://tizen.org/privilege/recorder
 602  * @return @c 0 on success,
 603  *         otherwise a negative error value
 604  * @retval #VC_ERROR_NONE Successful
 605  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 606  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 607  * @retval #VC_ERROR_INVALID_STATE Invalid state
 608  * @pre The state should be #VC_STATE_INITIALIZED.
 609  * @see vc_set_error_cb()
 610  */
 611 int vc_unset_error_cb(void);
 612
 613
 614 /**
 615  * @partner
 616  * @brief Requests to send TTS streaming data, asynchronously.
 617  * @details Using this function, the developer can request text to speech to the framework.
 618  *          When the developer requests the TTS with @a language, VC engine will send PCM data which is synthesized using VC engine's own persona.
 619  *          If @a to_vc_manager is true, the synthesized PCM data will be delivered to the VC manager, otherwise it will be delivered to the VC client
 620  *          For example, if @a text is "Alarm is set as 7 PM" and @a to_vc_manager is true, the PCM data corresponding "Alarm is set as 7 PM" will be delivered to VC manager client,
 621  *          and then it will be spoken in VC manager. If @a to_vc_manager is false, you will receive PCM data through the vc_tts_streaming_cb() callback function if it was set using vc_tts_set_streaming_cb().
 622  *          This function is executed asynchronously, so if there is an error while synthesizing, vc_error_cb() will be called.
 623  * @since_tizen 5.5
 624  * @privlevel partner
 625  * @privilege %http://tizen.org/privilege/voicecontrol.tts
 626  * @param[in] text The text to be requested for TTS
 627  * @param[in] language The language is specified as an ISO 3166 alpha-2 two-letter country code
 628  *                     followed by ISO 639-1 for the two-letter language code.
 629  *                     For example, "ko_KR" for Korean, "en_US" for American English
 630  * @param[in] to_vc_manager The value for selection between VC client and VC manager\n
 631  *                          If @c true, the synthesized PCM data will be delivered to the VC manager, otherwise it will be delivered to the VC client
 632  * @param[out] utt_id The utterance id
 633  * @return @c 0 on success,
 634  *         otherwise a negative error value
 635  * @retval #VC_ERROR_NONE Successful
 636  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 637  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 638  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 639  * @retval #VC_ERROR_INVALID_STATE Invalid state
 640  * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 641  * @pre The state should be #VC_STATE_READY.
 642  * @see vc_tts_cancel()
 643  */
 644 int vc_tts_request(const char* text, const char* language, bool to_vc_manager, int* utt_id);
 645
 646
 647 /**
 648  * @partner
 649  * @brief Requests to cancel TTS streaming data.
 650  * @since_tizen 5.5
 651  * @privlevel partner
 652  * @privilege %http://tizen.org/privilege/voicecontrol.tts
 653  * @param[in] utt_id The utterance id
 654  * @return @c 0 on success,
 655  *         otherwise a negative error value
 656  * @retval #VC_ERROR_NONE Successful
 657  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 658  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 659  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 660  * @retval #VC_ERROR_INVALID_STATE Invalid state
 661  * @pre The state should be #VC_STATE_READY.
 662  * @see vc_tts_request()
 663  */
 664 int vc_tts_cancel(int utt_id);
 665
 666
 667 /**
 668  * @partner
 669  * @brief Gets the TTS audio details.
 670  * @details Using this function, the developer can get details of synthesized audio data which is requested by vc_tts_request() function.
 671  * @since_tizen 5.5
 672  * @privlevel partner
 673  * @privilege %http://tizen.org/privilege/voicecontrol.tts
 674  * @param[out] rate The audio sampling rate
 675  * @param[out] channel The audio channel
 676  * @param[out] audio_type The audio type
 677  * @return @c 0 on success,
 678  *         otherwise a negative error value
 679  * @retval #VC_ERROR_NONE Successful
 680  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 681  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 682  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 683  * @retval #VC_ERROR_INVALID_STATE Invalid state
 684  * @pre The state should be #VC_STATE_READY.
 685  */
 686 int vc_tts_get_synthesized_audio_details(int* rate, vc_audio_channel_e* channel, vc_audio_type_e* audio_type);
 687
 688
 689 /**
 690  * @partner
 691  * @brief Sets the TTS streaming callback function.
 692  * @since_tizen 5.5
 693  * @privlevel partner
 694  * @privilege %http://tizen.org/privilege/voicecontrol.tts
 695  * @param[in] callback The callback function
 696  * @param[in] user_data The user data to be passed to the callback function
 697  * @return @c 0 on success,
 698  *         otherwise a negative error value
 699  * @retval #VC_ERROR_NONE Successful
 700  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 701  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 702  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 703  * @retval #VC_ERROR_INVALID_STATE Invalid state
 704  * @pre The state should be #VC_STATE_INITIALIZED.
 705  */
 706 int vc_tts_set_streaming_cb(vc_tts_streaming_cb callback, void* user_data);
 707
 708
 709 /**
 710  * @partner
 711  * @brief Unsets the TTS streaming callback function.
 712  * @since_tizen 5.5
 713  * @privlevel partner
 714  * @privilege %http://tizen.org/privilege/voicecontrol.tts
 715  * @return @c 0 on success,
 716  *         otherwise a negative error value
 717  * @retval #VC_ERROR_NONE Successful
 718  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 719  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 720  * @retval #VC_ERROR_INVALID_STATE Invalid state
 721  * @pre The state should be #VC_STATE_INITIALIZED.
 722  */
 723 int vc_tts_unset_streaming_cb(void);
 724
 725
 726 /**
 727  * @partner
 728  * @brief Sets the TTS utterance status callback function.
 729  * @details Using this function, the developer can set the utterance status callback to be called
 730  *          when the VC manager client starts or stops playing TTS PCM data which was requested to be synthesized with the vc_tts_request() function.
 731  *          This function is called when to_vc_manager in the vc_tts_request() function call is @c true.
 732  * @since_tizen 5.5
 733  * @privlevel partner
 734  * @privilege %http://tizen.org/privilege/voicecontrol.tts
 735  * @param[in] callback The callback function
 736  * @param[in] user_data The user data to be passed to the callback function
 737  * @return @c 0 on success,
 738  *         otherwise a negative error value
 739  * @retval #VC_ERROR_NONE Successful
 740  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 741  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 742  * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
 743  * @retval #VC_ERROR_INVALID_STATE Invalid state
 744  * @retval #VC_ERROR_OPERATION_FAILED Operation failure
 745  * @pre The state should be #VC_STATE_INITIALIZED.
 746  */
 747 int vc_tts_set_utterance_status_cb(vc_tts_utterance_status_cb callback, void* user_data);
 748
 749
 750 /**
 751  * @partner
 752  * @brief Unsets the TTS utterance status callback function.
 753  * @since_tizen 5.5
 754  * @privlevel partner
 755  * @privilege %http://tizen.org/privilege/voicecontrol.tts
 756  * @return @c 0 on success,
 757  *         otherwise a negative error value
 758  * @retval #VC_ERROR_NONE Successful
 759  * @retval #VC_ERROR_NOT_SUPPORTED Not supported
 760  * @retval #VC_ERROR_PERMISSION_DENIED Permission denied
 761  * @retval #VC_ERROR_INVALID_STATE Invalid state
 762  * @pre The state should be #VC_STATE_INITIALIZED.
 763  */
 764 int vc_tts_unset_utterance_status_cb(void);
 765
 766
 767 #ifdef __cplusplus
 768 }
 769 #endif
 770
 771 /**
 772  * @}
 773  */
 774
 775 #endif /* __VOICE_CONTROL_H__ */