server/sttp.h

   1 /*
   2 * Copyright (c) 2012, 2013 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_FEATURE= -0x0100035    /**< Not supported feature */
  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 * @brief Result message : None message
 154 */
 155 #define STTP_RESULT_MESSAGE_NONE                "stt.result.message.none"
 156
 157 /**
 158 * @brief Result warning message : The speech has started too soon
 159 */
 160 #define STTP_RESULT_MESSAGE_WARNING_TOO_SOON    "stt.result.message.warning.too.soon"
 161
 162 /**
 163 * @brief Result warning message : The speech is too short
 164 */
 165 #define STTP_RESULT_MESSAGE_WARNING_TOO_SHORT   "stt.result.message.warning.too.short"
 166
 167 /**
 168 * @brief Result warning message : The speech is too long
 169 */
 170 #define STTP_RESULT_MESSAGE_WARNING_TOO_LONG    "stt.result.message.warning.too.long"
 171
 172 /**
 173 * @brief Result warning message : The speech is too quiet to listen
 174 */
 175 #define STTP_RESULT_MESSAGE_WARNING_TOO_QUIET   "stt.result.message.warning.too.quiet"
 176
 177 /**
 178 * @brief Result warning message : The speech is too loud to listen
 179 */
 180 #define STTP_RESULT_MESSAGE_WARNING_TOO_LOUD    "stt.result.message.warning.too.loud"
 181
 182 /**
 183 * @brief Result warning message : The speech is too fast to listen
 184 */
 185 #define STTP_RESULT_MESSAGE_WARNING_TOO_FAST    "stt.result.message.warning.too.fast"
 186
 187 /**
 188 * @brief Result error message : Recognition was failed because the speech started too soon
 189 */
 190 #define STTP_RESULT_MESSAGE_ERROR_TOO_SOON      "stt.result.message.error.too.soon"
 191
 192 /**
 193 * @brief Result error message : Recognition was failed because the speech started too short
 194 */
 195 #define STTP_RESULT_MESSAGE_ERROR_TOO_SHORT     "stt.result.message.error.too.short"
 196
 197 /**
 198 * @brief Result error message : Recognition was failed because the speech started too long
 199 */
 200 #define STTP_RESULT_MESSAGE_ERROR_TOO_LONG      "stt.result.message.error.too.long"
 201
 202 /**
 203 * @brief Result error message : Recognition was failed because the speech started too quiet to listen
 204 */
 205 #define STTP_RESULT_MESSAGE_ERROR_TOO_QUIET     "stt.result.message.error.too.quiet"
 206
 207 /**
 208 * @brief Result error message : Recognition was failed because the speech started too loud to listen
 209 */
 210 #define STTP_RESULT_MESSAGE_ERROR_TOO_LOUD      "stt.result.message.error.too.loud"
 211
 212 /**
 213 * @brief Result error message : Recognition was failed because the speech started too fast to listen
 214 */
 215 #define STTP_RESULT_MESSAGE_ERROR_TOO_FAST      "stt.result.message.error.too.fast"
 216
 217 /**
 218 * @brief Called to get recognition result.
 219 *
 220 * @param[in] event A result event
 221 * @param[in] type A recognition type (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_COMMAND)
 222 * @param[in] data Result texts
 223 * @param[in] data_count Result text count
 224 * @param[in] msg Engine message (e.g. #STTP_RESULT_MESSAGE_WARNING_TOO_SOON, #STTP_RESULT_MESSAGE_ERROR_TOO_SHORT)
 225 * @param[in] user_data  The user data passed from the start function
 226 *
 227 * @pre sttpe_stop() will invoke this callback.
 228 *
 229 * @see sttpe_start()
 230 * @see sttpe_stop()
 231 */
 232 typedef void (*sttpe_result_cb)(sttp_result_event_e event, const char* type,
 233                                 const char** data, int data_count, const char* msg, void *user_data);
 234
 235 /**
 236 * @brief Called to get partial recognition result.
 237 *
 238 * @param[in] event A result event
 239 * @param[in] data A result text
 240 * @param[in] user_data  The user data passed from the start function.
 241 *
 242 * @pre sttpe_set_recording_data() will invoke this callback
 243 *
 244 * @see sttpe_set_recording_data()
 245 */
 246 typedef void (*sttpe_partial_result_cb)(sttp_result_event_e event, const char* data, void *user_data);
 247
 248 /**
 249 * @brief Called to detect silence from recording data.
 250 *
 251 * @param[in] user_data  The user data passed from the start function.
 252 *
 253 * @pre sttpe_set_recording_data() will invoke this callback.
 254 *
 255 * @see sttpe_set_recording_data()
 256 */
 257 typedef void (*sttpe_silence_detected_cb)(void *user_data);
 258
 259 /**
 260 * @brief Called to retrieve the supported languages.
 261 *
 262 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
 263 *               followed by ISO 639-1 for the two-letter language code \n
 264 *               For example, "ko_KR" for Korean, "en_US" for American English
 265 * @param[in] user_data The user data passed from the foreach function
 266 *
 267 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 268 *
 269 * @pre sttpe_foreach_supported_languages() will invoke this callback.
 270 *
 271 * @see sttpe_foreach_supported_languages()
 272 */
 273 typedef bool (*sttpe_supported_language_cb)(const char* language, void* user_data);
 274
 275 /**
 276 * @brief Called to retrieve the supported engine settings.
 277 *
 278 * @param[in] key A key
 279 * @param[in] value A value
 280 * @param[in] user_data The user data passed from the foreach function
 281 *
 282 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 283 * @pre sttpe_foreach_engine_settings() will invoke this callback.
 284 *
 285 * @see sttpe_foreach_engine_settings()
 286 */
 287 typedef bool (*sttpe_engine_setting_cb)(const char* key, const char* value, void* user_data);
 288
 289 /**
 290 * @brief Initializes the engine.
 291 *
 292 * @param[in] result_cb A callback function for recognition result
 293 * @param[in] partial_result_cb A callback function for partial recognition result
 294 * @param[in] silence_cb A callback function for silence detection
 295 *
 296 * @return 0 on success, otherwise a negative error value
 297 * @retval #STTP_ERROR_NONE Successful
 298 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 299 * @retval #STTP_ERROR_INVALID_STATE Already initialized
 300 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 301 *
 302 * @see sttpe_deinitialize()
 303 */
 304 typedef int (* sttpe_initialize)(sttpe_result_cb result_cb, sttpe_partial_result_cb partial_result_cb,
 305                                  sttpe_silence_detected_cb silence_cb);
 306
 307 /**
 308 * @brief Deinitializes the engine
 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 * @see sttpe_initialize()
 315 */
 316 typedef int (* sttpe_deinitialize)(void);
 317
 318 /**
 319 * @brief Retrieves all supported languages of the engine.
 320 *
 321 * @param[in] callback a callback function
 322 * @param[in] user_data The user data to be passed to the callback function
 323 *
 324 * @return 0 on success, otherwise a negative error value
 325 * @retval #STTP_ERROR_NONE Successful
 326 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 327 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 328 *
 329 * @post This function invokes sttpe_supported_language_cb() repeatedly for getting supported languages.
 330 *
 331 * @see sttpe_supported_language_cb()
 332 */
 333 typedef int (* sttpe_foreach_supported_languages)(sttpe_supported_language_cb callback, void* user_data);
 334
 335 /**
 336 * @brief Checks whether a language is valid or not.
 337 *
 338 * @param[in] language A language
 339 *
 340 * @return 0 on success, otherwise a negative error value
 341 * @retval #STTP_ERROR_NONE Successful
 342 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 343 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 344 *
 345 * @see sttpe_foreach_supported_languages()
 346 */
 347 typedef bool (* sttpe_is_valid_language)(const char* language);
 348
 349 /**
 350 * @brief Gets whether the engine supports silence detection.
 351 *
 352 * @return 0 on success, otherwise a negative error value
 353 * @retval #STTP_ERROR_NONE Successful
 354 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 355 */
 356 typedef bool (* sttpe_support_silence_detection)(void);
 357
 358 /**
 359 * @brief Gets supporting partial result.
 360 *
 361 * @return 0 on success, otherwise a negative error value
 362 * @retval #STTP_ERROR_NONE Successful
 363 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 364 */
 365 typedef bool (* sttpe_support_partial_result)(void);
 366
 367 /**
 368 * @brief Gets recording format of the engine.
 369 *
 370 * @param[out] types The format used by the recorder.
 371 * @param[out] rate The sample rate used by the recorder.
 372 * @param[out] channels The number of channels used by the recorder.
 373 *
 374 * @return 0 on success, otherwise a negative error value
 375 * @retval #STTP_ERROR_NONE Successful
 376 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 377 */
 378 typedef int (* sttpe_get_recording_format)(sttp_audio_type_e* types, int* rate, int* channels);
 379
 380 /**
 381 * @brief Sets profanity filter option.
 382 *
 383 * @param[in] value A value
 384 *
 385 * @return 0 on success, otherwise a negative error value
 386 * @retval #STTP_ERROR_NONE Successful
 387 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 388 * @retval #STTP_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 389 */
 390 typedef int (* sttpe_set_profanity_filter)(bool value);
 391
 392 /**
 393 * @brief Sets punctuation option.
 394 *
 395 * @param[in] value A value
 396 *
 397 * @return 0 on success, otherwise a negative error value
 398 * @retval #STTP_ERROR_NONE Successful
 399 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 400 * @retval #STTP_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 401 */
 402 typedef int (* sttpe_set_punctuation_override)(bool value);
 403
 404 /**
 405 * @brief Sets silence detection option.
 406 *
 407 * @param[in] value A value
 408 *
 409 * @return 0 on success, otherwise a negative error value
 410 * @retval #STTP_ERROR_NONE Successful
 411 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 412 * @retval #STTP_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 413 */
 414 typedef int (* sttpe_set_silence_detection)(bool value);
 415
 416 /**
 417 * @brief Start recognition.
 418 *
 419 * @param[in] language A language.
 420 * @param[in] type A recognition type. (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_WEB_SEARCH)
 421 * @param[in] user_data The user data to be passed to the callback function.
 422 *
 423 * @return 0 on success, otherwise a negative error value
 424 * @retval #STTP_ERROR_NONE Successful
 425 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 426 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 427 * @retval #STTP_ERROR_INVALID_LANGUAGE Invalid language
 428 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 429 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 430 *
 431 * @pre The engine is not in recognition processing.
 432 *
 433 * @see sttpe_set_recording_data()
 434 * @see sttpe_stop()
 435 * @see sttpe_cancel()
 436 */
 437 typedef int (* sttpe_start)(const char* language, const char* type, void *user_data);
 438
 439 /**
 440 * @brief Sets recording data for speech recognition from recorder.
 441 *
 442 * @remark This function should be returned immediately after recording data copy.
 443 *
 444 * @param[in] data A recording data
 445 * @param[in] length A length of recording data
 446 *
 447 * @return 0 on success, otherwise a negative error value
 448 * @retval #STTP_ERROR_NONE Successful
 449 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 450 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 451 *
 452 * @pre sttpe_start() should succeed.
 453 * @post If the engine supports partial result, it will invoke sttpe_partial_result_cb().
 454 *
 455 * @see sttpe_start()
 456 * @see sttpe_cancel()
 457 * @see sttpe_stop()
 458 * @see sttpe_partial_result_cb()
 459 */
 460 typedef int (* sttpe_set_recording_data)(const void* data, unsigned int length);
 461
 462 /**
 463 * @brief Stops to set recording data.
 464 *
 465 * @return 0 on success, otherwise a negative error value
 466 * @retval #STTP_ERROR_NONE Successful
 467 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 468 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 469 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 470 *
 471 * @pre sttpe_start() should succeed.
 472 * @post After processing of the engine, sttpe_result_cb() is called.
 473 *
 474 * @see sttpe_start()
 475 * @see sttpe_set_recording_data()
 476 * @see sttpe_result_cb()
 477 * @see sttpe_cancel()
 478 */
 479 typedef int (* sttpe_stop)(void);
 480
 481 /**
 482 * @brief Cancels the recognition process.
 483 *
 484 * @return 0 on success, otherwise a negative error value.
 485 * @retval #STTP_ERROR_NONE Successful.
 486 * @retval #STTP_ERROR_INVALID_STATE Invalid state.
 487 * @pre STT engine is in recognition processing.
 488 *
 489 * @see sttpe_start()
 490 * @see sttpe_stop()
 491 */
 492 typedef int (* sttpe_cancel)(void);
 493
 494 /**
 495 * @brief Gets setting information of the engine.
 496 *
 497 * @param[in] callback A callback function.
 498 * @param[in] user_data The user data to be passed to the callback function.
 499 *
 500 * @return 0 on success, otherwise a negative error value
 501 * @retval #STTP_ERROR_NONE Successful
 502 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 503 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 504 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 505 *
 506 * @post This function invokes sttpe_engine_setting_cb() repeatedly for getting engine settings.
 507 *
 508 * @see sttpe_engine_setting_cb()
 509 */
 510 typedef int (* sttpe_foreach_engine_settings)(sttpe_engine_setting_cb callback, void* user_data);
 511
 512 /**
 513 * @brief Set engine specific information.
 514 *
 515 * @param[in] key A key
 516 * @param[in] value A value
 517 *
 518 * @return 0 on success, otherwise a negative error value
 519 * @retval #STTP_ERROR_NONE Successful
 520 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 521 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 522 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 523 *
 524 * @see sttpe_foreach_engine_settings()
 525 */
 526 typedef int (* sttpe_set_engine_setting)(const char* key, const char* value);
 527
 528
 529 /**
 530 * @brief A structure of the engine functions.
 531 */
 532 typedef struct {
 533         int size;                                               /**< Size of structure */
 534         int version;                                            /**< Version */
 535
 536         sttpe_initialize                initialize;             /**< Initialize engine */
 537         sttpe_deinitialize              deinitialize;           /**< Shutdown engine */
 538
 539         /* Get engine information */
 540         sttpe_foreach_supported_languages foreach_langs;        /**< Foreach language list */
 541         sttpe_is_valid_language         is_valid_lang;          /**< Check language */
 542         sttpe_support_silence_detection support_silence;        /**< Get silence detection support */
 543         sttpe_support_partial_result    support_partial_result; /**< Get partial result support */
 544         sttpe_get_recording_format      get_audio_format;       /**< Get audio format */
 545
 546         /* Set engine information */
 547         sttpe_set_profanity_filter      set_profanity_filter;   /**< Set profanity filter */
 548         sttpe_set_punctuation_override  set_punctuation;        /**< Set punctuation override */
 549         sttpe_set_silence_detection     set_silence_detection;  /**< Set silence detection */
 550
 551         /* Control recognition */
 552         sttpe_start                     start;                  /**< Start recognition */
 553         sttpe_set_recording_data        set_recording;          /**< Set recording data */
 554         sttpe_stop                      stop;                   /**< Shutdown function */
 555         sttpe_cancel                    cancel;                 /**< Cancel recognition or cancel thinking */
 556
 557         /* Engine setting */
 558         sttpe_foreach_engine_settings   foreach_engine_settings;/**< Foreach engine specific info */
 559         sttpe_set_engine_setting        set_engine_setting;     /**< Set engine specific info */
 560 } sttpe_funcs_s;
 561
 562 /**
 563 * @brief A structure of the daemon functions.
 564 */
 565 typedef struct {
 566         int size;                                               /**< size */
 567         int version;                                            /**< version */
 568
 569 } sttpd_funcs_s;
 570
 571 /**
 572 * @brief Loads the engine.
 573 *
 574 * @param[in] pdfuncs The daemon functions
 575 * @param[out] pefuncs The engine functions
 576 *
 577 * @return This function returns zero on success, or negative with error code on failure
 578 * @retval #STTP_ERROR_NONE Successful
 579 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 580 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 581 *
 582 * @pre The sttp_get_engine_info() should be successful.
 583 * @post The daemon calls engine functions of sttpe_funcs_s.
 584 *
 585 * @see sttp_get_engine_info()
 586 * @see sttp_unload_engine()
 587 */
 588 int sttp_load_engine(sttpd_funcs_s* pdfuncs, sttpe_funcs_s* pefuncs);
 589
 590 /**
 591 * @brief Unloads this engine by the daemon.
 592 *
 593 * @pre The sttp_load_engine() should be successful.
 594 *
 595 * @see sttp_load_engine()
 596 */
 597 void sttp_unload_engine(void);
 598
 599 /**
 600 * @brief Called to get the engine base information.
 601 *
 602 * @param[in] engine_uuid The engine id
 603 * @param[in] engine_name The engine name
 604 * @param[in] setting_ug_name The setting ug name
 605 * @param[in] use_network @c true to need network @c false not to need network.
 606 * @param[in] user_data The User data passed from sttp_get_engine_info()
 607 *
 608 * @pre sttp_get_engine_info() will invoke this callback.
 609 *
 610 * @see sttp_get_engine_info()
 611 */
 612 typedef void (*sttpe_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* setting_ug_name,
 613                                      bool use_network, void* user_data);
 614
 615 /**
 616 * @brief Gets the engine base information before the engine is loaded by the daemon.
 617 *
 618 * @param[in] callback Callback function
 619 * @param[in] user_data User data to be passed to the callback function
 620 *
 621 * @return This function returns zero on success, or negative with error code on failure
 622 * @retval #STTP_ERROR_NONE Successful
 623 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 624 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 625 *
 626 * @post This function invokes sttpe_engine_info_cb() for getting engine information.
 627 *
 628 * @see sttpe_engine_info_cb()
 629 * @see sttp_load_engine()
 630 */
 631 int sttp_get_engine_info(sttpe_engine_info_cb callback, void* user_data);
 632
 633 #ifdef __cplusplus
 634 }
 635 #endif
 636
 637 /**
 638  * @}@}
 639  */
 640
 641 #endif /* __STTP_H__ */