include/stt.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 __STT_H__
  19 #define __STT_H__
  20
  21
  22 #include <tizen.h>
  23
  24
  25 /**
  26  * @file stt.h
  27  */
  28
  29
  30 /**
  31 * @addtogroup CAPI_UIX_STT_MODULE
  32 * @{
  33 */
  34
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #endif
  40
  41
  42 /**
  43  * @brief Enumeration for error codes.
  44  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  45 */
  46 typedef enum {
  47         STT_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  48         STT_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */
  49         STT_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
  50         STT_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  51         STT_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< No answer from the STT service */
  52         STT_ERROR_RECORDER_BUSY = TIZEN_ERROR_RESOURCE_BUSY, /**< Device or resource busy */
  53         STT_ERROR_OUT_OF_NETWORK = TIZEN_ERROR_NETWORK_DOWN, /**< Network is down */
  54         STT_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  55         STT_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< STT NOT supported */
  56         STT_ERROR_INVALID_STATE = TIZEN_ERROR_STT | 0x01, /**< Invalid state */
  57         STT_ERROR_INVALID_LANGUAGE = TIZEN_ERROR_STT | 0x02, /**< Invalid language */
  58         STT_ERROR_ENGINE_NOT_FOUND = TIZEN_ERROR_STT | 0x03, /**< No available engine  */
  59         STT_ERROR_OPERATION_FAILED = TIZEN_ERROR_STT | 0x04, /**< Operation failed  */
  60         STT_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_STT | 0x05, /**< Not supported feature of current engine */
  61         STT_ERROR_RECORDING_TIMED_OUT = TIZEN_ERROR_STT | 0x06, /**< Recording timed out @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  62         STT_ERROR_NO_SPEECH = TIZEN_ERROR_STT | 0x07, /**< No speech while recording @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  63         STT_ERROR_IN_PROGRESS_TO_READY = TIZEN_ERROR_STT | 0x08, /**< Progress to ready is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  64         STT_ERROR_IN_PROGRESS_TO_RECORDING = TIZEN_ERROR_STT | 0x09, /**< Progress to recording is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  65         STT_ERROR_IN_PROGRESS_TO_PROCESSING = TIZEN_ERROR_STT | 0x10, /**< Progress to processing is not finished @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  66         STT_ERROR_SERVICE_RESET = TIZEN_ERROR_STT | 0x11 /**< Service reset @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
  67 } stt_error_e;
  68
  69
  70 /**
  71  * @brief Definition for free form dictation and default type.
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73 */
  74 #define STT_RECOGNITION_TYPE_FREE               "stt.recognition.type.FREE"
  75
  76
  77 /**
  78  * @brief Definition for continuous free dictation.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80 */
  81 #define STT_RECOGNITION_TYPE_FREE_PARTIAL       "stt.recognition.type.FREE.PARTIAL"
  82
  83
  84 /**
  85  * @brief Definition for search.
  86  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  87 */
  88 #define STT_RECOGNITION_TYPE_SEARCH             "stt.recognition.type.SEARCH"
  89
  90
  91 /**
  92  * @brief Definition for web search.
  93  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  94 */
  95 #define STT_RECOGNITION_TYPE_WEB_SEARCH         "stt.recognition.type.WEB_SEARCH"
  96
  97
  98 /**
  99  * @brief Definition for map.
 100  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 101 */
 102 #define STT_RECOGNITION_TYPE_MAP                "stt.recognition.type.MAP"
 103
 104
 105 /**
 106  * @brief Definition for none message.
 107  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 108 */
 109 #define STT_RESULT_MESSAGE_NONE                 "stt.result.message.none"
 110
 111
 112 /**
 113  * @brief Definition for failed recognition because the speech started too soon.
 114  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 115 */
 116 #define STT_RESULT_MESSAGE_ERROR_TOO_SOON       "stt.result.message.error.too.soon"
 117
 118
 119 /**
 120  * @brief Definition for failed recognition because the speech is too short.
 121  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 122 */
 123 #define STT_RESULT_MESSAGE_ERROR_TOO_SHORT      "stt.result.message.error.too.short"
 124
 125
 126 /**
 127  * @brief Definition for failed recognition because the speech is too long.
 128  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 129 */
 130 #define STT_RESULT_MESSAGE_ERROR_TOO_LONG       "stt.result.message.error.too.long"
 131
 132
 133 /**
 134  * @brief Definition for failed recognition because the speech is too quiet to listen.
 135  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 136 */
 137 #define STT_RESULT_MESSAGE_ERROR_TOO_QUIET      "stt.result.message.error.too.quiet"
 138
 139
 140 /**
 141  * @brief Definition for failed recognition because the speech is too loud to listen.
 142  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 143 */
 144 #define STT_RESULT_MESSAGE_ERROR_TOO_LOUD       "stt.result.message.error.too.loud"
 145
 146
 147 /**
 148  * @brief Definition for failed recognition because the speech is too fast to listen.
 149  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 150 */
 151 #define STT_RESULT_MESSAGE_ERROR_TOO_FAST       "stt.result.message.error.too.fast"
 152
 153
 154 /**
 155  * @brief Enumeration for state.
 156  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 157 */
 158 typedef enum {
 159         STT_STATE_CREATED = 0, /**< 'CREATED' state */
 160         STT_STATE_READY = 1, /**< 'READY' state */
 161         STT_STATE_RECORDING = 2, /**< 'RECORDING' state */
 162         STT_STATE_PROCESSING = 3 /**< 'PROCESSING' state*/
 163 } stt_state_e;
 164
 165
 166 /**
 167  * @brief Enumeration for result event.
 168  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 169 */
 170 typedef enum {
 171         STT_RESULT_EVENT_FINAL_RESULT = 0, /**< Event when the recognition full or last result is ready  */
 172         STT_RESULT_EVENT_PARTIAL_RESULT, /**< Event when the recognition partial result is ready  */
 173         STT_RESULT_EVENT_ERROR /**< Event when the recognition has failed */
 174 } stt_result_event_e;
 175
 176
 177 /**
 178  * @brief Enumeration for result time callback event.
 179  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 180 */
 181 typedef enum {
 182         STT_RESULT_TIME_EVENT_BEGINNING = 0, /**< Event when the token is beginning type */
 183         STT_RESULT_TIME_EVENT_MIDDLE = 1, /**< Event when the token is middle type */
 184         STT_RESULT_TIME_EVENT_END = 2 /**< Event when the token is end type */
 185 } stt_result_time_event_e;
 186
 187
 188 /**
 189  * @brief Enumeration for silence detection type.
 190  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 191 */
 192 typedef enum {
 193         STT_OPTION_SILENCE_DETECTION_FALSE = 0, /**< Silence detection type - False */
 194         STT_OPTION_SILENCE_DETECTION_TRUE = 1, /**< Silence detection type - True */
 195         STT_OPTION_SILENCE_DETECTION_AUTO = 2 /**< Silence detection type - Auto */
 196 } stt_option_silence_detection_e;
 197
 198
 199 /**
 200  * @brief A structure of STT handle.
 201  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 202 */
 203 typedef struct stt_s *stt_h;
 204
 205
 206 /**
 207  * @brief Called to get the engine information.
 208  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 209  * @param[in] engine_id Engine ID
 210  * @param[in] engine_name Engine name
 211  * @param[in] user_data User data passed from the stt_setting_foreach_supported_engines()
 212  * @return @c true to continue with the next iteration of the loop,
 213  *         otherwise @c false to break out of the loop
 214  * @pre stt_foreach_supported_engines() will invoke this callback.
 215  * @see stt_foreach_supported_engines()
 216 */
 217 typedef bool(*stt_supported_engine_cb)(stt_h stt, const char* engine_id, const char* engine_name, void* user_data);
 218
 219
 220 /**
 221  * @brief Called when STT gets the recognition result from the engine.
 222  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 223  * @remarks After stt_stop() is called, silence is detected from recording, or partial result is occured, this function is called.
 224  * @param[in] stt The STT handle
 225  * @param[in] event The result event
 226  * @param[in] data Result texts
 227  * @param[in] data_count Result text count
 228  * @param[in] msg Engine message (e.g. #STT_RESULT_MESSAGE_NONE, #STT_RESULT_MESSAGE_ERROR_TOO_SHORT)
 229  * @param[in] user_data The user data passed from the callback registration function
 230  * @pre stt_stop() will invoke this callback if you register it using stt_set_result_cb().
 231  * @post If this function is called and event is #STT_RESULT_EVENT_FINAL_RESULT, the STT state will be #STT_STATE_READY.
 232  * @see stt_stop()
 233  * @see stt_set_recognition_result_cb()
 234  * @see stt_unset_recognition_result_cb()
 235 */
 236 typedef void (*stt_recognition_result_cb)(stt_h stt, stt_result_event_e event, const char** data, int data_count,
 237                                           const char* msg, void *user_data);
 238
 239
 240 /**
 241  * @brief Called when STT get the result time stamp in free partial type.
 242  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 243  * @param[in] stt The STT handle
 244  * @param[in] index The result index
 245  * @param[in] event The token event
 246  * @param[in] text The result text
 247  * @param[in] start_time The start time of result text
 248  * @param[in] end_time The end time of result text
 249  * @param[in] user_data The user data passed from the foreach function
 250  * @return @c true to continue with the next iteration of the loop
 251  *         otherwise @c false to break out of the loop
 252  * @pre stt_recognition_result_cb() should be called.
 253  * @see stt_recognition_result_cb()
 254 */
 255 typedef bool (*stt_result_time_cb)(stt_h stt, int index, stt_result_time_event_e event, const char* text,
 256                                    long start_time, long end_time, void* user_data);
 257
 258
 259 /**
 260  * @brief Called when the state of STT is changed.
 261  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 262  * @param[in] stt The STT handle
 263  * @param[in] previous A previous state
 264  * @param[in] current A current state
 265  * @param[in] user_data The user data passed from the callback registration function
 266  * @pre An application registers this callback using stt_set_state_changed_cb() to detect changing state.
 267  * @see stt_set_state_changed_cb()
 268  * @see stt_unset_state_changed_cb()
 269 */
 270 typedef void (*stt_state_changed_cb)(stt_h stt, stt_state_e previous, stt_state_e current, void* user_data);
 271
 272
 273 /**
 274  * @brief Called when an error occurs.
 275  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 276  * @param[in] stt The STT handle
 277  * @param[in] reason The error type (e.g. #STT_ERROR_OUT_OF_NETWORK, #STT_ERROR_IO_ERROR)
 278  * @param[in] user_data The user data passed from the callback registration function
 279  * @pre An application registers this callback using stt_set_error_cb() to detect error.
 280  * @see stt_set_error_cb()
 281  * @see stt_unset_error_cb()
 282 */
 283 typedef void (*stt_error_cb)(stt_h stt, stt_error_e reason, void *user_data);
 284
 285
 286 /**
 287  * @brief Called to retrieve the supported languages.
 288  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 289  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code. For example, "ko_KR" for Korean, "en_US" for American English.
 290  * @param[in] stt The STT handle
 291  * @param[in] language The language
 292  * @param[in] user_data The user data passed from the foreach function
 293  * @return @c true to continue with the next iteration of the loop,
 294  *         @c false to break out of the loop
 295  * @pre stt_foreach_supported_languages() will invoke this callback.
 296  * @see stt_foreach_supported_languages()
 297 */
 298 typedef bool (*stt_supported_language_cb)(stt_h stt, const char* language, void* user_data);
 299
 300
 301 /**
 302  * @brief Called when the default language is changed.
 303  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 304  * @param[in] stt The STT handle
 305  * @param[in] previous_language A previous language
 306  * @param[in] current_language A current language
 307  * @param[in] user_data The user data passed from the callback registration function
 308  * @see stt_set_default_language_changed_cb()
 309 */
 310 typedef void (*stt_default_language_changed_cb)(stt_h stt, const char* previous_language,
 311                                                 const char* current_language, void* user_data);
 312
 313
 314 /**
 315  * @brief Called when the engine is changed.
 316  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 317  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code. For example, "ko_KR" for Korean, "en_US" for American English.
 318  * @param[in] stt The STT handle
 319  * @param[in] engine_id Engine ID
 320  * @param[in] language The default language
 321  * @param[in] support_silence Whether the silence detection is supported or not
 322  * @param[in] need_credential The necessity of credential
 323  * @param[in] user_data The user data passed from the callback registration function
 324  * @see stt_set_engine_changed_cb()
 325 */
 326 typedef void (*stt_engine_changed_cb)(stt_h stt, const char* engine_id, const char* language,
 327                                                 bool support_silence, bool need_credential, void* user_data);
 328
 329
 330 /**
 331  * @brief Creates a STT handle.
 332  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 333  * @privlevel public
 334  * @privilege %http://tizen.org/privilege/recorder
 335  * @remarks If the function succeeds, @a stt handle must be released with stt_destroy().
 336  * @param[out] stt The STT handle
 337  * @return @c 0 on success,
 338  *         otherwise a negative error value
 339  * @retval #STT_ERROR_NONE Successful
 340  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
 341  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 342  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 343  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 344  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 345  * @post If this function is called, the STT state will be #STT_STATE_CREATED.
 346  * @see stt_destroy()
 347 */
 348 int stt_create(stt_h* stt);
 349
 350
 351 /**
 352  * @brief Destroys a STT handle.
 353  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 354  * @privlevel public
 355  * @privilege %http://tizen.org/privilege/recorder
 356  * @param[in] stt The STT handle
 357  * @return @c 0 on success,
 358  *         otherwise a negative error value
 359  * @retval #STT_ERROR_NONE Successful
 360  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 361  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 362  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 363  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 364  * @see stt_create()
 365 */
 366 int stt_destroy(stt_h stt);
 367
 368
 369 /**
 370  * @brief Retrieves supported engine information using a callback function.
 371  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 372  * @privlevel public
 373  * @privilege %http://tizen.org/privilege/recorder
 374  * @param[in] stt The STT handle
 375  * @param[in] callback The callback function to invoke
 376  * @param[in] user_data The user data to be passed to the callback function
 377  * @return @c 0 on success,
 378  *         otherwise a negative error value
 379  * @retval #STT_ERROR_NONE Success
 380  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 381  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 382  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 383  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 384  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 385  * @pre The state should be #STT_STATE_CREATED.
 386  * @post This function invokes stt_supported_engine_cb() repeatedly for getting engine information.
 387  * @see stt_supported_engine_cb()
 388 */
 389 int stt_foreach_supported_engines(stt_h stt, stt_supported_engine_cb callback, void* user_data);
 390
 391
 392 /**
 393  * @brief Gets the current engine ID.
 394  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 395  * @privlevel public
 396  * @privilege %http://tizen.org/privilege/recorder
 397  * @remarks If the function is success, @a engine_id must be released using free().
 398  * @param[in] stt The STT handle
 399  * @param[out] engine_id Engine ID
 400  * @return @c 0 on success,
 401  *         otherwise a negative error value
 402  * @retval #STT_ERROR_NONE Success
 403  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 404  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 405  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 406  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 407  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 408  * @pre The state should be #STT_STATE_CREATED.
 409  * @see stt_set_engine()
 410 */
 411 int stt_get_engine(stt_h stt, char** engine_id);
 412
 413
 414 /**
 415  * @brief Sets the engine ID.
 416  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 417  * @privlevel public
 418  * @privilege %http://tizen.org/privilege/recorder
 419  * @privilege %http://tizen.org/privilege/appmanager.launch
 420  * @remarks A privilege (%http://tizen.org/privilege/appmanager.launch) is necessary since 3.0.
 421  * @param[in] stt The STT handle
 422  * @param[in] engine_id Engine ID
 423  * @return @c 0 on success,
 424  *         otherwise a negative error value
 425  * @retval #STT_ERROR_NONE Success
 426  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 427  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 428  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 429  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 430  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 431  * @pre The state should be #STT_STATE_CREATED.
 432  * @see stt_get_engine()
 433 */
 434 int stt_set_engine(stt_h stt, const char* engine_id);
 435
 436
 437 /**
 438  * @brief Sets the app credential.
 439  * @details Using this API, the application can set a credential.
 440  *          The credential is a key to verify the authorization about using the engine.
 441  *          If the application sets the credential, it will be able to use functions of the engine entirely.
 442  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 443  * @remarks The necessity of the credential depends on the engine. In case of the engine which is basically embedded in Tizen, the credential is not necessary so far.
 444  *          However, if the user wants to apply the 3rd party's engine, the credential may be necessary. In that case, please follow the policy provided by the corresponding engine.
 445  * @param[in] stt The STT handle
 446  * @param[in] credential The app credential
 447  * @return @c 0 on success,
 448  *         otherwise a negative error value
 449  * @retval #STT_ERROR_NONE Success
 450  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 451  * @retval #STT_ERROR_INVALID_STATE Invalid state
 452  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 453  * @pre The state should be #STT_STATE_CREATED or #STT_STATE_READY.
 454  * @see stt_start()
 455 */
 456 int stt_set_credential(stt_h stt, const char* credential);
 457
 458
 459 /**
 460  * @brief Sets the private data to stt engine.
 461  * @details The private data is the setting parameter for applying keys provided by the engine.
 462  *          Using this API, the application can set the private data and use the corresponding key of the engine.
 463  *          For example, if the engine provides 'partial recognition' as a recognition type, the application can set the private data as the following.
 464  *          int ret = stt_set_private_data(stt_h, "recognition_type", "PARTIAL");
 465  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 466  * @remarks If the engine is replaced with the other engine, the key may be ignored.
 467  * @param[in] stt The STT handle
 468  * @param[in] key The field name of private data
 469  * @param[in] data The data for set
 470  * @return @c 0 on success,
 471  *         otherwise a negative error value
 472  * @retval #STT_ERROR_NONE Successful
 473  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 474  * @retval #STT_ERROR_INVALID_STATE Invalid state
 475  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 476  * @retval #STT_ERROR_TIMED_OUT No answer from the STT service
 477  * @pre The state should be #STT_STATE_READY.
 478  * @see stt_get_private_data()
 479 */
 480 int stt_set_private_data(stt_h stt, const char* key, const char* data);
 481
 482
 483 /**
 484  * @brief Gets the private data from stt engine.
 485  * @details The private data is the information provided by the engine.
 486  *          Using this API, the application can get the private data which corresponds to the key from the engine.
 487  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 488  * @remarks If the engine is replaced with the other engine, the key may be ignored.
 489  * @remarks The @a data must be released using free() when it is no longer required.
 490  * @param[in] stt The STT handle
 491  * @param[in] key The field name of private data
 492  * @param[out] data The data field of private data
 493  * @return @c 0 on success,
 494  *         otherwise a negative error value
 495  * @retval #STT_ERROR_NONE Successful
 496  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 497  * @retval #STT_ERROR_INVALID_STATE Invalid state
 498  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 499  * @retval #STT_ERROR_TIMED_OUT No answer from the STT service
 500  * @pre The state should be #STT_STATE_READY.
 501  * @see stt_set_private_data()
 502 */
 503 int stt_get_private_data(stt_h stt, const char* key, char** data);
 504
 505
 506 /**
 507  * @brief Connects the STT service asynchronously.
 508  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 509  * @privlevel public
 510  * @privilege %http://tizen.org/privilege/recorder
 511  * @param[in] stt The STT handle
 512  * @return @c 0 on success,
 513  *         otherwise a negative error value
 514  * @retval #STT_ERROR_NONE Successful
 515  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 516  * @retval #STT_ERROR_INVALID_STATE Invalid state
 517  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 518  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 519  * @pre The state should be #STT_STATE_CREATED.
 520  * @post If this function is successful, the STT state will be #STT_STATE_READY.
 521  *       If this function is failed, the error callback is called. (e.g. #STT_ERROR_ENGINE_NOT_FOUND)
 522  * @see stt_unprepare()
 523 */
 524 int stt_prepare(stt_h stt);
 525
 526
 527 /**
 528  * @brief Disconnects the STT service.
 529  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 530  * @privlevel public
 531  * @privilege %http://tizen.org/privilege/recorder
 532  * @param[in] stt The STT handle
 533  * @return @c 0 on success,
 534  *         otherwise a negative error value
 535  * @retval #STT_ERROR_NONE Successful
 536  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 537  * @retval #STT_ERROR_INVALID_STATE Invalid state
 538  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 539  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 540  * @pre The state should be #STT_STATE_READY.
 541  * @post If this function is called, the STT state will be #STT_STATE_CREATED.
 542  * @see stt_prepare()
 543 */
 544 int stt_unprepare(stt_h stt);
 545
 546
 547 /**
 548  * @brief Retrieves all supported languages of current engine using callback function.
 549  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 550  * @privlevel public
 551  * @privilege %http://tizen.org/privilege/recorder
 552  * @param[in] stt The STT handle
 553  * @param[in] callback The callback function to invoke
 554  * @param[in] user_data The user data to be passed to the callback function
 555  * @return @c 0 on success,
 556  *         otherwise a negative error value
 557  * @retval #STT_ERROR_NONE Successful
 558  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 559  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
 560  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 561  * @retval #STT_ERROR_ENGINE_NOT_FOUND No available engine
 562  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 563  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 564  * @post This function invokes stt_supported_language_cb() repeatedly for getting languages.
 565  * @see stt_supported_language_cb()
 566  * @see stt_get_default_language()
 567 */
 568 int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callback, void* user_data);
 569
 570
 571 /**
 572  * @brief Gets the default language set by the user.
 573  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 574  * @privlevel public
 575  * @privilege %http://tizen.org/privilege/recorder
 576  * @remarks The language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code.
 577  *          For example, "ko_KR" for Korean, "en_US" for American English.
 578  *          If the function succeeds, @a language must be released using free() when it is no longer required.
 579  * @param[in] stt The STT handle
 580  * @param[out] language The language
 581  * @return @c 0 on success,
 582  *         otherwise a negative error value
 583  * @retval #STT_ERROR_NONE Successful
 584  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 585  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 586  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 587  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 588  * @see stt_foreach_supported_languages()
 589 */
 590 int stt_get_default_language(stt_h stt, char** language);
 591
 592
 593 /**
 594  * @brief Gets the current STT state.
 595  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 596  * @privlevel public
 597  * @privilege %http://tizen.org/privilege/recorder
 598  * @param[in] stt The STT handle
 599  * @param[out] state The current STT state
 600  * @return @c 0 on success,
 601  *         otherwise a negative error value
 602  * @retval #STT_ERROR_NONE Successful
 603  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 604  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 605  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 606  * @see stt_start()
 607  * @see stt_stop()
 608  * @see stt_cancel()
 609  * @see stt_state_changed_cb()
 610 */
 611 int stt_get_state(stt_h stt, stt_state_e* state);
 612
 613
 614 /**
 615  * @brief Gets the current error message.
 616  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 617  * @remarks This function should be called during an stt error callback. If not, the error as operation failure will be returned.
 618  *          If the function succeeds, @a err_msg must be released using free() when it is no longer required.
 619  * @param[in] stt The STT handle
 620  * @param[out] err_msg The current error message
 621  * @return @c 0 on success,
 622  *         otherwise a negative error value
 623  * @retval #STT_ERROR_NONE Successful
 624  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 625  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 626  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 627  * @see stt_set_error_cb()
 628  * @see stt_unset_error_cb()
 629 */
 630 int stt_get_error_message(stt_h stt, char** err_msg);
 631
 632
 633 /**
 634  * @brief Checks whether the recognition type is supported.
 635  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 636  * @privlevel public
 637  * @privilege %http://tizen.org/privilege/recorder
 638  * @param[in] stt The STT handle
 639  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
 640  * @param[out] support The result status @c true = supported,
 641  *                     @c false = not supported
 642  * @return @c 0 on success,
 643  *         otherwise a negative error value
 644  * @retval #STT_ERROR_NONE Successful
 645  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 646  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 647  * @retval #STT_ERROR_INVALID_STATE Invalid state
 648  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 649  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 650  * @pre The state should be #STT_STATE_READY.
 651 */
 652 int stt_is_recognition_type_supported(stt_h stt, const char* type, bool* support);
 653
 654
 655 /**
 656  * @brief Sets the silence detection.
 657  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 658  * @privlevel public
 659  * @privilege %http://tizen.org/privilege/recorder
 660  * @param[in] stt The STT handle
 661  * @param[in] type The option type
 662  * @return @c 0 on success,
 663  *         otherwise a negative error value
 664  * @retval #STT_ERROR_NONE Successful
 665  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 666  * @retval #STT_ERROR_INVALID_STATE Invalid state
 667  * @retval #STT_ERROR_NOT_SUPPORTED_FEATURE Not supported feature of current engine
 668  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 669  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 670  * @pre The state should be #STT_STATE_READY.
 671 */
 672 int stt_set_silence_detection(stt_h stt, stt_option_silence_detection_e type);
 673
 674
 675 /**
 676  * @brief Sets the sound to start recording.
 677  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 678  * @privlevel public
 679  * @privilege %http://tizen.org/privilege/recorder
 680  * @remarks Sound file type should be wav type.
 681  * @param[in] stt The STT handle
 682  * @param[in] filename The sound file path
 683  * @return @c 0 on success,
 684  *         otherwise a negative error value
 685  * @retval #STT_ERROR_NONE Successful
 686  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 687  * @retval #STT_ERROR_INVALID_STATE Invalid state
 688  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 689  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 690  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 691  * @pre The state should be #STT_STATE_READY.
 692 */
 693 int stt_set_start_sound(stt_h stt, const char* filename);
 694
 695
 696 /**
 697  * @brief Unsets the sound to start recording.
 698  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 699  * @privlevel public
 700  * @privilege %http://tizen.org/privilege/recorder
 701  * @param[in] stt The STT handle
 702  * @return @c 0 on success,
 703  *         otherwise a negative error value
 704  * @retval #STT_ERROR_NONE Successful
 705  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 706  * @retval #STT_ERROR_INVALID_STATE Invalid state
 707  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 708  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 709  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 710  * @pre The state should be #STT_STATE_READY.
 711 */
 712 int stt_unset_start_sound(stt_h stt);
 713
 714
 715 /**
 716  * @brief Sets the sound to stop recording.
 717  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 718  * @privlevel public
 719  * @privilege %http://tizen.org/privilege/recorder
 720  * @remarks Sound file type should be wav type.
 721  * @param[in] stt The STT handle
 722  * @param[in] filename The sound file path
 723  * @return @c 0 on success,
 724  *         otherwise a negative error value
 725  * @retval #STT_ERROR_NONE Successful
 726  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 727  * @retval #STT_ERROR_INVALID_STATE Invalid state
 728  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 729  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 730  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 731  * @pre The state should be #STT_STATE_READY.
 732 */
 733 int stt_set_stop_sound(stt_h stt, const char* filename);
 734
 735
 736 /**
 737  * @brief Unsets the sound to stop recording.
 738  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 739  * @privlevel public
 740  * @privilege %http://tizen.org/privilege/recorder
 741  * @param[in] stt The STT handle
 742  * @return @c 0 on success,
 743  *         otherwise a negative error value
 744  * @retval #STT_ERROR_NONE Successful
 745  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 746  * @retval #STT_ERROR_INVALID_STATE Invalid state
 747  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 748  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 749  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 750  * @pre The state should be #STT_STATE_READY.
 751 */
 752 int stt_unset_stop_sound(stt_h stt);
 753
 754
 755 /**
 756  * @brief Starts recording and recognition asynchronously.
 757  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 758  * @privlevel public
 759  * @privilege %http://tizen.org/privilege/recorder
 760  * @remarks This function starts recording in the STT service and sending recording data to engine.
 761  *          This work continues until stt_stop(), stt_cancel() or silence detected by engine.
 762  * @param[in] stt The STT handle
 763  * @param[in] language The language selected from stt_foreach_supported_languages()
 764  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
 765  * @return @c 0 on success,
 766  *         otherwise a negative error value
 767  * @retval #STT_ERROR_NONE Successful
 768  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 769  * @retval #STT_ERROR_INVALID_STATE Invalid state
 770  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 771  * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
 772  * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
 773  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 774  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 775  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 776  * @pre The state should be #STT_STATE_READY.
 777  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 778  *       If this function succeeds, the STT state will be #STT_STATE_RECORDING.
 779  *       If you call this function again before state changes, you will receive STT_ERROR_IN_PROGRESS_TO_RECORDING.
 780  * @see stt_stop()
 781  * @see stt_cancel()
 782  * @see stt_state_changed_cb()
 783 */
 784 int stt_start(stt_h stt, const char* language, const char* type);
 785
 786
 787 /**
 788  * @brief Finishes the recording and starts recognition processing in engine asynchronously.
 789  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 790  * @privlevel public
 791  * @privilege %http://tizen.org/privilege/recorder
 792  * @param[in] stt The STT handle
 793  * @return @c 0 on success,
 794  *         otherwise a negative error value
 795  * @retval #STT_ERROR_NONE Successful
 796  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 797  * @retval #STT_ERROR_INVALID_STATE Invalid state
 798  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 799  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 800  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 801  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
 802  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 803  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
 804  * @pre The state should be #STT_STATE_RECORDING.
 805  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 806  *       If this function succeeds, the STT state will be #STT_STATE_PROCESSING.
 807  *       If you call this function again before state changes, you will receive STT_ERROR_IN_PROGRESS_TO_PROCESSING.
 808  *       After processing of engine, stt_result_cb() is called.
 809  * @see stt_start()
 810  * @see stt_cancel()
 811  * @see stt_state_changed_cb()
 812 */
 813 int stt_stop(stt_h stt);
 814
 815
 816 /**
 817  * @brief Cancels processing recognition and recording asynchronously.
 818  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 819  * @privlevel public
 820  * @privilege %http://tizen.org/privilege/recorder
 821  * @remarks This function cancels recording and engine cancels recognition processing.
 822  *          After successful cancel, stt_state_changed_cb() is called otherwise if error is occurred, stt_error_cb() is called.
 823  * @param[in] stt The STT handle
 824  * @return @c 0 on success,
 825  *         otherwise a negative error value
 826  * @retval #STT_ERROR_NONE Successful
 827  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 828  * @retval #STT_ERROR_INVALID_STATE Invalid state
 829  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 830  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 831  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 832  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
 833  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 834  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
 835  * @pre The state should be #STT_STATE_RECORDING or #STT_STATE_PROCESSING.
 836  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 837  *       If this function succeeds, the STT state will be #STT_STATE_READY.
 838  *       If you call this function again before state changes, you will receive STT_ERROR_IN_PROGRESS_TO_READY.
 839  * @see stt_start()
 840  * @see stt_stop()
 841  * @see stt_state_changed_cb()
 842 */
 843 int stt_cancel(stt_h stt);
 844
 845
 846 /**
 847  * @brief Gets the microphone volume during recording.
 848  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 849  * @privlevel public
 850  * @privilege %http://tizen.org/privilege/recorder
 851  * @param[in] stt The STT handle
 852  * @param[out] volume Recording volume
 853  * @return @c 0 on success,
 854  *         otherwise a negative error value
 855  * @retval #STT_ERROR_NONE Successful
 856  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 857  * @retval #STT_ERROR_INVALID_STATE Invalid state
 858  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 859  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 860  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 861  * @pre The state should be #STT_STATE_RECORDING.
 862  * @see stt_start()
 863 */
 864 int stt_get_recording_volume(stt_h stt, float* volume);
 865
 866
 867 /**
 868  * @brief Retrieves the time stamp of the current recognition result using the callback function.
 869  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 870  * @privlevel public
 871  * @privilege %http://tizen.org/privilege/recorder
 872  * @remarks This function should be called in stt_recognition_result_cb().
 873  *          After stt_recognition_result_cb(), result data is NOT valid.
 874  * @param[in] stt The STT handle
 875  * @param[in] callback The callback function to invoke
 876  * @param[in] user_data The user data to be passed to the callback function
 877  * @return @c 0 on success,
 878  *         otherwise a negative error value
 879  * @retval #STT_ERROR_NONE Successful
 880  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 881  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 882  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 883  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 884  * @pre This function should be called in stt_recognition_result_cb().
 885  * @post This function invokes stt_result_time_cb() repeatedly for getting time information.
 886  * @see stt_result_time_cb()
 887  * @see stt_recognition_result_cb()
 888 */
 889 int stt_foreach_detailed_result(stt_h stt, stt_result_time_cb callback, void* user_data);
 890
 891
 892 /**
 893  * @brief Registers a callback function to get the recognition result.
 894  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 895  * @privlevel public
 896  * @privilege %http://tizen.org/privilege/recorder
 897  * @param[in] stt The STT handle
 898  * @param[in] callback The callback function to register
 899  * @param[in] user_data The user data to be passed to the callback function
 900  * @return @c 0 on success,
 901  *         otherwise a negative error value
 902  * @retval #STT_ERROR_NONE Successful
 903  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 904  * @retval #STT_ERROR_INVALID_STATE Invalid state
 905  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 906  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 907  * @pre The state should be #STT_STATE_CREATED.
 908  * @see stt_recognition_result_cb()
 909  * @see stt_unset_recognition_result_cb()
 910 */
 911 int stt_set_recognition_result_cb(stt_h stt, stt_recognition_result_cb callback, void* user_data);
 912
 913
 914 /**
 915  * @brief Unregisters the callback function.
 916  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 917  * @privlevel public
 918  * @privilege %http://tizen.org/privilege/recorder
 919  * @param[in] stt The STT handle
 920  * @return @c 0 on success,
 921  *         otherwise a negative error value
 922  * @retval #STT_ERROR_NONE Successful
 923  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 924  * @retval #STT_ERROR_INVALID_STATE Invalid state
 925  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 926  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 927  * @pre The state should be #STT_STATE_CREATED.
 928  * @see stt_set_recognition_result_cb()
 929 */
 930 int stt_unset_recognition_result_cb(stt_h stt);
 931
 932
 933 /**
 934  * @brief Registers a callback function to be called when STT state changes.
 935  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 936  * @privlevel public
 937  * @privilege %http://tizen.org/privilege/recorder
 938  * @param[in] stt The STT handle
 939  * @param[in] callback The callback function to register
 940  * @param[in] user_data The user data to be passed to the callback function
 941  * @return @c 0 on success,
 942  *         otherwise a negative error value
 943  * @retval #STT_ERROR_NONE Successful
 944  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 945  * @retval #STT_ERROR_INVALID_STATE Invalid state
 946  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 947  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 948  * @pre The state should be #STT_STATE_CREATED.
 949  * @see stt_state_changed_cb()
 950  * @see stt_unset_state_changed_cb()
 951 */
 952 int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* user_data);
 953
 954
 955 /**
 956  * @brief Unregisters the callback function.
 957  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 958  * @privlevel public
 959  * @privilege %http://tizen.org/privilege/recorder
 960  * @param[in] stt The STT handle
 961  * @return @c 0 on success,
 962  *         otherwise a negative error value
 963  * @retval #STT_ERROR_NONE Successful
 964  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 965  * @retval #STT_ERROR_INVALID_STATE Invalid state
 966  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 967  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 968  * @pre The state should be #STT_STATE_CREATED.
 969  * @see stt_set_state_changed_cb()
 970 */
 971 int stt_unset_state_changed_cb(stt_h stt);
 972
 973
 974 /**
 975  * @brief Registers a callback function to be called when an error occurred.
 976  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 977  * @privlevel public
 978  * @privilege %http://tizen.org/privilege/recorder
 979  * @param[in] stt The STT handle
 980  * @param[in] callback The callback function to register
 981  * @param[in] user_data The user data to be passed to the callback function
 982  * @return @c 0 on success,
 983  *         otherwise a negative error value
 984  * @retval #STT_ERROR_NONE Successful
 985  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 986  * @retval #STT_ERROR_INVALID_STATE Invalid state
 987  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 988  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 989  * @pre The state should be #STT_STATE_CREATED.
 990  * @see stt_error_cb()
 991  * @see stt_unset_error_cb()
 992 */
 993 int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
 994
 995
 996 /**
 997  * @brief Unregisters the callback function.
 998  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 999  * @privlevel public
1000  * @privilege %http://tizen.org/privilege/recorder
1001  * @param[in] stt The STT handle
1002  * @return @c 0 on success,
1003  *         otherwise a negative error value
1004  * @retval #STT_ERROR_NONE Successful
1005  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1006  * @retval #STT_ERROR_INVALID_STATE Invalid state
1007  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1008  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1009  * @pre The state should be #STT_STATE_CREATED.
1010  * @see stt_set_error_cb()
1011 */
1012 int stt_unset_error_cb(stt_h stt);
1013
1014
1015 /**
1016  * @brief Registers a callback function to detect the default language change.
1017  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1018  * @privlevel public
1019  * @privilege %http://tizen.org/privilege/recorder
1020  * @param[in] stt The STT handle
1021  * @param[in] callback The callback function to register
1022  * @param[in] user_data The user data to be passed to the callback function
1023  * @return @c 0 on success,
1024  *         otherwise a negative error value
1025  * @retval #STT_ERROR_NONE Successful
1026  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1027  * @retval #STT_ERROR_INVALID_STATE Invalid state
1028  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1029  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1030  * @pre The state should be #STT_STATE_CREATED.
1031  * @see stt_default_language_changed_cb()
1032  * @see stt_unset_default_language_changed_cb()
1033 */
1034 int stt_set_default_language_changed_cb(stt_h stt, stt_default_language_changed_cb callback, void* user_data);
1035
1036
1037 /**
1038  * @brief Unregisters the callback function.
1039  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1040  * @privlevel public
1041  * @privilege %http://tizen.org/privilege/recorder
1042  * @param[in] stt The STT handle
1043  * @return @c 0 on success,
1044  *         otherwise a negative error value
1045  * @retval #STT_ERROR_NONE Successful
1046  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1047  * @retval #STT_ERROR_INVALID_STATE Invalid state
1048  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1049  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1050  * @pre The state should be #STT_STATE_CREATED.
1051  * @see stt_set_default_language_changed_cb()
1052 */
1053 int stt_unset_default_language_changed_cb(stt_h stt);
1054
1055
1056 /**
1057  * @brief Registers a callback function to detect the engine change.
1058  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1059  * @param[in] stt The STT handle
1060  * @param[in] callback The callback function to register
1061  * @param[in] user_data The user data to be passed to the callback function
1062  * @return @c 0 on success,
1063  *         otherwise a negative error value
1064  * @retval #STT_ERROR_NONE Successful
1065  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1066  * @retval #STT_ERROR_INVALID_STATE Invalid state
1067  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1068  * @pre The state should be #STT_STATE_CREATED.
1069  * @see stt_engine_changed_cb()
1070  * @see stt_unset_engine_changed_cb()
1071 */
1072 int stt_set_engine_changed_cb(stt_h stt, stt_engine_changed_cb callback, void* user_data);
1073
1074
1075 /**
1076  * @brief Unregisters the callback function.
1077  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1078  * @param[in] stt The STT handle
1079  * @return @c 0 on success,
1080  *         otherwise a negative error value
1081  * @retval #STT_ERROR_NONE Successful
1082  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1083  * @retval #STT_ERROR_INVALID_STATE Invalid state
1084  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1085  * @pre The state should be #STT_STATE_CREATED.
1086  * @see stt_set_engine_changed_cb()
1087 */
1088 int stt_unset_engine_changed_cb(stt_h stt);
1089
1090
1091 #ifdef __cplusplus
1092 }
1093 #endif
1094
1095
1096 /**
1097  * @}@}
1098  */
1099
1100
1101 #endif /* __STT_H__ */
1102