server/sttp.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 #ifndef __STTP_H__
  15 #define __STTP_H__
  16
  17 #include <errno.h>
  18 #include <stdbool.h>
  19
  20 /**
  21 * @addtogroup STT_ENGINE_MODULE
  22 * @{
  23 */
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30 * @brief Enumerations of error codes.
  31 */
  32 typedef enum {
  33         STTP_ERROR_NONE                 =  0,           /**< Successful */
  34         STTP_ERROR_OUT_OF_MEMORY        = -ENOMEM,      /**< Out of Memory */
  35         STTP_ERROR_IO_ERROR             = -EIO,         /**< I/O error */
  36         STTP_ERROR_INVALID_PARAMETER    = -EINVAL,      /**< Invalid parameter */
  37         STTP_ERROR_OUT_OF_NETWORK       = -ENETDOWN,    /**< Out of network */
  38         STTP_ERROR_INVALID_STATE        = -0x0100031,   /**< Invalid state */
  39         STTP_ERROR_INVALID_LANGUAGE     = -0x0100032,   /**< Invalid language */
  40         STTP_ERROR_OPERATION_FAILED     = -0x0100034,   /**< Operation failed */
  41         STTP_ERROR_NOT_SUPPORTED        = -0x0100035    /**< Not supported function */
  42 }sttp_error_e;
  43
  44 /**
  45 * @brief Enumerations of audio type.
  46 */
  47 typedef enum {
  48         STTP_AUDIO_TYPE_PCM_S16_LE = 0, /**< Signed 16bit audio type, Little endian */
  49         STTP_AUDIO_TYPE_PCM_U8,         /**< Unsigned 8bit audio type */
  50         STTP_AUDIO_TYPE_AMR             /**< AMR audio type */
  51 }sttp_audio_type_e;
  52
  53 /**
  54 * @brief Enumerations of callback event.
  55 */
  56 typedef enum {
  57         STTP_RESULT_EVENT_SUCCESS = 0,  /**< Event when the recognition full result is ready  */
  58         STTP_RESULT_EVENT_NO_RESULT,    /**< Event when the recognition result is not */
  59         STTP_RESULT_EVENT_ERROR         /**< Event when the recognition has failed */
  60 }sttp_result_event_e;
  61
  62 /**
  63 * @brief Recognition type : free form dictation or default type.
  64 */
  65 #define STTP_RECOGNITION_TYPE_FREE                      "stt.recognition.type.FREE"
  66
  67 /**
  68 * @brief Recognition type : web search.
  69 */
  70 #define STTP_RECOGNITION_TYPE_WEB_SEARCH                "stt.recognition.type.WEB_SEARCH"
  71
  72 /**
  73 * @brief Recognition type : all voice commands.
  74 */
  75 #define STTP_RECOGNITION_TYPE_COMMAND                   "stt.recognition.type.COMMAND"
  76
  77 /**
  78 * @brief Recognition type : call of voice commands.
  79 */
  80 #define STTP_RECOGNITION_TYPE_COMMAND_CALL              "stt.recognition.type.COMMAND.CALL"
  81
  82 /**
  83 * @brief Recognition type : music of voice commands.
  84 */
  85 #define STTP_RECOGNITION_TYPE_COMMAND_MUSIC             "stt.recognition.type.COMMAND.MUSIC"
  86
  87 /**
  88 * @brief Recognition type : web search of voice commands.
  89 */
  90 #define STTP_RECOGNITION_TYPE_COMMAND_WEB_SEARCH        "stt.recognition.type.COMMAND.WEB_SEARCH"
  91
  92 /**
  93 * @brief Recognition type : schedule of voice commands.
  94 */
  95 #define STTP_RECOGNITION_TYPE_COMMAND_SCHEDULE          "stt.recognition.type.COMMAND.SCHEDULE"
  96
  97 /**
  98 * @brief Recognition type : search of voice commands.
  99 */
 100 #define STTP_RECOGNITION_TYPE_COMMAND_SEARCH            "stt.recognition.type.COMMAND.SEARCH"
 101
 102 /**
 103 * @brief Recognition type : contact of voice commands.
 104 */
 105 #define STTP_RECOGNITION_TYPE_COMMAND_CONTACT           "stt.recognition.type.COMMAND.CONTACT"
 106
 107 /**
 108 * @brief Recognition type : social of voice commands.
 109 */
 110 #define STTP_RECOGNITION_TYPE_COMMAND_SOCIAL            "stt.recognition.type.COMMAND.SOCIAL"
 111
 112 /**
 113 * @brief Recognition type : message of voice commands.
 114 */
 115 #define STTP_RECOGNITION_TYPE_COMMAND_MESSAGE           "stt.recognition.type.COMMAND.MESSAGE"
 116
 117 /**
 118 * @brief Recognition type : email of voice commands.
 119 */
 120 #define STTP_RECOGNITION_TYPE_COMMAND_EMAIL             "stt.recognition.type.COMMAND.EMAIL"
 121
 122 /**
 123 * @brief Recognition type : memo of voice commands.
 124 */
 125 #define STTP_RECOGNITION_TYPE_COMMAND_MEMO              "stt.recognition.type.COMMAND.MEMO"
 126
 127 /**
 128 * @brief Recognition type : alarm of voice commands.
 129 */
 130 #define STTP_RECOGNITION_TYPE_COMMAND_ALARM             "stt.recognition.type.COMMAND.ALARM"
 131
 132 /**
 133 * @brief Recognition type : application of voice commands.
 134 */
 135 #define STTP_RECOGNITION_TYPE_COMMAND_APPLICATION       "stt.recognition.type.COMMAND.APPLICATION"
 136
 137 /**
 138 * @brief Recognition type : driving mode of voice commands.
 139 */
 140 #define STTP_RECOGNITION_TYPE_COMMAND_DRIVING_MODE      "stt.recognition.type.COMMAND.DRIVING_MODE"
 141
 142 /**
 143 * @brief Recognition type : navigation of voice commands.
 144 */
 145 #define STTP_RECOGNITION_TYPE_COMMAND_NAVIGATION        "stt.recognition.type.COMMAND.NAVIGATION"
 146
 147 /**
 148 * @brief Recognition type : text-to-speech of voice commands.
 149 */
 150 #define STTP_RECOGNITION_TYPE_COMMAND_TTS               "stt.recognition.type.COMMAND.TTS"
 151
 152
 153 /**
 154 * @brief Called to get recognition result.
 155 *
 156 * @param[in] event A result event
 157 * @param[in] type A recognition type
 158 * @param[in] data Result texts
 159 * @param[in] data_count Result text count
 160 * @param[in] msg engine A Message
 161 * @param[in] user_data  The user data passed from the start function
 162 *
 163 * @pre sttpe_stop() will invoke this callback.
 164 *
 165 * @see sttpe_start()
 166 * @see sttpe_stop()
 167 */
 168 typedef void (*sttpe_result_cb)(sttp_result_event_e event, const char* type,
 169                                 const char** data, int data_count, const char* msg, void *user_data);
 170
 171 /**
 172 * @brief Called to get partial recognition result.
 173 *
 174 * @param[in] event A result event
 175 * @param[in] data A result text
 176 * @param[in] user_data  The user data passed from the start function.
 177 *
 178 * @pre sttpe_set_recording_data() will invoke this callback
 179 *
 180 * @see sttpe_set_recording_data()
 181 */
 182 typedef void (*sttpe_partial_result_cb)(sttp_result_event_e event, const char* data, void *user_data);
 183
 184 /**
 185 * @brief Called to detect silence from recording data.
 186 *
 187 * @param[in] user_data  The user data passed from the start function.
 188 *
 189 * @pre sttpe_set_recording_data() will invoke this callback.
 190 *
 191 * @see sttpe_set_recording_data()
 192 */
 193 typedef void (*sttpe_silence_detected_cb)(void *user_data);
 194
 195 /**
 196 * @brief Called to retrieve the supported languages.
 197 *
 198 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
 199 *               followed by ISO 639-1 for the two-letter language code \n
 200 *               For example, "ko_KR" for Korean, "en_US" for American English
 201 * @param[in] user_data The user data passed from the foreach function
 202 *
 203 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 204 *
 205 * @pre sttpe_foreach_supported_languages() will invoke this callback.
 206 *
 207 * @see sttpe_foreach_supported_languages()
 208 */
 209 typedef bool (*sttpe_supported_language_cb)(const char* language, void* user_data);
 210
 211 /**
 212 * @brief Called to retrieve the supported engine settings.
 213 *
 214 * @param[in] key A key
 215 * @param[in] value A value
 216 * @param[in] user_data The user data passed from the foreach function
 217 *
 218 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 219 * @pre sttpe_foreach_engine_settings() will invoke this callback.
 220 *
 221 * @see sttpe_foreach_engine_settings()
 222 */
 223 typedef bool (*sttpe_engine_setting_cb)(const char* key, const char* value, void* user_data);
 224
 225 /**
 226 * @brief Initializes the engine.
 227 *
 228 * @param[in] result_cb A callback function for recognition result
 229 * @param[in] partial_result_cb A callback function for partial recognition result
 230 * @param[in] silence_cb A callback function for silence detection
 231 *
 232 * @return 0 on success, otherwise a negative error value
 233 * @retval #STTP_ERROR_NONE Successful
 234 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 235 * @retval #STTP_ERROR_INVALID_STATE Already initialized
 236 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 237 *
 238 * @see sttpe_deinitialize()
 239 */
 240 typedef int (* sttpe_initialize)(sttpe_result_cb result_cb, sttpe_partial_result_cb partial_result_cb,
 241                                  sttpe_silence_detected_cb silence_cb);
 242
 243 /**
 244 * @brief Deinitializes the engine
 245 *
 246 * @return 0 on success, otherwise a negative error value
 247 * @retval #STTP_ERROR_NONE Successful
 248 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 249 *
 250 * @see sttpe_initialize()
 251 */
 252 typedef int (* sttpe_deinitialize)(void);
 253
 254 /**
 255 * @brief Retrieves all supported languages of the engine.
 256 *
 257 * @param[in] callback a callback function
 258 * @param[in] user_data The user data to be passed to the callback function
 259 *
 260 * @return 0 on success, otherwise a negative error value
 261 * @retval #STTP_ERROR_NONE Successful
 262 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 263 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 264 *
 265 * @post This function invokes sttpe_supported_language_cb() repeatedly for getting supported languages.
 266 *
 267 * @see sttpe_supported_language_cb()
 268 */
 269 typedef int (* sttpe_foreach_supported_languages)(sttpe_supported_language_cb callback, void* user_data);
 270
 271 /**
 272 * @brief Checks whether a language is valid or not.
 273 *
 274 * @param[in] language A language
 275 *
 276 * @return 0 on success, otherwise a negative error value
 277 * @retval #STTP_ERROR_NONE Successful
 278 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 279 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 280 *
 281 * @see sttpe_foreach_supported_languages()
 282 */
 283 typedef bool (* sttpe_is_valid_language)(const char* language);
 284
 285 /**
 286 * @brief Gets whether the engine supports silence detection.
 287 *
 288 * @return 0 on success, otherwise a negative error value
 289 * @retval #STTP_ERROR_NONE Successful
 290 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 291 */
 292 typedef bool (* sttpe_support_silence_detection)(void);
 293
 294 /**
 295 * @brief Gets supporting partial result.
 296 *
 297 * @return 0 on success, otherwise a negative error value
 298 * @retval #STTP_ERROR_NONE Successful
 299 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 300 */
 301 typedef bool (* sttpe_support_partial_result)(void);
 302
 303 /**
 304 * @brief Gets recording format of the engine.
 305 *
 306 * @param[out] types The format used by the recorder.
 307 * @param[out] rate The sample rate used by the recorder.
 308 * @param[out] channels The number of channels used by the recorder.
 309 *
 310 * @return 0 on success, otherwise a negative error value
 311 * @retval #STTP_ERROR_NONE Successful
 312 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 313 */
 314 typedef int (* sttpe_get_recording_format)(sttp_audio_type_e* types, int* rate, int* channels);
 315
 316 /**
 317 * @brief Sets profanity filter option.
 318 *
 319 * @param[in] value A value
 320 *
 321 * @return 0 on success, otherwise a negative error value
 322 * @retval #STTP_ERROR_NONE Successful
 323 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 324 * @retval #STTP_ERROR_NOT_SUPPORTED Not supported
 325 */
 326 typedef int (* sttpe_set_profanity_filter)(bool value);
 327
 328 /**
 329 * @brief Sets punctuation option.
 330 *
 331 * @param[in] value A value
 332 *
 333 * @return 0 on success, otherwise a negative error value
 334 * @retval #STTP_ERROR_NONE Successful
 335 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 336 * @retval #STTP_ERROR_NOT_SUPPORTED Not supported
 337 */
 338 typedef int (* sttpe_set_punctuation_override)(bool value);
 339
 340 /**
 341 * @brief Sets silence detection option.
 342 *
 343 * @param[in] value A value
 344 *
 345 * @return 0 on success, otherwise a negative error value
 346 * @retval #STTP_ERROR_NONE Successful
 347 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 348 * @retval #STTP_ERROR_NOT_SUPPORTED Not supported
 349 */
 350 typedef int (* sttpe_set_silence_detection)(bool value);
 351
 352 /**
 353 * @brief Start recognition.
 354 *
 355 * @param[in] language A language.
 356 * @param[in] type A recognition type.
 357 * @param[in] user_data The user data to be passed to the callback function.
 358 *
 359 * @return 0 on success, otherwise a negative error value
 360 * @retval #STTP_ERROR_NONE Successful
 361 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 362 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 363 * @retval #STTP_ERROR_INVALID_LANGUAGE Invalid language
 364 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 365 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 366 *
 367 * @pre The engine is not in recognition processing.
 368 *
 369 * @see sttpe_set_recording_data()
 370 * @see sttpe_stop()
 371 * @see sttpe_cancel()
 372 */
 373 typedef int (* sttpe_start)(const char* language, const char* type, void *user_data);
 374
 375 /**
 376 * @brief Sets recording data for speech recognition from recorder.
 377 *
 378 * @remark This function should be returned immediately after recording data copy.
 379 *
 380 * @param[in] data A recording data
 381 * @param[in] length A length of recording data
 382 *
 383 * @return 0 on success, otherwise a negative error value
 384 * @retval #STTP_ERROR_NONE Successful
 385 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 386 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 387 *
 388 * @pre sttpe_start() should succeed.
 389 * @post If the engine supports partial result, it will invoke sttpe_partial_result_cb().
 390 *
 391 * @see sttpe_start()
 392 * @see sttpe_cancel()
 393 * @see sttpe_stop()
 394 * @see sttpe_partial_result_cb()
 395 */
 396 typedef int (* sttpe_set_recording_data)(const void* data, unsigned int length);
 397
 398 /**
 399 * @brief Stops to set recording data.
 400 *
 401 * @return 0 on success, otherwise a negative error value
 402 * @retval #STTP_ERROR_NONE Successful
 403 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 404 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 405 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 406 *
 407 * @pre sttpe_start() should succeed.
 408 * @post After processing of the engine, sttpe_result_cb() is called.
 409 *
 410 * @see sttpe_start()
 411 * @see sttpe_set_recording_data()
 412 * @see sttpe_result_cb()
 413 * @see sttpe_cancel()
 414 */
 415 typedef int (* sttpe_stop)(void);
 416
 417 /**
 418 * @brief Cancels the recognition process.
 419 *
 420 * @return 0 on success, otherwise a negative error value.
 421 * @retval #STTP_ERROR_NONE Successful.
 422 * @retval #STTP_ERROR_INVALID_STATE Invalid state.
 423 * @pre STT engine is in recognition processing.
 424 *
 425 * @see sttpe_start()
 426 * @see sttpe_stop()
 427 */
 428 typedef int (* sttpe_cancel)(void);
 429
 430 /**
 431 * @brief Gets setting information of the engine.
 432 *
 433 * @param[in] callback A callback function.
 434 * @param[in] user_data The user data to be passed to the callback function.
 435 *
 436 * @return 0 on success, otherwise a negative error value
 437 * @retval #STTP_ERROR_NONE Successful
 438 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 439 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 440 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 441 *
 442 * @post This function invokes sttpe_engine_setting_cb() repeatedly for getting engine settings.
 443 *
 444 * @see sttpe_engine_setting_cb()
 445 */
 446 typedef int (* sttpe_foreach_engine_settings)(sttpe_engine_setting_cb callback, void* user_data);
 447
 448 /**
 449 * @brief Set engine specific information.
 450 *
 451 * @param[in] key A key
 452 * @param[in] value A value
 453 *
 454 * @return 0 on success, otherwise a negative error value
 455 * @retval #STTP_ERROR_NONE Successful
 456 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 457 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 458 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 459 *
 460 * @see sttpe_foreach_engine_settings()
 461 */
 462 typedef int (* sttpe_set_engine_setting)(const char* key, const char* value);
 463
 464
 465 /**
 466 * @brief A structure of the engine functions.
 467 */
 468 typedef struct {
 469         int size;                                               /**< Size of structure */
 470         int version;                                            /**< Version */
 471
 472         sttpe_initialize                initialize;             /**< Initialize engine */
 473         sttpe_deinitialize              deinitialize;           /**< Shutdown engine */
 474
 475         /* Get engine information */
 476         sttpe_foreach_supported_languages foreach_langs;        /**< Foreach language list */
 477         sttpe_is_valid_language         is_valid_lang;          /**< Check language */
 478         sttpe_support_silence_detection support_silence;        /**< Get silence detection support */
 479         sttpe_support_partial_result    support_partial_result; /**< Get partial result support */
 480         sttpe_get_recording_format      get_audio_format;       /**< Get audio format */
 481
 482         /* Set engine information */
 483         sttpe_set_profanity_filter      set_profanity_filter;   /**< Set profanity filter */
 484         sttpe_set_punctuation_override  set_punctuation;        /**< Set punctuation override */
 485         sttpe_set_silence_detection     set_silence_detection;  /**< Set silence detection */
 486
 487         /* Control recognition */
 488         sttpe_start                     start;                  /**< Start recognition */
 489         sttpe_set_recording_data        set_recording;          /**< Set recording data */
 490         sttpe_stop                      stop;                   /**< Shutdown function */
 491         sttpe_cancel                    cancel;                 /**< Cancel recognition or cancel thinking */
 492
 493         /* Engine setting */
 494         sttpe_foreach_engine_settings   foreach_engine_settings;/**< Foreach engine specific info */
 495         sttpe_set_engine_setting        set_engine_setting;     /**< Set engine specific info */
 496 } sttpe_funcs_s;
 497
 498 /**
 499 * @brief A structure of the daemon functions.
 500 */
 501 typedef struct {
 502         int size;                                               /**< size */
 503         int version;                                            /**< version */
 504
 505 } sttpd_funcs_s;
 506
 507 /**
 508 * @brief Loads the engine.
 509 *
 510 * @param[in] pdfuncs The daemon functions
 511 * @param[out] pefuncs The engine functions
 512 *
 513 * @return This function returns zero on success, or negative with error code on failure
 514 * @retval #STTP_ERROR_NONE Successful
 515 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 516 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 517 *
 518 * @pre The sttp_get_engine_info() should be successful.
 519 * @post The daemon calls engine functions of sttpe_funcs_s.
 520 *
 521 * @see sttp_get_engine_info()
 522 * @see sttp_unload_engine()
 523 */
 524 int sttp_load_engine(sttpd_funcs_s* pdfuncs, sttpe_funcs_s* pefuncs);
 525
 526 /**
 527 * @brief Unloads this engine by the daemon.
 528 *
 529 * @pre The sttp_load_engine() should be successful.
 530 *
 531 * @see sttp_load_engine()
 532 */
 533 void sttp_unload_engine(void);
 534
 535 /**
 536 * @brief Called to get the engine base information.
 537 *
 538 * @param[in] engine_uuid The engine id
 539 * @param[in] engine_name The engine name
 540 * @param[in] setting_ug_name The setting ug name
 541 * @param[in] use_network @c true to need network @c false not to need network.
 542 * @param[in] user_data The User data passed from sttp_get_engine_info()
 543 *
 544 * @pre sttp_get_engine_info() will invoke this callback.
 545 *
 546 * @see sttp_get_engine_info()
 547 */
 548 typedef void (*sttpe_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* setting_ug_name,
 549                                      bool use_network, void* user_data);
 550
 551 /**
 552 * @brief Gets the engine base information before the engine is loaded by the daemon.
 553 *
 554 * @param[in] callback Callback function
 555 * @param[in] user_data User data to be passed to the callback function
 556 *
 557 * @return This function returns zero on success, or negative with error code on failure
 558 * @retval #STTP_ERROR_NONE Successful
 559 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 560 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 561 *
 562 * @post This function invokes sttpe_engine_info_cb() for getting engine information.
 563 *
 564 * @see sttpe_engine_info_cb()
 565 * @see sttp_load_engine()
 566 */
 567 int sttp_get_engine_info(sttpe_engine_info_cb callback, void* user_data);
 568
 569 #ifdef __cplusplus
 570 }
 571 #endif
 572
 573 /**
 574  * @}@}
 575  */
 576
 577 #endif /* __STTP_H__ */