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 * @brief Enumeration for speech status.
 200 * @since_tizen 5.5
 201 */
 202 typedef enum {
 203         STT_SPEECH_STATUS_BEGINNING_OF_SPEECH_DETECTED = 0, /**< Beginning Of Speech is detected */
 204         STT_SPEECH_STATUS_END_OF_SPEECH_DETECTED /**< End Of Speech is detected */
 205 } stt_speech_status_e;
 206
 207
 208 /**
 209  * @brief A structure of STT handle.
 210  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 211 */
 212 typedef struct stt_s *stt_h;
 213
 214
 215 /**
 216  * @brief Called to get the engine information.
 217  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 218  * @param[in] stt The STT handle
 219  * @param[in] engine_id Engine ID
 220  * @param[in] engine_name Engine name
 221  * @param[in] user_data User data passed from the stt_setting_foreach_supported_engines()
 222  * @return @c true to continue with the next iteration of the loop,
 223  *         otherwise @c false to break out of the loop
 224  * @pre stt_foreach_supported_engines() will invoke this callback.
 225  * @see stt_foreach_supported_engines()
 226 */
 227 typedef bool(*stt_supported_engine_cb)(stt_h stt, const char* engine_id, const char* engine_name, void* user_data);
 228
 229
 230 /**
 231  * @brief Called when STT gets the recognition result from the engine.
 232  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 233  * @remarks After stt_stop() is called, silence is detected from recording, or partial result is occurred, this function is called.
 234  * @param[in] stt The STT handle
 235  * @param[in] event The result event
 236  * @param[in] data Result texts
 237  * @param[in] data_count Result text count
 238  * @param[in] msg Engine message (e.g. #STT_RESULT_MESSAGE_NONE, #STT_RESULT_MESSAGE_ERROR_TOO_SHORT)
 239  * @param[in] user_data The user data passed from the callback registration function
 240  * @pre stt_stop() will invoke this callback if you register it using stt_set_result_cb().
 241  * @post If this function is called and event is #STT_RESULT_EVENT_FINAL_RESULT, the STT state will be #STT_STATE_READY.
 242  * @see stt_stop()
 243  * @see stt_set_recognition_result_cb()
 244  * @see stt_unset_recognition_result_cb()
 245 */
 246 typedef void (*stt_recognition_result_cb)(stt_h stt, stt_result_event_e event, const char** data, int data_count,
 247                                           const char* msg, void *user_data);
 248
 249
 250 /**
 251  * @brief Called when STT get the result time stamp in free partial type.
 252  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 253  * @param[in] stt The STT handle
 254  * @param[in] index The result index
 255  * @param[in] event The token event
 256  * @param[in] text The result text
 257  * @param[in] start_time The start time of result text
 258  * @param[in] end_time The end time of result text
 259  * @param[in] user_data The user data passed from the foreach function
 260  * @return @c true to continue with the next iteration of the loop
 261  *         otherwise @c false to break out of the loop
 262  * @pre stt_recognition_result_cb() should be called.
 263  * @see stt_recognition_result_cb()
 264 */
 265 typedef bool (*stt_result_time_cb)(stt_h stt, int index, stt_result_time_event_e event, const char* text,
 266                                    long start_time, long end_time, void* user_data);
 267
 268
 269 /**
 270  * @brief Called when the state of STT is changed.
 271  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 272  * @param[in] stt The STT handle
 273  * @param[in] previous A previous state
 274  * @param[in] current A current state
 275  * @param[in] user_data The user data passed from the callback registration function
 276  * @pre An application registers this callback using stt_set_state_changed_cb() to detect changing state.
 277  * @see stt_set_state_changed_cb()
 278  * @see stt_unset_state_changed_cb()
 279 */
 280 typedef void (*stt_state_changed_cb)(stt_h stt, stt_state_e previous, stt_state_e current, void* user_data);
 281
 282
 283 /**
 284  * @brief Called when an error occurs.
 285  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 286  * @param[in] stt The STT handle
 287  * @param[in] reason The error type (e.g. #STT_ERROR_OUT_OF_NETWORK, #STT_ERROR_IO_ERROR)
 288  * @param[in] user_data The user data passed from the callback registration function
 289  * @pre An application registers this callback using stt_set_error_cb() to detect error.
 290  * @see stt_set_error_cb()
 291  * @see stt_unset_error_cb()
 292 */
 293 typedef void (*stt_error_cb)(stt_h stt, stt_error_e reason, void *user_data);
 294
 295
 296 /**
 297  * @brief Called to retrieve the supported languages.
 298  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 299  * @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.
 300  * @param[in] stt The STT handle
 301  * @param[in] language The language
 302  * @param[in] user_data The user data passed from the foreach function
 303  * @return @c true to continue with the next iteration of the loop,
 304  *         @c false to break out of the loop
 305  * @pre stt_foreach_supported_languages() will invoke this callback.
 306  * @see stt_foreach_supported_languages()
 307 */
 308 typedef bool (*stt_supported_language_cb)(stt_h stt, const char* language, void* user_data);
 309
 310
 311 /**
 312  * @brief Called when the default language is changed.
 313  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 314  * @param[in] stt The STT handle
 315  * @param[in] previous_language A previous language
 316  * @param[in] current_language A current language
 317  * @param[in] user_data The user data passed from the callback registration function
 318  * @see stt_set_default_language_changed_cb()
 319 */
 320 typedef void (*stt_default_language_changed_cb)(stt_h stt, const char* previous_language,
 321                                                 const char* current_language, void* user_data);
 322
 323
 324 /**
 325  * @brief Called when the engine is changed.
 326  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 327  * @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.
 328  * @param[in] stt The STT handle
 329  * @param[in] engine_id Engine ID
 330  * @param[in] language The default language
 331  * @param[in] support_silence Whether the silence detection is supported or not
 332  * @param[in] need_credential The necessity of credential
 333  * @param[in] user_data The user data passed from the callback registration function
 334  * @see stt_set_engine_changed_cb()
 335 */
 336 typedef void (*stt_engine_changed_cb)(stt_h stt, const char* engine_id, const char* language,
 337                                                 bool support_silence, bool need_credential, void* user_data);
 338
 339
 340 /**
 341  * @brief Called when STT engine detects beginning or ending of the speech.
 342  * @since_tizen 5.5
 343  * @param[in] stt The STT handle
 344  * @param[in] status The speech status
 345  * @param[in] user_data The user data passed from the callback registration function
 346  * @see stt_set_speech_status_cb()
 347  */
 348 typedef void (*stt_speech_status_cb)(stt_h stt, stt_speech_status_e status, void *user_data);
 349
 350
 351 /**
 352  * @brief Creates 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  * @remarks If the function succeeds, @a stt handle must be released with stt_destroy().
 357  * @param[out] stt The STT handle
 358  * @return @c 0 on success,
 359  *         otherwise a negative error value
 360  * @retval #STT_ERROR_NONE Successful
 361  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
 362  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 363  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 364  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 365  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 366  * @post If this function is called, the STT state will be #STT_STATE_CREATED.
 367  * @see stt_destroy()
 368 */
 369 int stt_create(stt_h* stt);
 370
 371
 372 /**
 373  * @brief Destroys a STT handle.
 374  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 375  * @privlevel public
 376  * @privilege %http://tizen.org/privilege/recorder
 377  * @param[in] stt The STT handle
 378  * @return @c 0 on success,
 379  *         otherwise a negative error value
 380  * @retval #STT_ERROR_NONE Successful
 381  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 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  * @see stt_create()
 386 */
 387 int stt_destroy(stt_h stt);
 388
 389
 390 /**
 391  * @brief Retrieves supported engine information using a callback function.
 392  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 393  * @privlevel public
 394  * @privilege %http://tizen.org/privilege/recorder
 395  * @param[in] stt The STT handle
 396  * @param[in] callback The callback function to invoke
 397  * @param[in] user_data The user data to be passed to the callback function
 398  * @return @c 0 on success,
 399  *         otherwise a negative error value
 400  * @retval #STT_ERROR_NONE Success
 401  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 402  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 403  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 404  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 405  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 406  * @pre The state should be #STT_STATE_CREATED.
 407  * @post This function invokes stt_supported_engine_cb() repeatedly for getting engine information.
 408  * @see stt_supported_engine_cb()
 409 */
 410 int stt_foreach_supported_engines(stt_h stt, stt_supported_engine_cb callback, void* user_data);
 411
 412
 413 /**
 414  * @brief Gets the current engine ID.
 415  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 416  * @privlevel public
 417  * @privilege %http://tizen.org/privilege/recorder
 418  * @remarks If the function is success, @a engine_id must be released using free().
 419  * @param[in] stt The STT handle
 420  * @param[out] engine_id Engine ID
 421  * @return @c 0 on success,
 422  *         otherwise a negative error value
 423  * @retval #STT_ERROR_NONE Success
 424  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 425  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 426  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 427  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 428  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 429  * @pre The state should be #STT_STATE_CREATED.
 430  * @see stt_set_engine()
 431 */
 432 int stt_get_engine(stt_h stt, char** engine_id);
 433
 434
 435 /**
 436  * @brief Sets the engine ID.
 437  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 438  * @privlevel public
 439  * @privilege %http://tizen.org/privilege/recorder
 440  * @privilege %http://tizen.org/privilege/appmanager.launch
 441  * @remarks A privilege (%http://tizen.org/privilege/appmanager.launch) is necessary since 3.0.
 442  * @param[in] stt The STT handle
 443  * @param[in] engine_id Engine ID
 444  * @return @c 0 on success,
 445  *         otherwise a negative error value
 446  * @retval #STT_ERROR_NONE Success
 447  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 448  * @retval #STT_ERROR_INVALID_STATE STT Not initialized
 449  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 450  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 451  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 452  * @pre The state should be #STT_STATE_CREATED.
 453  * @see stt_get_engine()
 454 */
 455 int stt_set_engine(stt_h stt, const char* engine_id);
 456
 457
 458 /**
 459  * @brief Sets the app credential.
 460  * @details Using this API, the application can set a credential.
 461  *          The credential is a key to verify the authorization about using the engine.
 462  *          If the application sets the credential, it will be able to use functions of the engine entirely.
 463  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 464  * @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.
 465  *          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.
 466  * @param[in] stt The STT handle
 467  * @param[in] credential The app credential
 468  * @return @c 0 on success,
 469  *         otherwise a negative error value
 470  * @retval #STT_ERROR_NONE Success
 471  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 472  * @retval #STT_ERROR_INVALID_STATE Invalid state
 473  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 474  * @pre The state should be #STT_STATE_CREATED or #STT_STATE_READY.
 475  * @see stt_start()
 476 */
 477 int stt_set_credential(stt_h stt, const char* credential);
 478
 479
 480 /**
 481  * @brief Sets the private data to stt engine.
 482  * @details The private data is the setting parameter for applying keys provided by the engine.
 483  *          Using this API, the application can set the private data and use the corresponding key of the engine.
 484  *          For example, if the engine provides 'partial recognition' as a recognition type, the application can set the private data as the following.
 485  *          int ret = stt_set_private_data(stt_h, "recognition_type", "PARTIAL");
 486  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 487  * @remarks If the engine is replaced with the other engine, the key may be ignored.
 488  * @param[in] stt The STT handle
 489  * @param[in] key The field name of private data
 490  * @param[in] data The data for set
 491  * @return @c 0 on success,
 492  *         otherwise a negative error value
 493  * @retval #STT_ERROR_NONE Successful
 494  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 495  * @retval #STT_ERROR_INVALID_STATE Invalid state
 496  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 497  * @retval #STT_ERROR_TIMED_OUT No answer from the STT service
 498  * @pre The state should be #STT_STATE_READY.
 499  * @see stt_get_private_data()
 500 */
 501 int stt_set_private_data(stt_h stt, const char* key, const char* data);
 502
 503
 504 /**
 505  * @brief Gets the private data from stt engine.
 506  * @details The private data is the information provided by the engine.
 507  *          Using this API, the application can get the private data which corresponds to the key from the engine.
 508  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 509  * @remarks If the engine is replaced with the other engine, the key may be ignored.
 510  * @remarks The @a data must be released using free() when it is no longer required.
 511  * @param[in] stt The STT handle
 512  * @param[in] key The field name of private data
 513  * @param[out] data The data field of private data
 514  * @return @c 0 on success,
 515  *         otherwise a negative error value
 516  * @retval #STT_ERROR_NONE Successful
 517  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 518  * @retval #STT_ERROR_INVALID_STATE Invalid state
 519  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 520  * @retval #STT_ERROR_TIMED_OUT No answer from the STT service
 521  * @pre The state should be #STT_STATE_READY.
 522  * @see stt_set_private_data()
 523 */
 524 int stt_get_private_data(stt_h stt, const char* key, char** data);
 525
 526
 527 /**
 528  * @brief Connects the STT service asynchronously.
 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_CREATED.
 541  * @post If this function is successful, the STT state will be #STT_STATE_READY.
 542  *       If this function is failed, the error callback is called. (e.g. #STT_ERROR_ENGINE_NOT_FOUND)
 543  * @see stt_unprepare()
 544 */
 545 int stt_prepare(stt_h stt);
 546
 547
 548 /**
 549  * @brief Disconnects the STT service.
 550  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 551  * @privlevel public
 552  * @privilege %http://tizen.org/privilege/recorder
 553  * @param[in] stt The STT handle
 554  * @return @c 0 on success,
 555  *         otherwise a negative error value
 556  * @retval #STT_ERROR_NONE Successful
 557  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 558  * @retval #STT_ERROR_INVALID_STATE Invalid state
 559  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 560  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 561  * @pre The state should be #STT_STATE_READY.
 562  * @post If this function is called, the STT state will be #STT_STATE_CREATED.
 563  * @see stt_prepare()
 564 */
 565 int stt_unprepare(stt_h stt);
 566
 567
 568 /**
 569  * @brief Retrieves all supported languages of current engine using callback function.
 570  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 571  * @privlevel public
 572  * @privilege %http://tizen.org/privilege/recorder
 573  * @param[in] stt The STT handle
 574  * @param[in] callback The callback function to invoke
 575  * @param[in] user_data The user data to be passed to the callback function
 576  * @return @c 0 on success,
 577  *         otherwise a negative error value
 578  * @retval #STT_ERROR_NONE Successful
 579  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 580  * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
 581  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 582  * @retval #STT_ERROR_ENGINE_NOT_FOUND No available engine
 583  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 584  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 585  * @post This function invokes stt_supported_language_cb() repeatedly for getting languages.
 586  * @see stt_supported_language_cb()
 587  * @see stt_get_default_language()
 588 */
 589 int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callback, void* user_data);
 590
 591
 592 /**
 593  * @brief Gets the default language set by the user.
 594  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 595  * @privlevel public
 596  * @privilege %http://tizen.org/privilege/recorder
 597  * @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.
 598  *          For example, "ko_KR" for Korean, "en_US" for American English.
 599  *          If the function succeeds, @a language must be released using free() when it is no longer required.
 600  * @param[in] stt The STT handle
 601  * @param[out] language The language
 602  * @return @c 0 on success,
 603  *         otherwise a negative error value
 604  * @retval #STT_ERROR_NONE Successful
 605  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 606  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 607  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 608  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 609  * @see stt_foreach_supported_languages()
 610 */
 611 int stt_get_default_language(stt_h stt, char** language);
 612
 613
 614 /**
 615  * @brief Gets the current STT state.
 616  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 617  * @privlevel public
 618  * @privilege %http://tizen.org/privilege/recorder
 619  * @param[in] stt The STT handle
 620  * @param[out] state The current STT state
 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_PERMISSION_DENIED Permission denied
 627  * @see stt_start()
 628  * @see stt_stop()
 629  * @see stt_cancel()
 630  * @see stt_state_changed_cb()
 631 */
 632 int stt_get_state(stt_h stt, stt_state_e* state);
 633
 634
 635 /**
 636  * @brief Gets the current error message.
 637  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 638  * @remarks This function should be called during an stt error callback. If not, the error as operation failure will be returned.
 639  *          If the function succeeds, @a err_msg must be released using free() when it is no longer required.
 640  * @param[in] stt The STT handle
 641  * @param[out] err_msg The current error message
 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_NOT_SUPPORTED STT NOT supported
 647  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 648  * @see stt_set_error_cb()
 649  * @see stt_unset_error_cb()
 650 */
 651 int stt_get_error_message(stt_h stt, char** err_msg);
 652
 653
 654 /**
 655  * @brief Checks whether the recognition type is supported.
 656  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 657  * @privlevel public
 658  * @privilege %http://tizen.org/privilege/recorder
 659  * @param[in] stt The STT handle
 660  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
 661  * @param[out] support The result status @c true = supported,
 662  *                     @c false = not supported
 663  * @return @c 0 on success,
 664  *         otherwise a negative error value
 665  * @retval #STT_ERROR_NONE Successful
 666  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 667  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 668  * @retval #STT_ERROR_INVALID_STATE Invalid state
 669  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 670  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 671  * @pre The state should be #STT_STATE_READY.
 672 */
 673 int stt_is_recognition_type_supported(stt_h stt, const char* type, bool* support);
 674
 675
 676 /**
 677  * @brief Sets the silence detection.
 678  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 679  * @privlevel public
 680  * @privilege %http://tizen.org/privilege/recorder
 681  * @param[in] stt The STT handle
 682  * @param[in] type The option type
 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_NOT_SUPPORTED_FEATURE Not supported feature of current engine
 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_silence_detection(stt_h stt, stt_option_silence_detection_e type);
 694
 695
 696 /**
 697  * @brief Sets 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  * @remarks Sound file type should be wav type.
 702  * @param[in] stt The STT handle
 703  * @param[in] filename The sound file path
 704  * @return @c 0 on success,
 705  *         otherwise a negative error value
 706  * @retval #STT_ERROR_NONE Successful
 707  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 708  * @retval #STT_ERROR_INVALID_STATE Invalid state
 709  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 710  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 711  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 712  * @pre The state should be #STT_STATE_READY.
 713 */
 714 int stt_set_start_sound(stt_h stt, const char* filename);
 715
 716
 717 /**
 718  * @brief Unsets the sound to start recording.
 719  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 720  * @privlevel public
 721  * @privilege %http://tizen.org/privilege/recorder
 722  * @param[in] stt The STT handle
 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_unset_start_sound(stt_h stt);
 734
 735
 736 /**
 737  * @brief Sets 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  * @remarks Sound file type should be wav type.
 742  * @param[in] stt The STT handle
 743  * @param[in] filename The sound file path
 744  * @return @c 0 on success,
 745  *         otherwise a negative error value
 746  * @retval #STT_ERROR_NONE Successful
 747  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 748  * @retval #STT_ERROR_INVALID_STATE Invalid state
 749  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 750  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 751  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 752  * @pre The state should be #STT_STATE_READY.
 753 */
 754 int stt_set_stop_sound(stt_h stt, const char* filename);
 755
 756
 757 /**
 758  * @brief Unsets the sound to stop recording.
 759  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 760  * @privlevel public
 761  * @privilege %http://tizen.org/privilege/recorder
 762  * @param[in] stt The STT handle
 763  * @return @c 0 on success,
 764  *         otherwise a negative error value
 765  * @retval #STT_ERROR_NONE Successful
 766  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 767  * @retval #STT_ERROR_INVALID_STATE Invalid state
 768  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 769  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 770  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 771  * @pre The state should be #STT_STATE_READY.
 772 */
 773 int stt_unset_stop_sound(stt_h stt);
 774
 775
 776 /**
 777  * @brief Starts recording and recognition asynchronously.
 778  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 779  * @privlevel public
 780  * @privilege %http://tizen.org/privilege/recorder
 781  * @remarks This function starts recording in the STT service and sending recording data to engine.
 782  *          This work continues until stt_stop(), stt_cancel() or silence detected by engine.
 783  * @param[in] stt The STT handle
 784  * @param[in] language The language selected from stt_foreach_supported_languages()
 785  * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_FREE_PARTIAL)
 786  * @return @c 0 on success,
 787  *         otherwise a negative error value
 788  * @retval #STT_ERROR_NONE Successful
 789  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 790  * @retval #STT_ERROR_INVALID_STATE Invalid state
 791  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 792  * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
 793  * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
 794  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 795  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 796  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 797  * @pre The state should be #STT_STATE_READY.
 798  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 799  *       If this function succeeds, the STT state will be #STT_STATE_RECORDING.
 800  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_RECORDING.
 801  * @see stt_stop()
 802  * @see stt_cancel()
 803  * @see stt_state_changed_cb()
 804 */
 805 int stt_start(stt_h stt, const char* language, const char* type);
 806
 807
 808 /**
 809  * @brief Finishes the recording and starts recognition processing in engine asynchronously.
 810  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 811  * @privlevel public
 812  * @privilege %http://tizen.org/privilege/recorder
 813  * @param[in] stt The STT handle
 814  * @return @c 0 on success,
 815  *         otherwise a negative error value
 816  * @retval #STT_ERROR_NONE Successful
 817  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 818  * @retval #STT_ERROR_INVALID_STATE Invalid state
 819  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 820  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 821  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 822  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
 823  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 824  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
 825  * @pre The state should be #STT_STATE_RECORDING.
 826  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 827  *       If this function succeeds, the STT state will be #STT_STATE_PROCESSING.
 828  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_PROCESSING.
 829  *       After processing of engine, stt_result_cb() is called.
 830  * @see stt_start()
 831  * @see stt_cancel()
 832  * @see stt_state_changed_cb()
 833 */
 834 int stt_stop(stt_h stt);
 835
 836
 837 /**
 838  * @brief Cancels processing recognition and recording asynchronously.
 839  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 840  * @privlevel public
 841  * @privilege %http://tizen.org/privilege/recorder
 842  * @remarks This function cancels recording and engine cancels recognition processing.
 843  *          After successful cancel, stt_state_changed_cb() is called otherwise if error is occurred, stt_error_cb() is called.
 844  * @param[in] stt The STT handle
 845  * @return @c 0 on success,
 846  *         otherwise a negative error value
 847  * @retval #STT_ERROR_NONE Successful
 848  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 849  * @retval #STT_ERROR_INVALID_STATE Invalid state
 850  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 851  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 852  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 853  * @retval #STT_ERROR_IN_PROGRESS_TO_READY Progress to ready is not finished
 854  * @retval #STT_ERROR_IN_PROGRESS_TO_RECORDING Progress to recording is not finished
 855  * @retval #STT_ERROR_IN_PROGRESS_TO_PROCESSING Progress to processing is not finished
 856  * @pre The state should be #STT_STATE_RECORDING or #STT_STATE_PROCESSING.
 857  * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb().
 858  *       If this function succeeds, the STT state will be #STT_STATE_READY.
 859  *       If you call this function again before state changes, you will receive #STT_ERROR_IN_PROGRESS_TO_READY.
 860  * @see stt_start()
 861  * @see stt_stop()
 862  * @see stt_state_changed_cb()
 863 */
 864 int stt_cancel(stt_h stt);
 865
 866
 867 /**
 868  * @brief Gets the microphone volume during recording.
 869  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 870  * @privlevel public
 871  * @privilege %http://tizen.org/privilege/recorder
 872  * @param[in] stt The STT handle
 873  * @param[out] volume Recording volume
 874  * @return @c 0 on success,
 875  *         otherwise a negative error value
 876  * @retval #STT_ERROR_NONE Successful
 877  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 878  * @retval #STT_ERROR_INVALID_STATE Invalid state
 879  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 880  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 881  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 882  * @pre The state should be #STT_STATE_RECORDING.
 883  * @see stt_start()
 884 */
 885 int stt_get_recording_volume(stt_h stt, float* volume);
 886
 887
 888 /**
 889  * @brief Retrieves the time stamp of the current recognition result using the callback function.
 890  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 891  * @privlevel public
 892  * @privilege %http://tizen.org/privilege/recorder
 893  * @remarks This function should be called in stt_recognition_result_cb().
 894  *          After stt_recognition_result_cb(), result data is NOT valid.
 895  * @param[in] stt The STT handle
 896  * @param[in] callback The callback function to invoke
 897  * @param[in] user_data The user data to be passed to the callback function
 898  * @return @c 0 on success,
 899  *         otherwise a negative error value
 900  * @retval #STT_ERROR_NONE Successful
 901  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 902  * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 903  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 904  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 905  * @pre This function should be called in stt_recognition_result_cb().
 906  * @post This function invokes stt_result_time_cb() repeatedly for getting time information.
 907  * @see stt_result_time_cb()
 908  * @see stt_recognition_result_cb()
 909 */
 910 int stt_foreach_detailed_result(stt_h stt, stt_result_time_cb callback, void* user_data);
 911
 912
 913 /**
 914  * @brief Sets a callback function to get the recognition result.
 915  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 916  * @privlevel public
 917  * @privilege %http://tizen.org/privilege/recorder
 918  * @param[in] stt The STT handle
 919  * @param[in] callback The callback function to register
 920  * @param[in] user_data The user data to be passed to the callback function
 921  * @return @c 0 on success,
 922  *         otherwise a negative error value
 923  * @retval #STT_ERROR_NONE Successful
 924  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 925  * @retval #STT_ERROR_INVALID_STATE Invalid state
 926  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 927  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 928  * @pre The state should be #STT_STATE_CREATED.
 929  * @see stt_recognition_result_cb()
 930  * @see stt_unset_recognition_result_cb()
 931 */
 932 int stt_set_recognition_result_cb(stt_h stt, stt_recognition_result_cb callback, void* user_data);
 933
 934
 935 /**
 936  * @brief Unsets the callback function.
 937  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 938  * @privlevel public
 939  * @privilege %http://tizen.org/privilege/recorder
 940  * @param[in] stt The STT handle
 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_set_recognition_result_cb()
 950 */
 951 int stt_unset_recognition_result_cb(stt_h stt);
 952
 953
 954 /**
 955  * @brief Sets a callback function to be called when STT state changes.
 956  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 957  * @privlevel public
 958  * @privilege %http://tizen.org/privilege/recorder
 959  * @param[in] stt The STT handle
 960  * @param[in] callback The callback function to register
 961  * @param[in] user_data The user data to be passed to the callback function
 962  * @return @c 0 on success,
 963  *         otherwise a negative error value
 964  * @retval #STT_ERROR_NONE Successful
 965  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 966  * @retval #STT_ERROR_INVALID_STATE Invalid state
 967  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
 968  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
 969  * @pre The state should be #STT_STATE_CREATED.
 970  * @see stt_state_changed_cb()
 971  * @see stt_unset_state_changed_cb()
 972 */
 973 int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* user_data);
 974
 975
 976 /**
 977  * @brief Unsets the callback function.
 978  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 979  * @privlevel public
 980  * @privilege %http://tizen.org/privilege/recorder
 981  * @param[in] stt The STT handle
 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_set_state_changed_cb()
 991 */
 992 int stt_unset_state_changed_cb(stt_h stt);
 993
 994
 995 /**
 996  * @brief Sets a callback function to be called when an error occurred.
 997  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 998  * @privlevel public
 999  * @privilege %http://tizen.org/privilege/recorder
1000  * @param[in] stt The STT handle
1001  * @param[in] callback The callback function to register
1002  * @param[in] user_data The user data to be passed to the callback function
1003  * @return @c 0 on success,
1004  *         otherwise a negative error value
1005  * @retval #STT_ERROR_NONE Successful
1006  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1007  * @retval #STT_ERROR_INVALID_STATE Invalid state
1008  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1009  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1010  * @pre The state should be #STT_STATE_CREATED.
1011  * @see stt_error_cb()
1012  * @see stt_unset_error_cb()
1013 */
1014 int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
1015
1016
1017 /**
1018  * @brief Unsets the callback function.
1019  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1020  * @privlevel public
1021  * @privilege %http://tizen.org/privilege/recorder
1022  * @param[in] stt The STT handle
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_set_error_cb()
1032 */
1033 int stt_unset_error_cb(stt_h stt);
1034
1035
1036 /**
1037  * @brief Sets a callback function to detect the default language change.
1038  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1039  * @privlevel public
1040  * @privilege %http://tizen.org/privilege/recorder
1041  * @param[in] stt The STT handle
1042  * @param[in] callback The callback function to register
1043  * @param[in] user_data The user data to be passed to the callback function
1044  * @return @c 0 on success,
1045  *         otherwise a negative error value
1046  * @retval #STT_ERROR_NONE Successful
1047  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1048  * @retval #STT_ERROR_INVALID_STATE Invalid state
1049  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1050  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1051  * @pre The state should be #STT_STATE_CREATED.
1052  * @see stt_default_language_changed_cb()
1053  * @see stt_unset_default_language_changed_cb()
1054 */
1055 int stt_set_default_language_changed_cb(stt_h stt, stt_default_language_changed_cb callback, void* user_data);
1056
1057
1058 /**
1059  * @brief Unsets the callback function.
1060  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1061  * @privlevel public
1062  * @privilege %http://tizen.org/privilege/recorder
1063  * @param[in] stt The STT handle
1064  * @return @c 0 on success,
1065  *         otherwise a negative error value
1066  * @retval #STT_ERROR_NONE Successful
1067  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1068  * @retval #STT_ERROR_INVALID_STATE Invalid state
1069  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1070  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1071  * @pre The state should be #STT_STATE_CREATED.
1072  * @see stt_set_default_language_changed_cb()
1073 */
1074 int stt_unset_default_language_changed_cb(stt_h stt);
1075
1076
1077 /**
1078  * @brief Sets a callback function to detect the engine change.
1079  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1080  * @param[in] stt The STT handle
1081  * @param[in] callback The callback function to register
1082  * @param[in] user_data The user data to be passed to the callback function
1083  * @return @c 0 on success,
1084  *         otherwise a negative error value
1085  * @retval #STT_ERROR_NONE Successful
1086  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1087  * @retval #STT_ERROR_INVALID_STATE Invalid state
1088  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1089  * @pre The state should be #STT_STATE_CREATED.
1090  * @see stt_engine_changed_cb()
1091  * @see stt_unset_engine_changed_cb()
1092 */
1093 int stt_set_engine_changed_cb(stt_h stt, stt_engine_changed_cb callback, void* user_data);
1094
1095
1096 /**
1097  * @brief Unsets the callback function.
1098  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1099  * @param[in] stt The STT handle
1100  * @return @c 0 on success,
1101  *         otherwise a negative error value
1102  * @retval #STT_ERROR_NONE Successful
1103  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1104  * @retval #STT_ERROR_INVALID_STATE Invalid state
1105  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1106  * @pre The state should be #STT_STATE_CREATED.
1107  * @see stt_set_engine_changed_cb()
1108 */
1109 int stt_unset_engine_changed_cb(stt_h stt);
1110
1111
1112 /**
1113  * @brief Sets a callback function to detect the speech status is changed.
1114  * @since_tizen 5.5
1115  * @privlevel public
1116  * @privilege %http://tizen.org/privilege/recorder
1117  * @param[in] stt The STT handle
1118  * @param[in] callback The callback function to register
1119  * @param[in] user_data The user data to be passed to the callback function
1120  * @return @c 0 on success,
1121  *         otherwise a negative error value
1122  * @retval #STT_ERROR_NONE Successful
1123  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1124  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1125  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1126  * @retval #STT_ERROR_INVALID_STATE Invalid state
1127  * @pre The state should be #STT_STATE_CREATED.
1128  * @see stt_speech_status_cb()
1129  * @see stt_unset_speech_status_cb()
1130 */
1131 int stt_set_speech_status_cb(stt_h stt, stt_speech_status_cb callback, void* user_data);
1132
1133
1134 /**
1135  * @brief Unsets the callback function to detect the speech status is changed.
1136  * @since_tizen 5.5
1137  * @privlevel public
1138  * @privilege %http://tizen.org/privilege/recorder
1139  * @param[in] stt The STT handle
1140  * @return @c 0 on success,
1141  *         otherwise a negative error value
1142  * @retval #STT_ERROR_NONE Successful
1143  * @retval #STT_ERROR_NOT_SUPPORTED STT NOT supported
1144  * @retval #STT_ERROR_PERMISSION_DENIED Permission denied
1145  * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
1146  * @retval #STT_ERROR_INVALID_STATE Invalid state
1147  * @pre The state should be #STT_STATE_CREATED.
1148  * @see stt_set_speech_status_cb()
1149 */
1150 int stt_unset_speech_status_cb(stt_h stt);
1151
1152
1153 #ifdef __cplusplus
1154 }
1155 #endif
1156
1157
1158 /**
1159  * @}
1160  */
1161
1162
1163 #endif /* __STT_H__ */
1164