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