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