server/sttp.h

   1 /*
   2 *  Copyright (c) 2011-2016 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 <tizen.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                         = TIZEN_ERROR_NONE,             /**< Successful */
  34         STTP_ERROR_OUT_OF_MEMORY                = TIZEN_ERROR_OUT_OF_MEMORY,    /**< Out of Memory */
  35         STTP_ERROR_IO_ERROR                     = TIZEN_ERROR_IO_ERROR,         /**< I/O error */
  36         STTP_ERROR_INVALID_PARAMETER            = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */
  37         STTP_ERROR_TIMED_OUT                    = TIZEN_ERROR_TIMED_OUT,        /**< No answer from the daemon */
  38         STTP_ERROR_RECORDER_BUSY                = TIZEN_ERROR_RESOURCE_BUSY,    /**< Device or resource busy */
  39         STTP_ERROR_OUT_OF_NETWORK               = TIZEN_ERROR_NETWORK_DOWN,     /**< Network is down */
  40         STTP_ERROR_PERMISSION_DENIED            = TIZEN_ERROR_PERMISSION_DENIED,/**< Permission denied */
  41         STTP_ERROR_NOT_SUPPORTED                = TIZEN_ERROR_NOT_SUPPORTED,    /**< STT NOT supported */
  42         STTP_ERROR_INVALID_STATE                = TIZEN_ERROR_STT | 0x01,       /**< Invalid state */
  43         STTP_ERROR_INVALID_LANGUAGE             = TIZEN_ERROR_STT | 0x02,       /**< Invalid language */
  44         STTP_ERROR_ENGINE_NOT_FOUND             = TIZEN_ERROR_STT | 0x03,       /**< No available engine  */
  45         STTP_ERROR_OPERATION_FAILED             = TIZEN_ERROR_STT | 0x04,       /**< Operation failed  */
  46         STTP_ERROR_NOT_SUPPORTED_FEATURE        = TIZEN_ERROR_STT | 0x05,       /**< Not supported feature of current engine */
  47         STTP_ERROR_NO_SPEECH                    = TIZEN_ERROR_STT | 0x06,       /**< No speech while recording */
  48         STTP_ERROR_RECORDING_TIMED_OUT          = TIZEN_ERROR_STT | 0x10        /**< Recording timed out */
  49 } sttp_error_e;
  50
  51 /**
  52 * @brief Enumerations of audio type.
  53 */
  54 typedef enum {
  55         STTP_AUDIO_TYPE_PCM_S16_LE = 0, /**< Signed 16bit audio type, Little endian */
  56         STTP_AUDIO_TYPE_PCM_U8          /**< Unsigned 8bit audio type */
  57 } sttp_audio_type_e;
  58
  59 /**
  60 * @brief Enumerations of callback event.
  61 */
  62 typedef enum {
  63         STTP_RESULT_EVENT_FINAL_RESULT = 0,     /**< Event when the recognition full or last result is ready  */
  64         STTP_RESULT_EVENT_PARTIAL_RESULT,       /**< Event when the recognition partial result is ready  */
  65         STTP_RESULT_EVENT_ERROR                 /**< Event when the recognition has failed */
  66 } sttp_result_event_e;
  67
  68 /**
  69 * @brief Enumerations of result time callback event.
  70 */
  71 typedef enum {
  72         STTP_RESULT_TIME_EVENT_BEGINNING = 0,   /**< Event when the token is beginning type */
  73         STTP_RESULT_TIME_EVENT_MIDDLE,          /**< Event when the token is middle type */
  74         STTP_RESULT_TIME_EVENT_END              /**< Event when the token is end type */
  75 } sttp_result_time_event_e;
  76
  77 /**
  78 * @brief Enumerations of silence type.
  79 */
  80 typedef enum {
  81         STTP_SILENCE_TYPE_NO_RECORD_TIMEOUT = 0,        /**< No sound is recorded */
  82         STTP_SILENCE_TYPE_END_OF_SPEECH_DETECTED        /**< End of speech is detected */
  83 } sttp_silence_type_e;
  84
  85 /**
  86 * @brief Recognition type : free form dictation and default type.
  87 */
  88 #define STTP_RECOGNITION_TYPE_FREE              "stt.recognition.type.FREE"
  89
  90 /**
  91 * @brief Recognition type : free form dictation continuously.
  92 */
  93 #define STTP_RECOGNITION_TYPE_FREE_PARTIAL      "stt.recognition.type.FREE.PARTIAL"
  94
  95 /**
  96 * @brief Recognition type : Search.
  97 */
  98 #define STTP_RECOGNITION_TYPE_SEARCH            "stt.recognition.type.SEARCH"
  99
 100 /**
 101 * @brief Recognition type : web search.
 102 */
 103 #define STTP_RECOGNITION_TYPE_WEB_SEARCH        "stt.recognition.type.WEB_SEARCH"
 104
 105 /**
 106 * @brief Recognition type : Map.
 107 */
 108 #define STTP_RECOGNITION_TYPE_MAP               "stt.recognition.type.MAP"
 109
 110
 111 /**
 112 * @brief Result message : None message
 113 */
 114 #define STTP_RESULT_MESSAGE_NONE                "stt.result.message.none"
 115
 116 /**
 117 * @brief Result error message : Recognition was failed because the speech started too soon
 118 */
 119 #define STTP_RESULT_MESSAGE_ERROR_TOO_SOON      "stt.result.message.error.too.soon"
 120
 121 /**
 122 * @brief Result error message : Recognition was failed because the speech started too short
 123 */
 124 #define STTP_RESULT_MESSAGE_ERROR_TOO_SHORT     "stt.result.message.error.too.short"
 125
 126 /**
 127 * @brief Result error message : Recognition was failed because the speech started too long
 128 */
 129 #define STTP_RESULT_MESSAGE_ERROR_TOO_LONG      "stt.result.message.error.too.long"
 130
 131 /**
 132 * @brief Result error message : Recognition was failed because the speech started too quiet to listen
 133 */
 134 #define STTP_RESULT_MESSAGE_ERROR_TOO_QUIET     "stt.result.message.error.too.quiet"
 135
 136 /**
 137 * @brief Result error message : Recognition was failed because the speech started too loud to listen
 138 */
 139 #define STTP_RESULT_MESSAGE_ERROR_TOO_LOUD      "stt.result.message.error.too.loud"
 140
 141 /**
 142 * @brief Result error message : Recognition was failed because the speech started too fast to listen
 143 */
 144 #define STTP_RESULT_MESSAGE_ERROR_TOO_FAST      "stt.result.message.error.too.fast"
 145
 146 /**
 147 * @brief Called to get recognition result.
 148 *
 149 * @param[in] event A result event
 150 * @param[in] type A recognition type (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_FREE_PARTIAL)
 151 * @param[in] data Result texts
 152 * @param[in] data_count Result text count
 153 * @param[in] msg Engine message (e.g. #STTP_RESULT_MESSAGE_NONE, #STTP_RESULT_MESSAGE_ERROR_TOO_SHORT)
 154 * @param[in] user_data  The user data passed from the start function
 155 *
 156 * @pre sttpe_stop() will invoke this callback.
 157 *
 158 * @see sttpe_start()
 159 * @see sttpe_stop()
 160 */
 161 typedef void (*sttpe_result_cb)(sttp_result_event_e event, const char* type, const char** data, int data_count,
 162                                 const char* msg, void* time_info, void* user_data);
 163
 164 /**
 165 * @brief Called to retrieve the time stamp of result.
 166 *
 167 * @param[in] index The result index
 168 * @param[in] event The token event
 169 * @param[in] text The result text
 170 * @param[in] start_time The start time of result text
 171 * @param[in] end_time The end time of result text
 172 * @param[in] user_data The user data passed from the foreach function
 173 *
 174 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 175 *
 176 * @pre sttpe_result_cb() should be called.
 177 *
 178 * @see sttpe_result_cb()
 179 */
 180 typedef bool (*sttpe_result_time_cb)(int index, sttp_result_time_event_e event, const char* text,
 181                                 long start_time, long end_time, void* user_data);
 182
 183 /**
 184 * @brief Called to detect silence from recording data.
 185 *
 186 * @param[in] user_data  The user data passed from the start function.
 187 *
 188 * @pre sttpe_set_recording_data() will invoke this callback.
 189 *
 190 * @see sttpe_set_recording_data()
 191 */
 192 typedef void (*sttpe_silence_detected_cb)(sttp_silence_type_e type, void* user_data);
 193
 194 /**
 195 * @brief Called to retrieve the supported languages.
 196 *
 197 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
 198 *               followed by ISO 639-1 for the two-letter language code \n
 199 *               For example, "ko_KR" for Korean, "en_US" for American English
 200 * @param[in] user_data The user data passed from the foreach function
 201 *
 202 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 203 *
 204 * @pre sttpe_foreach_supported_languages() will invoke this callback.
 205 *
 206 * @see sttpe_foreach_supported_languages()
 207 */
 208 typedef bool (*sttpe_supported_language_cb)(const char* language, void* user_data);
 209
 210 /**
 211 * @brief Initializes the engine.
 212 *
 213 * @param[in] result_cb A callback function for recognition result
 214 * @param[in] silence_cb A callback function for silence detection
 215 *
 216 * @return 0 on success, otherwise a negative error value
 217 * @retval #STTP_ERROR_NONE Successful
 218 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 219 * @retval #STTP_ERROR_INVALID_STATE Already initialized
 220 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 221 *
 222 * @see sttpe_deinitialize()
 223 */
 224 typedef int (*sttpe_initialize)(sttpe_result_cb result_cb, sttpe_silence_detected_cb silence_cb);
 225
 226 /**
 227 * @brief Deinitializes the engine
 228 *
 229 * @return 0 on success, otherwise a negative error value
 230 * @retval #STTP_ERROR_NONE Successful
 231 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 232 *
 233 * @see sttpe_initialize()
 234 */
 235 typedef int (*sttpe_deinitialize)(void);
 236
 237 /**
 238 * @brief Retrieves all supported languages of the engine.
 239 *
 240 * @param[in] callback a callback function
 241 * @param[in] user_data The user data to be passed to the callback function
 242 *
 243 * @return 0 on success, otherwise a negative error value
 244 * @retval #STTP_ERROR_NONE Successful
 245 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 246 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 247 *
 248 * @post This function invokes sttpe_supported_language_cb() repeatedly for getting supported languages.
 249 *
 250 * @see sttpe_supported_language_cb()
 251 */
 252 typedef int (*sttpe_foreach_supported_langs)(sttpe_supported_language_cb callback, void* user_data);
 253
 254 /**
 255 * @brief Checks whether a language is valid or not.
 256 *
 257 * @param[in] language A language
 258 *
 259 * @return @c true to valid language, \n @c false to invalid language.
 260 *
 261 * @see sttpe_foreach_supported_languages()
 262 */
 263 typedef bool (*sttpe_is_valid_language)(const char* language);
 264
 265 /**
 266 * @brief Gets whether the engine supports silence detection.
 267 *
 268 * @return @c true to support silence detection, \n @c false not to support silence detection.
 269 *
 270 * @see sttpe_set_silence_detection()
 271 */
 272 typedef bool (*sttpe_support_silence_detection)(void);
 273
 274 /**
 275 * @brief Gets credential necessity.
 276 *
 277 * @return @c true to be needed app credential, \n @c false not to be needed app credential.
 278 *
 279 */
 280 typedef bool (*sttpe_need_app_credential)(void);
 281
 282 /**
 283 * @brief Gets supporting recognition type.
 284 *
 285 * @return @c true to support recognition type, \n @c false not to support recognition type.
 286 *
 287 */
 288 typedef bool (*sttpe_support_recognition_type)(const char* type);
 289
 290 /**
 291 * @brief Gets recording format of the engine.
 292 *
 293 * @param[out] types The format used by the recorder.
 294 * @param[out] rate The sample rate used by the recorder.
 295 * @param[out] channels The number of channels used by the recorder.
 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 int (*sttpe_get_recording_format)(sttp_audio_type_e* types, int* rate, int* channels);
 302
 303 /**
 304 * @brief Sets silence detection option.
 305 *
 306 * @param[in] value A value
 307 *
 308 * @return 0 on success, otherwise a negative error value
 309 * @retval #STTP_ERROR_NONE Successful
 310 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 311 * @retval #STTP_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 312 */
 313 typedef int (*sttpe_set_silence_detection)(bool value);
 314
 315 /**
 316 * @brief Gets whether application is agreed to get engine service.
 317 *
 318 * @param[in] appid Application ID
 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_FEATURE Not supported feature
 325 */
 326 typedef int (*sttpe_check_app_agreed)(const char* appid, bool* value);
 327
 328 /**
 329 * @brief Retrieves result time info in recognition callback of daemon.
 330 *
 331 * @param[in] callback a callback function
 332 * @param[in] user_data The user data to be passed to the callback function
 333 *
 334 * @return 0 on success, otherwise a negative error value
 335 * @retval #STTP_ERROR_NONE Successful
 336 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 337 * @retval #STTP_ERROR_INVALID_STATE Not initialized
 338 *
 339 * @pre sttpe_result_cb() will be invoke this function.
 340 * @post This function invokes sttpe_result_time_cb() repeatedly for getting result time information.
 341 *
 342 * @see sttpe_result_time_cb()
 343 */
 344 typedef int (*sttpe_foreach_result_time)(void* time_info, sttpe_result_time_cb callback, void* user_data);
 345
 346 /**
 347 * @brief Start recognition.
 348 *
 349 * @param[in] language A language.
 350 * @param[in] type A recognition type. (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_WEB_SEARCH)
 351 * @parma[in] credential The app credential to allow recognition
 352 * @param[in] user_data The user data to be passed to the callback function.
 353 *
 354 * @return 0 on success, otherwise a negative error value
 355 * @retval #STTP_ERROR_NONE Successful
 356 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 357 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 358 * @retval #STTP_ERROR_INVALID_LANGUAGE Invalid language
 359 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 360 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 361 * @retval #STTP_ERROR_PERMISSION_DENIED Permission denied
 362 *
 363 * @pre The engine is not in recognition processing.
 364 *
 365 * @see sttpe_set_recording_data()
 366 * @see sttpe_stop()
 367 * @see sttpe_cancel()
 368 */
 369 typedef int (* sttpe_start)(const char* language, const char* type, const char* credential, void *user_data);
 370
 371 /**
 372 * @brief Sets recording data for speech recognition from recorder.
 373 *
 374 * @remark This function should be returned immediately after recording data copy.
 375 *
 376 * @param[in] data A recording data
 377 * @param[in] length A length of recording data
 378 *
 379 * @return 0 on success, otherwise a negative error value
 380 * @retval #STTP_ERROR_NONE Successful
 381 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 382 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 383 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 384 *
 385 * @pre sttpe_start() should succeed.
 386 * @post If the engine supports partial result, it will invoke sttpe_result_cb().
 387 *
 388 * @see sttpe_start()
 389 * @see sttpe_cancel()
 390 * @see sttpe_stop()
 391 */
 392 typedef int (*sttpe_set_recording_data)(const void* data, unsigned int length);
 393
 394 /**
 395 * @brief Stops to set recording data.
 396 *
 397 * @return 0 on success, otherwise a negative error value
 398 * @retval #STTP_ERROR_NONE Successful
 399 * @retval #STTP_ERROR_INVALID_STATE Invalid state
 400 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 401 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 402 *
 403 * @pre sttpe_start() should succeed.
 404 * @post After processing of the engine, sttpe_result_cb() is called.
 405 *
 406 * @see sttpe_start()
 407 * @see sttpe_set_recording_data()
 408 * @see sttpe_result_cb()
 409 * @see sttpe_cancel()
 410 */
 411 typedef int (*sttpe_stop)(void);
 412
 413 /**
 414 * @brief Cancels the recognition process.
 415 *
 416 * @return 0 on success, otherwise a negative error value.
 417 * @retval #STTP_ERROR_NONE Successful.
 418 * @retval #STTP_ERROR_INVALID_STATE Invalid state.
 419 * @pre STT engine is in recognition processing or recording.
 420 *
 421 * @see sttpe_start()
 422 * @see sttpe_stop()
 423 */
 424 typedef int (*sttpe_cancel)(void);
 425
 426 /**
 427 * @brief Start recognition of file.
 428 *
 429 * @param[in] language A language.
 430 * @param[in] type A recognition type. (e.g. #STTP_RECOGNITION_TYPE_FREE, #STTP_RECOGNITION_TYPE_WEB_SEARCH)
 431 * @param[in] filepath A filepath for recognition.
 432 * @param[in] audio_type A audio type of file.
 433 * @param[in] sample_rate A sample rate of file.
 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 Invalid state
 440 * @retval #STTP_ERROR_INVALID_LANGUAGE Invalid language
 441 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 442 * @retval #STTP_ERROR_OUT_OF_NETWORK Out of network
 443 *
 444 * @pre The engine is not in recognition processing.
 445 *
 446 * @see sttpe_cancel_file()
 447 */
 448 typedef int (*sttpe_start_file)(const char* language, const char* type, const char* filepath,
 449                                  sttp_audio_type_e audio_type, int sample_rate, void *user_data);
 450
 451 /**
 452 * @brief Cancels the recognition process of file.
 453 *
 454 * @return 0 on success, otherwise a negative error value.
 455 * @retval #STTP_ERROR_NONE Successful.
 456 * @retval #STTP_ERROR_INVALID_STATE Invalid state.
 457 * @pre STT engine is in recognition processing.
 458 *
 459 * @see sttpe_start_file()
 460 */
 461 typedef int (*sttpe_cancel_file)(void);
 462
 463 /**
 464 * @brief Set private data.
 465 * @since_tizen 3.0
 466 *
 467 * @param[in] key Key field of private data.
 468 * @param[in] data Data field of private data.
 469 *
 470 * @return 0 on success, otherwise a negative error value
 471 * @retval #STTP_ERROR_NONE Successful
 472 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 473 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 474 *
 475 * @see sttpe_get_private_data()
 476 */
 477 typedef int (* sttpe_set_private_data)(const char* key, const char* data);
 478
 479 /**
 480 * @brief Get private data.
 481 * @since_tizen 3.0
 482 *
 483 * @param[out] key Key field of private data.
 484 * @param[out] data Data field of private data.
 485 *
 486 * @return 0 on success, otherwise a negative error value
 487 * @retval #STTP_ERROR_NONE Successful
 488 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 489 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 490 *
 491 * @see sttpe_set_private_data()
 492 */
 493 typedef int (* sttpe_get_private_data)(const char* key, char** data);
 494
 495 /**
 496 * @brief A structure of the engine functions.
 497 */
 498 typedef struct {
 499         int size;                                               /**< Size of structure */
 500         int version;                                            /**< Version */
 501
 502         sttpe_initialize                initialize;             /**< Initialize engine */
 503         sttpe_deinitialize              deinitialize;           /**< Shutdown engine */
 504
 505         /* Get engine information */
 506         sttpe_foreach_supported_langs   foreach_langs;          /**< Foreach language list */
 507         sttpe_is_valid_language         is_valid_lang;          /**< Check language */
 508         sttpe_support_silence_detection support_silence;        /**< Get silence detection support */
 509         sttpe_support_recognition_type  support_recognition_type; /**< Get recognition type support */
 510         sttpe_need_app_credential       need_app_credential;    /**< Get app credential necessity*/
 511         sttpe_get_recording_format      get_audio_format;       /**< Get audio format */
 512         sttpe_foreach_result_time       foreach_result_time;    /**< Foreach result time */
 513
 514         /* Set engine information */
 515         sttpe_set_silence_detection     set_silence_detection;  /**< Set silence detection */
 516
 517         /* Check app agreement */
 518         sttpe_check_app_agreed          check_app_agreed;       /**< Get app agreement */
 519
 520         /* Control recognition */
 521         sttpe_start                     start;                  /**< Start recognition */
 522         sttpe_set_recording_data        set_recording;          /**< Set recording data */
 523         sttpe_stop                      stop;                   /**< Shutdown function */
 524         sttpe_cancel                    cancel;                 /**< Cancel recognition */
 525
 526         /* Control file recognition */
 527         sttpe_start_file                start_file;             /**< Start recognition */
 528         sttpe_cancel_file               cancel_file;            /**< Cancel recognition */
 529
 530         /* Set/Get private data */
 531         sttpe_set_private_data          set_private_data;       /**< Set private data */
 532         sttpe_get_private_data          get_private_data;       /**< Get private data */
 533 } sttpe_funcs_s;
 534
 535 /**
 536 * @brief A structure of the daemon functions.
 537 */
 538 typedef struct {
 539         int size;                                               /**< size */
 540         int version;                                            /**< version */
 541
 542 } sttpd_funcs_s;
 543
 544 /**
 545 * @brief Loads the engine.
 546 *
 547 * @param[in] pdfuncs The daemon functions
 548 * @param[out] pefuncs The engine functions
 549 *
 550 * @return This function returns zero on success, or negative with error code on failure
 551 * @retval #STTP_ERROR_NONE Successful
 552 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 553 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 554 *
 555 * @pre The sttp_get_engine_info() should be successful.
 556 * @post The daemon calls engine functions of sttpe_funcs_s.
 557 *
 558 * @see sttp_get_engine_info()
 559 * @see sttp_unload_engine()
 560 */
 561 int sttp_load_engine(sttpd_funcs_s* pdfuncs, sttpe_funcs_s* pefuncs);
 562
 563 /**
 564 * @brief Unloads this engine by the daemon.
 565 *
 566 * @pre The sttp_load_engine() should be successful.
 567 *
 568 * @see sttp_load_engine()
 569 */
 570 void sttp_unload_engine(void);
 571
 572 /**
 573 * @brief Called to get the engine base information.
 574 *
 575 * @param[in] engine_uuid The engine id
 576 * @param[in] engine_name The engine name
 577 * @param[in] engine_setting The setting name
 578 * @param[in] use_network @c true to need network @c false not to need network.
 579 * @param[in] user_data The User data passed from sttp_get_engine_info()
 580 *
 581 * @pre sttp_get_engine_info() will invoke this callback.
 582 *
 583 * @see sttp_get_engine_info()
 584 */
 585 typedef void (*sttpe_engine_info_cb)(const char* engine_uuid, const char* engine_name, const char* engine_setting,
 586                                      bool use_network, void* user_data);
 587
 588 /**
 589 * @brief Gets the engine base information before the engine is loaded by the daemon.
 590 *
 591 * @param[in] callback Callback function
 592 * @param[in] user_data User data to be passed to the callback function
 593 *
 594 * @return This function returns zero on success, or negative with error code on failure
 595 * @retval #STTP_ERROR_NONE Successful
 596 * @retval #STTP_ERROR_INVALID_PARAMETER Invalid parameter
 597 * @retval #STTP_ERROR_OPERATION_FAILED Operation failed
 598 *
 599 * @post This function invokes sttpe_engine_info_cb() for getting engine information.
 600 *
 601 * @see sttpe_engine_info_cb()
 602 * @see sttp_load_engine()
 603 */
 604 int sttp_get_engine_info(sttpe_engine_info_cb callback, void* user_data);
 605
 606 #ifdef __cplusplus
 607 }
 608 #endif
 609
 610 /**
 611  * @}
 612  */
 613
 614 #endif /* __STTP_H__ */