client/stt.h

   1 /*
   2  * Copyright (c) 2012, 2013 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 #ifndef __STT_H__
  18 #define __STT_H__
  19
  20 #include <errno.h>
  21 #include <stdbool.h>
  22
  23 /**
  24 * @addtogroup CAPI_UIX_STT_MODULE
  25 * @{
  26 */
  27
  28 #ifdef __cplusplus
  29 extern "C"
  30 {
  31 #endif
  32
  33 /**
  34 * @brief Enumerations of error codes.
  35 */
  36 typedef enum {
  37         STT_ERROR_NONE                  = 0,                    /**< Successful */
  38         STT_ERROR_OUT_OF_MEMORY         = -ENOMEM,              /**< Out of Memory */
  39         STT_ERROR_IO_ERROR              = -EIO,                 /**< I/O error */
  40         STT_ERROR_INVALID_PARAMETER     = -EINVAL,              /**< Invalid parameter */
  41         STT_ERROR_TIMED_OUT             = -ETIMEDOUT,           /**< No answer from the daemon */
  42         STT_ERROR_RECORDER_BUSY         = -EBUSY,               /**< Busy recorder */
  43         STT_ERROR_OUT_OF_NETWORK        = -ENETDOWN,            /**< Out of network */
  44         STT_ERROR_INVALID_STATE         = -0x0100000 | 0x31,    /**< Invalid state */
  45         STT_ERROR_INVALID_LANGUAGE      = -0x0100000 | 0x32,    /**< Invalid language */
  46         STT_ERROR_ENGINE_NOT_FOUND      = -0x0100000 | 0x33,    /**< No available engine  */
  47         STT_ERROR_OPERATION_FAILED      = -0x0100000 | 0x34,    /**< Operation failed  */
  48         STT_ERROR_NOT_SUPPORTED_FEATURE = -0x0100000 | 0x35     /**< Not supported feature of current engine */
  49 }stt_error_e;
  50
  51 /**
  52 * @brief Recognition type : free form dictation or default type.
  53 */
  54 #define STT_RECOGNITION_TYPE_FREE               "stt.recognition.type.FREE"
  55
  56 /**
  57 * @brief Recognition type : web search.
  58 */
  59 #define STT_RECOGNITION_TYPE_WEB_SEARCH         "stt.recognition.type.WEB_SEARCH"
  60
  61 /**
  62 * @brief Result message : None message
  63 */
  64 #define STT_RESULT_MESSAGE_NONE                 "stt.result.message.none"
  65
  66 /**
  67 * @brief Result warning message : The speech has started too soon
  68 */
  69 #define STT_RESULT_MESSAGE_WARNING_TOO_SOON     "stt.result.message.warning.too.soon"
  70
  71 /**
  72 * @brief Result warning message : The speech is too short
  73 */
  74 #define STT_RESULT_MESSAGE_WARNING_TOO_SHORT    "stt.result.message.warning.too.short"
  75
  76 /**
  77 * @brief Result warning message : The speech is too long
  78 */
  79 #define STT_RESULT_MESSAGE_WARNING_TOO_LONG     "stt.result.message.warning.too.long"
  80
  81 /**
  82 * @brief Result warning message : The speech is too quiet to listen
  83 */
  84 #define STT_RESULT_MESSAGE_WARNING_TOO_QUIET    "stt.result.message.warning.too.quiet"
  85
  86 /**
  87 * @brief Result warning message : The speech is too loud to listen
  88 */
  89 #define STT_RESULT_MESSAGE_WARNING_TOO_LOUD     "stt.result.message.warning.too.loud"
  90
  91 /**
  92 * @brief Result warning message : The speech is too fast to listen
  93 */
  94 #define STT_RESULT_MESSAGE_WARNING_TOO_FAST     "stt.result.message.warning.too.fast"
  95
  96 /**
  97 * @brief Result error message : Recognition was failed because the speech started too soon
  98 */
  99 #define STT_RESULT_MESSAGE_ERROR_TOO_SOON       "stt.result.message.error.too.soon"
 100
 101 /**
 102 * @brief Result error message : Recognition was failed because the speech started too short
 103 */
 104 #define STT_RESULT_MESSAGE_ERROR_TOO_SHORT      "stt.result.message.error.too.short"
 105
 106 /**
 107 * @brief Result error message : Recognition was failed because the speech started too long
 108 */
 109 #define STT_RESULT_MESSAGE_ERROR_TOO_LONG       "stt.result.message.error.too.long"
 110
 111 /**
 112 * @brief Result error message : Recognition was failed because the speech started too quiet to listen
 113 */
 114 #define STT_RESULT_MESSAGE_ERROR_TOO_QUIET      "stt.result.message.error.too.quiet"
 115
 116 /**
 117 * @brief Result error message : Recognition was failed because the speech started too loud to listen
 118 */
 119 #define STT_RESULT_MESSAGE_ERROR_TOO_LOUD       "stt.result.message.error.too.loud"
 120
 121 /**
 122 * @brief Result error message : Recognition was failed because the speech started too fast to listen
 123 */
 124 #define STT_RESULT_MESSAGE_ERROR_TOO_FAST       "stt.result.message.error.too.fast"
 125
 126
 127 /**
 128 * @brief Enumerations of state.
 129 */
 130 typedef enum {
 131         STT_STATE_CREATED = 0,                  /**< 'CREATED' state */
 132         STT_STATE_READY,                        /**< 'READY' state */
 133         STT_STATE_RECORDING,                    /**< 'RECORDING' state */
 134         STT_STATE_PROCESSING                    /**< 'PROCESSING' state*/
 135 }stt_state_e;
 136
 137 /**
 138 * @brief Enumerations of profanity type.
 139 */
 140 typedef enum {
 141         STT_OPTION_PROFANITY_FALSE = 0,         /**< Profanity type - False */
 142         STT_OPTION_PROFANITY_TRUE = 1,          /**< Profanity type - True */
 143         STT_OPTION_PROFANITY_AUTO = 2           /**< Profanity type - Auto */
 144 }stt_option_profanity_e;
 145
 146 /**
 147 * @brief Enumerations of punctuation type.
 148 */
 149 typedef enum {
 150         STT_OPTION_PUNCTUATION_FALSE = 0,       /**< Punctuation type - False */
 151         STT_OPTION_PUNCTUATION_TRUE = 1,        /**< Punctuation type - True */
 152         STT_OPTION_PUNCTUATION_AUTO = 2         /**< Punctuation type - Auto */
 153 }stt_option_punctuation_e;
 154
 155 /**
 156 * @brief Enumerations of silence detection type.
 157 */
 158 typedef enum {
 159         STT_OPTION_SILENCE_DETECTION_FALSE = 0, /**< Silence detection type - False */
 160         STT_OPTION_SILENCE_DETECTION_TRUE = 1,  /**< Silence detection type - True */
 161         STT_OPTION_SILENCE_DETECTION_AUTO = 2   /**< Silence detection type - Auto */
 162 }stt_option_silence_detection_e;
 163
 164 /**
 165 * @brief A structure of handle for STT
 166 */
 167 typedef struct stt_s *stt_h;
 168
 169 /**
 170 * @brief Called when STT gets the recognition result from engine after the application call stt_stop().
 171 *
 172 * @remark If results of recognition is valid after stt_stop() is called or silence is detected from recording,
 173 *       this function is called.
 174 *
 175 * @param[in] stt The handle for STT
 176 * @param[in] type Recognition type (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_WEB_SEARCH)
 177 * @param[in] data Result texts
 178 * @param[in] data_count Result text count
 179 * @param[in] msg Engine message (e.g. #STT_RESULT_MESSAGE_WARNING_TOO_SOON, #STT_RESULT_MESSAGE_ERROR_TOO_SHORT)
 180 * @param[in] user_data The user data passed from the callback registration function
 181 *
 182 * @pre stt_stop() will invoke this callback if you register it using stt_set_result_cb().
 183 * @post If this function is called, the STT state will be #STT_STATE_READY.
 184 *
 185 * @see stt_stop()
 186 * @see stt_set_result_cb()
 187 * @see stt_unset_result_cb()
 188 */
 189 typedef void (*stt_result_cb)(stt_h stt, const char* type, const char** data, int data_count, const char* msg, void *user_data);
 190
 191 /**
 192 * @brief Called when STT gets recognition the partial result from engine after the application calls stt_start().
 193 *
 194 * @remark If a current engine supports partial result of recognition, this function can be called.
 195 *
 196 * @param[in] stt The handle for STT
 197 * @param[in] data Result data
 198 * @param[in] user_data The user data passed from the callback registration function
 199 *
 200 * @pre stt_start() will invoke this callback if you register it using stt_set_partial_result_cb().
 201 *
 202 * @see stt_start()
 203 * @see stt_set_partial_result_cb()
 204 * @see stt_unset_partial_result_cb()
 205 * @see stt_is_partial_result_supported()
 206 */
 207 typedef void (*stt_partial_result_cb)(stt_h stt, const char* data, void *user_data);
 208
 209 /**
 210 * @brief Called when the state of STT is changed.
 211 *
 212 * @param[in] stt The handle for STT
 213 * @param[in] previous A previous state
 214 * @param[in] current A current state
 215 * @param[in] user_data The user data passed from the callback registration function.
 216 *
 217 * @pre An application registers this callback using stt_set_state_changed_cb() to detect changing state.
 218 *
 219 * @see stt_set_state_changed_cb()
 220 * @see stt_unset_state_changed_cb()
 221 */
 222 typedef void (*stt_state_changed_cb)(stt_h stt, stt_state_e previous, stt_state_e current, void* user_data);
 223
 224 /**
 225 * @brief Called when error occurred.
 226 *
 227 * @param[in] stt The handle for STT
 228 * @param[in] reason The error type (e.g. #STT_ERROR_OUT_OF_NETWORK, #STT_ERROR_IO_ERROR)
 229 * @param[in] user_data The user data passed from the callback registration function
 230 *
 231 * @pre An application registers this callback using stt_set_error_cb() to detect error.
 232 *
 233 * @see stt_set_error_cb()
 234 * @see stt_unset_error_cb()
 235 */
 236 typedef void (*stt_error_cb)(stt_h stt, stt_error_e reason, void *user_data);
 237
 238 /**
 239 * @brief Called to retrieve the supported languages.
 240 *
 241 * @param[in] stt The handle for STT
 242 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
 243 *               followed by ISO 639-1 for the two-letter language code. \n
 244 *               For example, "ko_KR" for Korean, "en_US" for American English.
 245 * @param[in] user_data The user data passed from the foreach function
 246 *
 247 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 248 * @pre stt_foreach_supported_languages() will invoke this callback.
 249 *
 250 * @see stt_foreach_supported_languages()
 251 */
 252 typedef bool(*stt_supported_language_cb)(stt_h stt, const char* language, void* user_data);
 253
 254
 255 /**
 256 * @brief Creates a handle for STT.
 257 *
 258 * @param[out] stt The handle for STT
 259 *
 260 * @return 0 on success, otherwise a negative error value
 261 * @retval #STT_ERROR_NONE Successful
 262 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 263 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 264 *
 265 * @post If this function is called, the STT state will be #STT_STATE_CREATED.
 266 *
 267 * @see stt_destroy()
 268 */
 269 int stt_create(stt_h* stt);
 270
 271 /**
 272 * @brief Destroys the handle.
 273 *
 274 * @param[in] stt The handle for STT
 275 *
 276 * @return 0 on success, otherwise a negative error value
 277 * @retval #STT_ERROR_NONE Successful
 278 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 279 *
 280 * @see stt_create()
 281 */
 282 int stt_destroy(stt_h stt);
 283
 284 /**
 285 * @brief Connects the daemon.
 286 *
 287 * @param[in] stt The handle for STT
 288 *
 289 * @return 0 on success, otherwise a negative error value
 290 * @retval #STT_ERROR_NONE Successful
 291 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 292 * @retval #STT_ERROR_INVALID_STATE Invalid state
 293 *
 294 * @pre The state should be #STT_STATE_CREATED.
 295 * @post If this function is called, the STT state will be #STT_STATE_READY.
 296 *
 297 * @see stt_unprepare()
 298 */
 299 int stt_prepare(stt_h stt);
 300
 301 /**
 302 * @brief Disconnects the daemon.
 303 *
 304 * @param[in] stt The handle for STT
 305 *
 306 * @return 0 on success, otherwise a negative error value
 307 * @retval #STT_ERROR_NONE Successful
 308 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 309 * @retval #STT_ERROR_INVALID_STATE Invalid state
 310 *
 311 * @pre The state should be #STT_STATE_READY.
 312 * @post If this function is called, the STT state will be #STT_STATE_CREATED.
 313 *
 314 * @see stt_prepare()
 315 */
 316 int stt_unprepare(stt_h stt);
 317
 318 /**
 319 * @brief Retrieves all supported languages of current engine using callback function.
 320 *
 321 * @param[in] stt The handle for STT
 322 * @param[in] callback The callback function to invoke
 323 * @param[in] user_data The user data to be passed to the callback function
 324 *
 325 * @return 0 on success, otherwise a negative error value
 326 * @retval #STT_ERROR_NONE Successful
 327 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 328 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 329 * @retval #STT_ERROR_INVALID_STATE Invalid state
 330 *
 331 * @pre The state should be #STT_STATE_READY.
 332 * @post This function invokes stt_supported_language_cb() repeatedly for getting languages.
 333 *
 334 * @see stt_supported_language_cb()
 335 * @see stt_get_default_language()
 336 */
 337 int stt_foreach_supported_languages(stt_h stt, stt_supported_language_cb callback, void* user_data);
 338
 339 /**
 340 * @brief Gets the default language set by user.
 341 *
 342 * @remark If the function succeeds, @a language must be released with free() by you when you no longer need it.
 343 *
 344 * @param[in] stt The handle for STT
 345 * @param[out] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
 346 *                       followed by ISO 639-1 for the two-letter language code. \n
 347 *                       For example, "ko_KR" for Korean, "en_US" for American English.
 348 *
 349 * @return 0 on success, otherwise a negative error value
 350 * @retval #STT_ERROR_NONE Successful
 351 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 352 * @retval #STT_ERROR_OUT_OF_MEMORY Out of memory
 353 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 354 * @retval #STT_ERROR_INVALID_STATE Invalid state
 355 *
 356 * @pre The state should be #STT_STATE_READY.
 357 *
 358 * @see stt_foreach_supported_languages()
 359 */
 360 int stt_get_default_language(stt_h stt, char** language);
 361
 362 /**
 363 * @brief Gets the current state of STT.
 364 *
 365 * @param[in] stt The handle for STT
 366 * @param[out] state The current state of STT
 367 *
 368 * @return 0 on success, otherwise a negative error value
 369 * @retval #STT_ERROR_NONE Successful
 370 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 371 *
 372 * @see stt_start()
 373 * @see stt_stop()
 374 * @see stt_cancel()
 375 * @see stt_state_changed_cb()
 376 */
 377 int stt_get_state(stt_h stt, stt_state_e* state);
 378
 379 /**
 380 * @brief Checks whether the partial results can be returned while a recognition is in process.
 381 *
 382 * @param[in] stt The handle for STT
 383 * @param[out] partial_result The partial result status : (@c true = supported, @c false = not supported)
 384 *
 385 * @return 0 on success, otherwise a negative error value
 386 * @retval #STT_ERROR_NONE Successful
 387 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 388 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 389 * @retval #STT_ERROR_INVALID_STATE Invalid state
 390 *
 391 * @pre The state should be #STT_STATE_READY.
 392 *
 393 * @see stt_partial_result_cb()
 394 */
 395 int stt_is_partial_result_supported(stt_h stt, bool* partial_result);
 396
 397 /**
 398 * @brief Sets profanity filter.
 399 *
 400 * @param[in] stt The handle for STT
 401 * @param[in] type The option type
 402 *
 403 * @return 0 on success, otherwise a negative error value
 404 * @retval #STT_ERROR_NONE Successful
 405 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 406 * @retval #STT_ERROR_INVALID_STATE Invalid state
 407 * @retval #STT_ERROR_NOT_SUPPORTED_FEATURE Not supported feature of current engine
 408 *
 409 * @pre The state should be #STT_STATE_READY.
 410 */
 411 int stt_set_profanity_filter(stt_h stt, stt_option_profanity_e type);
 412
 413 /**
 414 * @brief Sets punctuation override.
 415 *
 416 * @param[in] stt The handle for STT
 417 * @param[in] type The option type
 418 *
 419 * @return 0 on success, otherwise a negative error value
 420 * @retval #STT_ERROR_NONE Successful
 421 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 422 * @retval #STT_ERROR_INVALID_STATE Invalid state
 423 * @retval #STT_ERROR_NOT_SUPPORTED_FEATURE Not supported feature of current engine
 424 *
 425 * @pre The state should be #STT_STATE_READY.
 426 */
 427 int stt_set_punctuation_override(stt_h stt, stt_option_punctuation_e type);
 428
 429 /**
 430 * @brief Sets silence detection.
 431 *
 432 * @param[in] stt The handle for STT
 433 * @param[in] type The option type
 434 *
 435 * @return 0 on success, otherwise a negative error value
 436 * @retval #STT_ERROR_NONE Successful
 437 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 438 * @retval #STT_ERROR_INVALID_STATE Invalid state
 439 * @retval #STT_ERROR_NOT_SUPPORTED_FEATURE Not supported feature of current engine
 440 *
 441 * @pre The state should be #STT_STATE_READY.
 442 */
 443 int stt_set_silence_detection(stt_h stt, stt_option_silence_detection_e type);
 444
 445 /**
 446 * @brief Starts recording and recognition.
 447 *
 448 * @remark This function starts recording in the daemon and sending recording data to engine. \n
 449 * This work continues until stt_stop(), stt_cancel() or silence detected.
 450 *
 451 * @param[in] stt The handle for STT
 452 * @param[in] language The language selected from stt_foreach_supported_languages()
 453 * @param[in] type The type for recognition (e.g. #STT_RECOGNITION_TYPE_FREE, #STT_RECOGNITION_TYPE_WEB_SEARCH)
 454 *
 455 * @return 0 on success, otherwise a negative error value
 456 * @retval #STT_ERROR_NONE Successful
 457 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter.
 458 * @retval #STT_ERROR_INVALID_STATE Invalid state
 459 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 460 * @retval #STT_ERROR_RECORDER_BUSY Recorder busy
 461 * @retval #STT_ERROR_INVALID_LANGUAGE Invalid language
 462 *
 463 * @pre The state should be #STT_STATE_READY.
 464 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
 465 * If this function succeeds, the STT state will be #STT_STATE_RECORDING.
 466 *
 467 * @see stt_stop()
 468 * @see stt_cancel()
 469 * @see stt_state_changed_cb()
 470 * @see stt_error_cb()
 471 */
 472 int stt_start(stt_h stt, const char* language, const char* type);
 473
 474 /**
 475 * @brief Finishes recording and starts recognition processing in engine.
 476 *
 477 * @param[in] stt The handle for STT
 478 *
 479 * @return 0 on success, otherwise a negative error value
 480 * @retval #STT_ERROR_NONE Successful
 481 * @retval #STT_ERROR_OUT_OF_MEMORY Not enough memory
 482 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 483 * @retval #STT_ERROR_INVALID_STATE Invalid state
 484 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 485 *
 486 * @pre The state should be #STT_STATE_RECORDING.
 487 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
 488 * If this function succeeds, the STT state will be #STT_STATE_PROCESSING. \n
 489 * After processing of engine, stt_result_cb() is called.
 490 *
 491 * @see stt_start()
 492 * @see stt_cancel()
 493 * @see stt_state_changed_cb()
 494 * @see stt_error_cb()
 495 */
 496 int stt_stop(stt_h stt);
 497
 498 /**
 499 * @brief Cancels processing recognition and recording.
 500 *
 501 * @remark This function cancels recording and engine cancels recognition processing. \n
 502 * After successful cancel, stt_state_changed_cb() is called otherwise if error is occurred, stt_error_cb() is called.
 503 *
 504 * @param[in] stt The handle for STT
 505 *
 506 * @return 0 on success, otherwise a negative error value
 507 * @retval #STT_ERROR_NONE Successful
 508 * @retval #STT_ERROR_OUT_OF_MEMORY Not enough memory
 509 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 510 * @retval #STT_ERROR_INVALID_STATE Invalid state
 511 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 512 *
 513 * @pre The state should be #STT_STATE_RECORDING or #STT_STATE_PROCESSING.
 514 * @post It will invoke stt_state_changed_cb(), if you register a callback with stt_state_changed_cb(). \n
 515 * If this function succeeds, the STT state will be #STT_STATE_READY.
 516 *
 517 * @see stt_start()
 518 * @see stt_stop()
 519 * @see stt_state_changed_cb()
 520 * @see stt_error_cb()
 521 */
 522 int stt_cancel(stt_h stt);
 523
 524 /**
 525 * @brief Gets the microphone volume during recording.
 526 *
 527 * @param[in] stt The handle for STT
 528 * @param[out] volume Recording volume
 529 *
 530 * @return 0 on success, otherwise a negative error value
 531 * @retval #STT_ERROR_NONE Successful
 532 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 533 * @retval #STT_ERROR_INVALID_STATE Invalid state
 534 * @retval #STT_ERROR_OPERATION_FAILED Operation failure
 535 *
 536 * @pre The state should be #STT_STATE_RECORDING.
 537 *
 538 * @see stt_start()
 539 */
 540 int stt_get_recording_volume(stt_h stt, float* volume);
 541
 542 /**
 543 * @brief Registers a callback function for getting recognition result.
 544 *
 545 * @param[in] stt The handle for STT
 546 * @param[in] callback The callback function to register
 547 * @param[in] user_data The user data to be passed to the callback function
 548 *
 549 * @return 0 on success, otherwise a negative error value
 550 * @retval #STT_ERROR_NONE Successful
 551 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 552 * @retval #STT_ERROR_INVALID_STATE Invalid state
 553 *
 554 * @pre The state should be #STT_STATE_CREATED.
 555 *
 556 * @see stt_result_cb()
 557 * @see stt_unset_result_cb()
 558 */
 559 int stt_set_result_cb(stt_h stt, stt_result_cb callback, void* user_data);
 560
 561 /**
 562 * @brief Unregisters the callback function.
 563 *
 564 * @param[in] stt The handle for STT
 565 *
 566 * @return 0 on success, otherwise a negative error value
 567 * @retval #STT_ERROR_NONE Successful
 568 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 569 * @retval #STT_ERROR_INVALID_STATE Invalid state
 570 *
 571 * @pre The state should be #STT_STATE_CREATED.
 572 *
 573 * @see stt_set_result_cb()
 574 */
 575 int stt_unset_result_cb(stt_h stt);
 576
 577 /**
 578 * @brief Registers a callback function for getting partial result of recognition.
 579 *
 580 * @param[in] stt The handle for STT
 581 * @param[in] callback The callback function to register
 582 * @param[in] user_data The user data to be passed to the callback function
 583 *
 584 * @return 0 on success, otherwise a negative error value
 585 * @retval #STT_ERROR_NONE Successful
 586 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 587 * @retval #STT_ERROR_INVALID_STATE Invalid state
 588 *
 589 * @pre The state should be #STT_STATE_CREATED.
 590 *
 591 * @see stt_partial_result_cb()
 592 * @see stt_unset_partial_result_cb()
 593 */
 594 int stt_set_partial_result_cb(stt_h stt, stt_partial_result_cb callback, void* user_data);
 595
 596 /**
 597 * @brief Unregisters the callback function.
 598 *
 599 * @param[in] stt The handle for STT
 600 *
 601 * @return 0 on success, otherwise a negative error value
 602 * @retval #STT_ERROR_NONE Successful
 603 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 604 * @retval #STT_ERROR_INVALID_STATE Invalid state
 605 *
 606 * @pre The state should be #STT_STATE_CREATED.
 607 *
 608 * @see stt_set_partial_result_cb()
 609 */
 610 int stt_unset_partial_result_cb(stt_h stt);
 611
 612 /**
 613 * @brief Registers a callback function to be called when STT state changes.
 614 *
 615 * @param[in] stt The handle for STT
 616 * @param[in] callback The callback function to register
 617 * @param[in] user_data The user data to be passed to the callback function
 618 *
 619 * @return 0 on success, otherwise a negative error value
 620 * @retval #STT_ERROR_NONE Successful
 621 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 622 * @retval #STT_ERROR_INVALID_STATE Invalid state
 623 *
 624 * @pre The state should be #STT_STATE_CREATED.
 625 *
 626 * @see stt_state_changed_cb()
 627 * @see stt_unset_state_changed_cb()
 628 */
 629 int stt_set_state_changed_cb(stt_h stt, stt_state_changed_cb callback, void* user_data);
 630
 631 /**
 632 * @brief Unregisters the callback function.
 633 *
 634 * @param[in] stt The handle for STT
 635 *
 636 * @return 0 on success, otherwise a negative error value
 637 * @retval #STT_ERROR_NONE Successful
 638 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 639 * @retval #STT_ERROR_INVALID_STATE Invalid state
 640 *
 641 * @pre The state should be #STT_STATE_CREATED.
 642 *
 643 * @see stt_set_state_changed_cb()
 644 */
 645 int stt_unset_state_changed_cb(stt_h stt);
 646
 647 /**
 648 * @brief Registers a callback function to be called when an error occurred.
 649 *
 650 * @param[in] stt The handle for STT
 651 * @param[in] callback The callback function to register
 652 * @param[in] user_data The user data to be passed to the callback function
 653 *
 654 * @return 0 on success, otherwise a negative error value
 655 * @retval #STT_ERROR_NONE Successful
 656 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 657 * @retval #STT_ERROR_INVALID_STATE Invalid state
 658 *
 659 * @pre The state should be #STT_STATE_CREATED.
 660 *
 661 * @see stt_error_cb()
 662 * @see stt_unset_error_cb()
 663 */
 664 int stt_set_error_cb(stt_h stt, stt_error_cb callback, void* user_data);
 665
 666 /**
 667 * @brief Unregisters the callback function.
 668 *
 669 * @param[in] stt The handle for STT
 670 *
 671 * @return 0 on success, otherwise a negative error value
 672 * @retval #STT_ERROR_NONE Successful
 673 * @retval #STT_ERROR_INVALID_PARAMETER Invalid parameter
 674 * @retval #STT_ERROR_INVALID_STATE Invalid state
 675 *
 676 * @pre The state should be #STT_STATE_CREATED.
 677 *
 678 * @see stt_set_error_cb()
 679 */
 680 int stt_unset_error_cb(stt_h stt);
 681
 682
 683 #ifdef __cplusplus
 684 }
 685 #endif
 686
 687 /**
 688  * @}@}
 689  */
 690
 691 #endif /* __STT_H__ */