client/stt.h

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