include/stte.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 __STT_ENGINE_MAIN_H__
  15 #define __STT_ENGINE_MAIN_H__
  16
  17 #include <tizen.h>
  18
  19 /**
  20 * @addtogroup CAPI_UIX_STTE_MODULE
  21 * @{
  22 */
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29 * @brief Enumerations for error codes.
  30 * @since_tizen 3.0
  31 */
  32 typedef enum {
  33         STTE_ERROR_NONE                         = TIZEN_ERROR_NONE,                     /**< Successful */
  34         STTE_ERROR_OUT_OF_MEMORY                = TIZEN_ERROR_OUT_OF_MEMORY,            /**< Out of Memory */
  35         STTE_ERROR_IO_ERROR                     = TIZEN_ERROR_IO_ERROR,                 /**< I/O error */
  36         STTE_ERROR_INVALID_PARAMETER            = TIZEN_ERROR_INVALID_PARAMETER,        /**< Invalid parameter */
  37         STTE_ERROR_NETWORK_DOWN                 = TIZEN_ERROR_NETWORK_DOWN,             /**< Network down(Out of network) */
  38         STTE_ERROR_INVALID_STATE                = TIZEN_ERROR_STT | 0x01,               /**< Invalid state */
  39         STTE_ERROR_INVALID_LANGUAGE             = TIZEN_ERROR_STT | 0x02,               /**< Invalid language */
  40         STTE_ERROR_OPERATION_FAILED             = TIZEN_ERROR_STT | 0x04,               /**< Operation failed */
  41         STTE_ERROR_NOT_SUPPORTED_FEATURE        = TIZEN_ERROR_STT | 0x05,               /**< Not supported feature */
  42         STTE_ERROR_NOT_SUPPORTED                = TIZEN_ERROR_NOT_SUPPORTED,            /**< Not supported */
  43         STTE_ERROR_PERMISSION_DENIED            = TIZEN_ERROR_PERMISSION_DENIED,        /**< Permission denied */
  44         STTE_ERROR_RECORDING_TIMED_OUT          = TIZEN_ERROR_STT | 0x06                /**< Recording timed out */
  45 } stte_error_e;
  46
  47 /**
  48 * @brief Enumerations for audio type.
  49 * @since_tizen 3.0
  50 */
  51 typedef enum {
  52         STTE_AUDIO_TYPE_PCM_S16_LE = 0,         /**< Signed 16bit audio type, Little endian */
  53         STTE_AUDIO_TYPE_PCM_U8                  /**< Unsigned 8bit audio type */
  54 } stte_audio_type_e;
  55
  56 /**
  57 * @brief Enumerations for callback event.
  58 * @since_tizen 3.0
  59 */
  60 typedef enum {
  61         STTE_RESULT_EVENT_FINAL_RESULT = 0,     /**< Event when either the full matched or the final result is delivered */
  62         STTE_RESULT_EVENT_PARTIAL_RESULT,       /**< Event when the partial matched result is delivered */
  63         STTE_RESULT_EVENT_ERROR                 /**< Event when the recognition has failed */
  64 } stte_result_event_e;
  65
  66 /**
  67 * @brief Enumerations for result time callback event.
  68 * @since_tizen 3.0
  69 */
  70 typedef enum {
  71         STTE_RESULT_TIME_EVENT_BEGINNING = 0,   /**< Event when the token is beginning type */
  72         STTE_RESULT_TIME_EVENT_MIDDLE,          /**< Event when the token is middle type */
  73         STTE_RESULT_TIME_EVENT_END              /**< Event when the token is end type */
  74 } stte_result_time_event_e;
  75
  76 /**
  77 * @brief Enumerations for speech status.
  78 * @since_tizen 3.0
  79 */
  80 typedef enum {
  81         STTE_SPEECH_STATUS_BEGINNING_POINT_DETECTED = 0,        /**< Beginning point of speech is detected */
  82         STTE_SPEECH_STATUS_END_POINT_DETECTED           /**< End point of speech is detected */
  83 } stte_speech_status_e;
  84
  85 /**
  86 * @brief Definition for free form dictation and default type.
  87 * @since_tizen 3.0
  88 */
  89 #define STTE_RECOGNITION_TYPE_FREE              "stt.recognition.type.FREE"
  90
  91 /**
  92 * @brief Definition for free form dictation continuously.
  93 * @since_tizen 3.0
  94 */
  95 #define STTE_RECOGNITION_TYPE_FREE_PARTIAL      "stt.recognition.type.FREE.PARTIAL"
  96
  97 /**
  98 * @brief Definition for None message.
  99 * @since_tizen 3.0
 100 */
 101 #define STTE_RESULT_MESSAGE_NONE                "stt.result.message.none"
 102
 103 /**
 104 * @brief Definition for failed recognition because the speech started too soon.
 105 * @since_tizen 3.0
 106 */
 107 #define STTE_RESULT_MESSAGE_ERROR_TOO_SOON      "stt.result.message.error.too.soon"
 108
 109 /**
 110 * @brief Definition for failed recognition because the speech started too short.
 111 * @since_tizen 3.0
 112 */
 113 #define STTE_RESULT_MESSAGE_ERROR_TOO_SHORT     "stt.result.message.error.too.short"
 114
 115 /**
 116 * @brief Definition for failed recognition because the speech started too long.
 117 * @since_tizen 3.0
 118 */
 119 #define STTE_RESULT_MESSAGE_ERROR_TOO_LONG      "stt.result.message.error.too.long"
 120
 121 /**
 122 * @brief Definition for failed recognition because the speech started too quiet to listen.
 123 * @since_tizen 3.0
 124 */
 125 #define STTE_RESULT_MESSAGE_ERROR_TOO_QUIET     "stt.result.message.error.too.quiet"
 126
 127 /**
 128 * @brief Definition for failed recognition because the speech started too loud to listen.
 129 * @since_tizen 3.0
 130 */
 131 #define STTE_RESULT_MESSAGE_ERROR_TOO_LOUD      "stt.result.message.error.too.loud"
 132
 133 /**
 134 * @brief Definition for failed recognition because the speech started too fast to listen.
 135 * @since_tizen 3.0
 136 */
 137 #define STTE_RESULT_MESSAGE_ERROR_TOO_FAST      "stt.result.message.error.too.fast"
 138
 139
 140 /**
 141 * @brief Called when STT engine provides the time stamp of result to the engine service user.
 142 * @details This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.
 143 * @since_tizen 3.0
 144 *
 145 * @remarks This callback function is called in stte_foreach_result_time_cb() for adding time information.
 146 *       @a user_data must be transferred from stte_foreach_result_time_cb().
 147 *
 148 * @param[in] index The result index
 149 * @param[in] event The token event
 150 * @param[in] text The result text
 151 * @param[in] start_time The time started speaking the result text
 152 * @param[in] end_time The time finished speaking the result text
 153 * @param[in] user_data The user data passed from stte_foreach_result_time_cb()
 154 *
 155 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 156 *
 157 * @pre stte_send_result() should be called.
 158 *
 159 * @see stte_send_result()
 160 * @see stte_foreach_result_time_cb()
 161 */
 162 typedef bool (*stte_result_time_cb)(int index, stte_result_time_event_e event, const char* text,
 163                                 long start_time, long end_time, void* user_data);
 164
 165
 166 /**
 167 * @brief Called when STT engine informs the engine service user about whole supported language list.
 168 * @details This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.
 169 * @since_tizen 3.0
 170 *
 171 * @remarks This callback function is called in stte_foreach_supported_langs_cb() to inform the whole supported language list.
 172 *       @a user_data must be transferred from stte_foreach_supported_langs_cb().
 173 *
 174 * @param[in] language The language is specified as an ISO 3166 alpha-2 two letter country-code
 175 *       followed by ISO 639-1 for the two-letter language code \n
 176 *       For example, "ko_KR" for Korean, "en_US" for American English
 177 * @param[in] user_data The user data passed from stte_foreach_supported_langs_cb()
 178 *
 179 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
 180 *
 181 * @pre stte_foreach_supported_langs_cb() will invoke this callback function.
 182 *
 183 * @see stte_foreach_supported_langs_cb()
 184 */
 185 typedef bool (*stte_supported_language_cb)(const char* language, void* user_data);
 186
 187 /**
 188 * @brief Called when the engine service user initializes STT engine.
 189 * @details This callback function is called by the engine service user to request for STT engine to be started.
 190 * @since_tizen 3.0
 191 *
 192 * @remarks This callback function is mandatory and must be registered using stte_main().
 193 *
 194 * @return 0 on success, otherwise a negative error value
 195 * @retval #STTE_ERROR_NONE Successful
 196 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 197 * @retval #STTE_ERROR_INVALID_STATE Already initialized
 198 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 199 *
 200 * @see stte_deinitialize_cb()
 201 */
 202 typedef int (*stte_initialize_cb)(void);
 203
 204 /**
 205 * @brief Called when the engine service user deinitializes STT engine
 206 * @details This callback function is called by the engine service user to request for STT engine to be deinitialized.
 207 * @since_tizen 3.0
 208 *
 209 * @remarks This callback function is mandatory and must be registered using stte_main().
 210 *       NOTE that the engine may be terminated automatically.
 211 *       When this callback function is invoked, the release of resources is necessary.
 212 *
 213 * @return 0 on success, otherwise a negative error value
 214 * @retval #STTE_ERROR_NONE Successful
 215 * @retval #STTE_ERROR_INVALID_STATE Not initialized
 216 *
 217 * @see stte_initialize_cb()
 218 */
 219 typedef int (*stte_deinitialize_cb)(void);
 220
 221 /**
 222 * @brief Called when the engine service user gets the whole supported language list.
 223 * @since_tizen 3.0
 224 *
 225 * @remarks This callback function is mandatory and must be registered using stte_main().
 226 *       In this function, the engine service user's callback function 'stte_supported_language_cb()' is invoked repeatedly for getting all supported languages, and @a user_data must be transferred to 'stte_supported_language_cb()'.
 227 *       If 'stte_supported_language_cb()' returns @c false, it should be stopped to call 'stte_supported_language_cb()'.
 228 *
 229 * @param[in] callback The callback function
 230 * @param[in] user_data The user data which must be passed to the callback function 'stte_supported_language_cb()'
 231 *
 232 * @return 0 on success, otherwise a negative error value
 233 * @retval #STTE_ERROR_NONE Successful
 234 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 235 * @retval #STTE_ERROR_INVALID_STATE Not initialized
 236 *
 237 * @post This callback function invokes stte_supported_language_cb() repeatedly for getting supported languages.
 238 *
 239 * @see stte_supported_language_cb()
 240 */
 241 typedef int (*stte_foreach_supported_langs_cb)(stte_supported_language_cb callback, void* user_data);
 242
 243 /**
 244 * @brief Called when the engine service user checks whether the corresponding language is valid or not in STT engine.
 245 * @since_tizen 3.0
 246 *
 247 * @remarks This callback function is mandatory and must be registered using stte_main().
 248 *
 249 * @param[in] language The language is specified as an ISO 3166 alpha-2 two letter country-code
 250 *       followed by ISO 639-1 for the two-letter language code \n
 251 *       For example, "ko_KR" for Korean, "en_US" for American English
 252 * @param[out] is_valid A variable for checking whether the corresponding language is valid or not. \n @c true to be valid, @c false to be invalid.
 253 *
 254 * @return 0 on success, otherwise a negative error value
 255 * @retval #STTE_ERROR_NONE Successful
 256 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 257 *
 258 * @see stte_foreach_supported_languages_cb()
 259 */
 260 typedef int (*stte_is_valid_language_cb)(const char* language, bool* is_valid);
 261
 262 /**
 263 * @brief Called when the engine service user checks whether STT engine supports silence detection.
 264 * @since_tizen 3.0
 265 *
 266 * @remarks This callback function is mandatory and must be registered using stte_main().
 267 *
 268 * @return @c true to support silence detection, @c false not to support silence detection
 269 *
 270 * @see stte_set_silence_detection_cb()
 271 */
 272 typedef bool (*stte_support_silence_detection_cb)(void);
 273
 274 /**
 275 * @brief Called when the engine service user checks whether STT engine supports the corresponding recognition type.
 276 * @since_tizen 3.0
 277 *
 278 * @remarks This callback function is mandatory and must be registered using stte_main().
 279 *
 280 * @param[in] type The type for recognition (e.g. #STTE_RECOGNITION_TYPE_FREE)
 281 * @param[out] is_supported A variable for checking whether STT engine supports the corresponding recognition type. \n @c true to support recognition type, @c false not to support recognition type.
 282 *
 283 * @return 0 on success, otherwise a negative error value
 284 * @retval #STTE_ERROR_NONE Successful
 285 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 286 *
 287 */
 288 typedef int (*stte_support_recognition_type_cb)(const char* type, bool* is_supported);
 289
 290 /**
 291 * @brief Called when the engine service user gets the proper recording format of STT engine.
 292 * @since_tizen 3.0
 293 *
 294 * @remarks This callback function is mandatory and must be registered using stte_main().
 295 *       The recording format is used for creating the recorder.
 296 *
 297 * @param[out] types The format used by the recorder.
 298 * @param[out] rate The sample rate used by the recorder.
 299 * @param[out] channels The number of channels used by the recorder.
 300 *
 301 * @return 0 on success, otherwise a negative error value
 302 * @retval #STTE_ERROR_NONE Successful
 303 * @retval #STTE_ERROR_INVALID_STATE Not initialized
 304 */
 305 typedef int (*stte_get_recording_format_cb)(stte_audio_type_e* types, int* rate, int* channels);
 306
 307 /**
 308 * @brief Called when the engine service user sets the silence detection.
 309 * @since_tizen 3.0
 310 *
 311 * @remarks This callback function is mandatory and must be registered using stte_main().
 312 *       If the engine service user sets this option as 'TRUE', STT engine will detect the silence (EPD) and send the callback event about it.
 313 *
 314 * @param[in] is_set A variable for setting the silence detection. \n @c true to detect the silence, @c false not to detect the silence.
 315 *
 316 * @return 0 on success, otherwise a negative error value
 317 * @retval #STTE_ERROR_NONE Successful
 318 * @retval #STTE_ERROR_INVALID_STATE Not initialized
 319 * @retval #STTE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 320 */
 321 typedef int (*stte_set_silence_detection_cb)(bool is_set);
 322
 323 /**
 324 * @brief Called when the engine service user requests for STT engine to check whether the application agreed the usage of STT engine.
 325 * @details This callback function is called when the engine service user requests for STT engine to check the application's agreement about using the engine.
 326 *       According to the need, the engine developer can provide some user interfaces to check the agreement.
 327 * @since_tizen 3.0
 328 *
 329 * @remarks This callback function is mandatory and must be registered using stte_main().
 330 *       If the STT engine developer wants not to check the agreement, the developer has need to return proper values as @a is_agreed in accordance with the intention. \n @c true if the developer regards that every application agreed the usage of the engine, @c false if the developer regards that every application disagreed.
 331 *       NOTE that, however, there may be any legal issue unless the developer checks the agreement. Therefore, we suggest that the engine developers should provide a function to check the agreement.
 332 *
 333 * @param[in] appid The Application ID
 334 * @param[out] is_agreed A variable for checking whether the application agreed to use STT engine or not. \n @c true to agree, @c false to disagree.
 335 *
 336 * @return 0 on success, otherwise a negative error value
 337 * @retval #STTE_ERROR_NONE Successful
 338 * @retval #STTE_ERROR_INVALID_STATE Not initialized
 339 * @retval #STTE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 340 */
 341 typedef int (*stte_check_app_agreed_cb)(const char* appid, bool* is_agreed);
 342
 343 /**
 344 * @brief Called when the engine service user checks whether STT engine needs the application's credential.
 345 * @since_tizen 3.0
 346 *
 347 * @remarks This callback function is mandatory and must be registered using stte_main().
 348 *
 349 * @return @c true if STT engine needs the application's credential, otherwise @c false
 350 */
 351 typedef bool (*stte_need_app_credential_cb)(void);
 352
 353 /**
 354 * @brief Called when the engine service user gets the result time information(stamp).
 355 * @since_tizen 3.0
 356 *
 357 * @remarks This callback function is mandatory and must be registered using stte_main().
 358 *       In this function, the engine service user's callback function 'stte_result_time_cb()' is invoked repeatedly for sending the time information to the engine service user, and @a user_data must be transferred to 'stte_result_time_cb()'.
 359 *       If 'stte_result_time_cb()' returns @c false, it should be stopped to call 'stte_result_time_cb()'.
 360 *       @a time_info is transferred from stte_send_result(). The type of @a time_info is up to the STT engine developer.
 361 *
 362 * @param[in] time_info The time information
 363 * @param[in] callback The callback function
 364 * @param[in] user_data The user data which must be passed to the callback function 'stte_result_time_cb()'
 365 *
 366 * @return 0 on success, otherwise a negative error value
 367 * @retval #STTE_ERROR_NONE Successful
 368 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 369 * @retval #STTE_ERROR_INVALID_STATE Not initialized
 370 *
 371 * @pre stte_send_result() will invoke this function.
 372 * @post This function invokes stte_result_time_cb() repeatedly for getting result time information.
 373 *
 374 * @see stte_result_time_cb()
 375 */
 376 typedef int (*stte_foreach_result_time_cb)(void* time_info, stte_result_time_cb callback, void* user_data);
 377
 378 /**
 379 * @brief Called when the engine service user starts to recognize the recording data.
 380 * @since_tizen 3.0
 381 *
 382 * @remarks This callback function is mandatory and must be registered using stte_main().
 383 *       In this callback function, STT engine must transfer the recognition result and @a user_data to the engine service user using stte_send_result().
 384 *       Also, if STT engine needs the application's credential, it sets the credential granted to the application.
 385 *
 386 * @param[in] language The language is specified as an ISO 3166 alpha-2 two letter country-code
 387 *       followed by ISO 639-1 for the two-letter language code \n
 388 *       For example, "ko_KR" for Korean, "en_US" for American English
 389 * @param[in] type The recognition type. (e.g. #STTE_RECOGNITION_TYPE_FREE)
 390 * @param[in] appid The Application ID
 391 * @param[in] credential The credential granted to the application
 392 * @param[in] user_data The user data to be passed to the callback function.
 393 *
 394 * @return 0 on success, otherwise a negative error value
 395 * @retval #STTE_ERROR_NONE Successful
 396 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 397 * @retval #STTE_ERROR_INVALID_STATE Invalid state
 398 * @retval #STTE_ERROR_INVALID_LANGUAGE Invalid language
 399 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 400 * @retval #STTE_ERROR_NETWORK_DOWN Out of network
 401 *
 402 * @pre The engine is not in recognition processing.
 403 *
 404 * @see stte_set_recording_data_cb()
 405 * @see stte_stop_cb()
 406 * @see stte_cancel_cb()
 407 * @see stte_need_app_credential_cb()
 408 */
 409 typedef int (*stte_start_cb)(const char* language, const char* type, const char* appid, const char* credential, void *user_data);
 410
 411 /**
 412 * @brief Called when the engine service user sets and sends the recording data for speech recognition.
 413 * @details This callback function is called by the engine service user to send the recording data to STT engine.
 414 *       The engine receives the recording data and uses for speech recognition.
 415 * @since_tizen 3.0
 416 *
 417 * @remarks This callback function is mandatory and must be registered using stte_main().
 418 *       Also, this function should be returned immediately after recording data copy.
 419 *
 420 * @param[in] data The recording data
 421 * @param[in] length The length of recording data
 422 *
 423 * @return 0 on success, otherwise a negative error value
 424 * @retval #STTE_ERROR_NONE Successful
 425 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 426 * @retval #STTE_ERROR_INVALID_STATE Invalid state
 427 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 428 *
 429 * @pre stte_start_cb() should succeed.
 430 * @post If the engine supports partial result, stte_send_result() should be invoked.
 431 *
 432 * @see stte_start_cb()
 433 * @see stte_cancel_cb()
 434 * @see stte_stop_cb()
 435 */
 436 typedef int (*stte_set_recording_data_cb)(const void* data, unsigned int length);
 437
 438 /**
 439 * @brief Called when the engine service user stops to recognize the recording data.
 440 * @details This callback function is called by the engine service user to stop recording and to get the recognition result.
 441 * @since_tizen 3.0
 442 *
 443 * @remarks This callback function is mandatory and must be registered using stte_main().
 444 *
 445 * @return 0 on success, otherwise a negative error value
 446 * @retval #STTE_ERROR_NONE Successful
 447 * @retval #STTE_ERROR_INVALID_STATE Invalid state
 448 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 449 * @retval #STTE_ERROR_NETWORK_DOWN Out of network
 450 *
 451 * @pre stte_start_cb() should succeed.
 452 * @post After processing of the engine, stte_send_result() must be called.
 453 *
 454 * @see stte_start_cb()
 455 * @see stte_set_recording_data_cb()
 456 * @see stte_cancel_cb()
 457 * @see stte_send_result()
 458 */
 459 typedef int (*stte_stop_cb)(void);
 460
 461 /**
 462 * @brief Called when the engine service user cancels to recognize the recording data.
 463 * @details This callback function is called by the engine service user to cancel to recognize the recording data.
 464 *       Also, when starting the recorder is failed, this function is called.
 465 * @since_tizen 3.0
 466 *
 467 * @remarks This callback function is mandatory and must be registered using stte_main().
 468 *
 469 * @return 0 on success, otherwise a negative error value.
 470 * @retval #STTE_ERROR_NONE Successful.
 471 * @retval #STTE_ERROR_INVALID_STATE Invalid state.
 472 *
 473 * @pre STT engine is in recognition processing or recording.
 474 *
 475 * @see stte_start_cb()
 476 * @see stte_stop_cb()
 477 */
 478 typedef int (*stte_cancel_cb)(void);
 479
 480 /**
 481 * @brief Called when the engine service user requests the basic information of STT engine.
 482 * @since_tizen 3.0
 483 *
 484 * @remarks This callback function is mandatory and must be registered using stte_main().
 485 *       The allocated @a engine_uuid, @a engine_name, and @a engine_setting will be released internally.
 486 *       In order to upload the engine at Tizen Appstore, both a service app and a ui app are necessary.
 487 *       Therefore, @a engine_setting must be transferred to the engine service user.
 488 *
 489 * @param[out] engine_uuid UUID of engine
 490 * @param[out] engine_name Name of engine
 491 * @param[out] engine_setting The engine setting application(ui app)'s app id
 492 * @param[out] use_network A variable for checking whether the network is used or not
 493 *
 494 * @return 0 on success, otherwise a negative error code on failure
 495 * @retval #STTE_ERROR_NONE Successful
 496 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 497 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 498 *
 499 */
 500 typedef int (*stte_get_info_cb)(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
 501
 502 /**
 503 * @brief Called when STT engine receives the private data from the engine service user.
 504 * @details This callback function is called when the engine service user sends the private data to STT engine.
 505 * @since_tizen 3.0
 506 *
 507 * @remarks This callback function is optional and is registered using stte_set_private_data_set_cb().
 508 *
 509 * @param[in] key The key field of private data.
 510 * @param[in] data The data field of private data.
 511 *
 512 * @return 0 on success, otherwise a negative error value
 513 * @retval #STTE_ERROR_NONE Successful
 514 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 515 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 516 *
 517 * @see stte_private_data_requested_cb()
 518 * @see stte_set_private_data_set_cb()
 519 */
 520 typedef int (*stte_private_data_set_cb)(const char* key, const char* data);
 521
 522 /**
 523 * @brief Called when STT engine provides the engine service user with the private data.
 524 * @details This callback function is called when the engine service user gets the private data from STT engine.
 525 * @since_tizen 3.0
 526 *
 527 * @remarks This callback function is optional and is registered using stte_set_private_data_requested_cb().
 528 *
 529 * @param[out] key The key field of private data.
 530 * @param[out] data The data field of private data.
 531 *
 532 * @return 0 on success, otherwise a negative error value
 533 * @retval #STTE_ERROR_NONE Successful
 534 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 535 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 536 *
 537 * @see stte_private_data_set_cb()
 538 * @see stte_set_private_data_requested_cb()
 539 */
 540 typedef int (*stte_private_data_requested_cb)(const char* key, char** data);
 541
 542 /**
 543 * @brief A structure for the STT engine functions.
 544 * @details This structure contains essential callback functions for operating STT engine.
 545 * @since_tizen 3.0
 546 *
 547 * @remarks These functions are mandatory for operating STT engine. Therefore, all functions MUST be implemented.
 548 */
 549 typedef struct {
 550         int version;                                                            /**< The version of the structure 'stte_request_callback_s' */
 551         stte_get_info_cb                        get_info;                       /**< Called when the engine service user requests the basic information of STT engine */
 552
 553         stte_initialize_cb                      initialize;                     /**< Called when the engine service user initializes STT engine */
 554         stte_deinitialize_cb                    deinitialize;                   /**< Called when the engine service user deinitializes STT engine */
 555
 556         stte_foreach_supported_langs_cb         foreach_langs;                  /**< Called when the engine service user gets the whole supported language list */
 557         stte_is_valid_language_cb               is_valid_lang;                  /**< Called when the engine service user checks whether the corresponding language is valid or not*/
 558         stte_support_silence_detection_cb       support_silence;                /**< Called when the engine service user checks whether STT engine supports silence detection*/
 559         stte_support_recognition_type_cb        support_recognition_type;       /**< Called when the engine service user checks whether STT engine supports the corresponding recognition type */
 560         stte_get_recording_format_cb            get_audio_format;               /**< Called when the engine service user gets the proper recording format of STT engine */
 561         stte_foreach_result_time_cb             foreach_result_time;            /**< Called when the engine service user gets the result time information(stamp) */
 562
 563         stte_set_silence_detection_cb           set_silence_detection;          /**< Called when the engine service user sets the silence detection */
 564
 565         stte_start_cb                           start;                          /**< Called when the engine service user starts to recognize the recording data */
 566         stte_set_recording_data_cb              set_recording;                  /**< Called when the engine service user sets and sends the recording data for speech recognition */
 567         stte_stop_cb                            stop;                           /**< Called when the engine service user stops to recognize the recording data */
 568         stte_cancel_cb                          cancel;                         /**< Called when the engine service user cancels to recognize the recording data */
 569
 570         stte_check_app_agreed_cb                check_app_agreed;               /**< Called when the engine service user requests for STT engine to check whether the application agreed the usage of STT engine */
 571         stte_need_app_credential_cb             need_app_credential;            /**< Called when the engine service user checks whether STT engine needs the application's credential */
 572 } stte_request_callback_s;
 573
 574 /**
 575 * @brief Main function for Speech-To-Text (STT) engine.
 576 * @details This function is the main function for operating STT engine.
 577 * @since_tizen 3.0
 578 *
 579 * @privlevel public
 580 * @privilege %http://tizen.org/privilege/recorder
 581 *
 582 * @remarks The service_app_main() should be used for working the engine after this function.
 583 *
 584 * @param[in] argc The argument count(original)
 585 * @param[in] argv The argument(original)
 586 * @param[in] callback The structure of engine request callback function
 587 *
 588 * @return This function returns zero on success, or negative with error code on failure
 589 * @retval #STTE_ERROR_NONE Successful
 590 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 591 * @retval #STTE_ERROR_PERMISSION_DENIED Permission denied
 592 * @retval #STTE_ERROR_NOT_SUPPORTED Not supported
 593 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 594 *
 595 * @see stte_request_callback_s
 596 *
 597 * @code
 598 #include <stte.h>
 599
 600 // Required callback functions - MUST BE IMPLEMENTED
 601 static int sttengine_get_info_cb(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
 602 static int sttengine_initialize_cb(void);
 603 static int sttengine_deinitialize_cb(void);
 604 static int sttengine_is_valid_language_cb(const char* language, bool* is_valid);
 605 static int sttengine_foreach_supported_langs_cb(stte_supported_language_cb callback, void* user_data);
 606 static bool sttengine_support_silence_detection_cb(void);
 607 static int sttengine_set_silence_detection_cb(bool is_set);
 608 static int sttengine_support_recognition_type_cb(const char* type, bool* is_supported);
 609 static int sttengine_get_recording_format_cb(stte_audio_type_e* types, int* rate, int* channels);
 610 static int sttengine_set_recording_data_cb(const void* data, unsigned int length);
 611 static int sttengine_foreach_result_time_cb(void* time_info, stte_result_time_cb callback, void* user_data);
 612 static int sttengine_start_cb(const char* language, const char* type, const char* appid, const char* credential, void *user_data);
 613 static int sttengine_stop_cb(void);
 614 static int sttengine_cancel_cb(void);
 615 static int sttengine_check_app_agreed_cb(const char* appid, bool* is_agreed);
 616 static bool sttengine_need_app_credential_cb(void);
 617
 618 // Optional callback function
 619 static int sttengine_private_data_set_cb(const char* key, const char* data);
 620
 621 int main(int argc, char* argv[])
 622 {
 623         // 1. Create a structure 'stte_request_callback_s'
 624         stte_request_callback_s engine_callback = { 0, };
 625
 626         engine_callback.size = sizeof(stte_request_callback_s);
 627         engine_callback.version = 1;
 628         engine_callback.get_info = sttengine_get_info_cb;
 629
 630         engine_callback.initialize = sttengine_initialize_cb;
 631         engine_callback.deinitialize = sttengine_deinitialize_cb;
 632
 633         engine_callback.foreach_langs = sttengine_foreach_supported_langs_cb;
 634         engine_callback.is_valid_lang = sttengine_is_valid_language_cb;
 635         engine_callback.support_silence = sttengine_support_silence_detection_cb;
 636         engine_callback.support_recognition_type = sttengine_support_recognition_type_cb;
 637
 638         engine_callback.get_audio_format = sttengine_get_recording_format_cb;
 639         engine_callback.foreach_result_time = sttengine_foreach_result_time_cb;
 640
 641         engine_callback.set_silence_detection = sttengine_set_silence_detection_cb;
 642
 643         engine_callback.start = sttengine_start_cb;
 644         engine_callback.set_recording = sttengine_set_recording_data_cb;
 645         engine_callback.stop = sttengine_stop_cb;
 646         engine_callback.cancel = sttengine_cancel_cb;
 647
 648         engine_callback.check_app_agreed = sttengine_check_app_agreed_cb;
 649         engine_callback.need_app_credential = sttengine_need_app_credential_cb;
 650
 651         // 2. Run 'stte_main()'
 652         if (0 != stte_main(argc, argv, &engine_callback)) {
 653                 return -1;
 654         }
 655
 656         // Optional
 657         stte_set_private_data_set_cb(sttengine_private_data_set_cb);
 658
 659         // 3. Set event callbacks for service app and Run 'service_app_main()'
 660         char ad[50] = { 0, };
 661
 662         service_app_lifecycle_callback_s event_callback;
 663         app_event_handler_h handlers[5] = { NULL, };
 664
 665         event_callback.create = service_app_create;
 666         event_callback.terminate = service_app_terminate;
 667         event_callback.app_control = service_app_control;
 668
 669         service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, service_app_low_battery, &ad);
 670         service_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, service_app_low_memory, &ad);
 671         service_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, service_app_lang_changed, &ad);
 672         service_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, service_app_region_changed, &ad);
 673
 674         return service_app_main(argc, argv, &event_callback, ad);
 675 }
 676
 677 * @endcode
 678 */
 679 int stte_main(int argc, char** argv, stte_request_callback_s *callback);
 680
 681
 682 /**
 683 * @brief Sends the recognition result to the engine service user.
 684 * @since_tizen 3.0
 685 *
 686 * @remarks This API is used in stte_set_recording_data_cb() and stte_stop_cb(), when STT engine sends the recognition result to the engine service user.
 687 *       This function is called in the following situations; 1) after stte_stop_cb() is called, 2) the end point of speech is detected from recording, or 3) partial result is occurred.
 688 *       The recognition result and @a user_data must be transferred to the engine service user through this function.
 689 *       Also, @a time_info must be transferred to stte_foreach_result_time_cb(). The type of @a time_info is up to the STT engine developer.
 690 *
 691 * @param[in] event The result event
 692 * @param[in] type The recognition type (e.g. #STTE_RECOGNITION_TYPE_FREE, #STTE_RECOGNITION_TYPE_FREE_PARTIAL)
 693 * @param[in] result Result texts
 694 * @param[in] result_count Result text count
 695 * @param[in] msg Engine message (e.g. #STTE_RESULT_MESSAGE_NONE, #STTE_RESULT_MESSAGE_ERROR_TOO_SHORT)
 696 * @param[in] time_info The time information
 697 * @param[in] user_data  The user data passed from stte_start_cb()
 698 *
 699 * @return 0 on success, otherwise a negative error value
 700 * @retval #STTE_ERROR_NONE Successful
 701 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 702 * @retval #STTE_ERROR_PERMISSION_DENIED Permission denied
 703 * @retval #STTE_ERROR_NOT_SUPPORTED Not supported
 704 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 705 *
 706 * @pre The stte_main() function should be invoked before this function is called.
 707 *       stte_stop_cb() will invoke this function.
 708 * @post This function invokes stte_foreach_result_time_cb().
 709 *
 710 * @see stte_start_cb()
 711 * @see stte_set_recording_data_cb()
 712 * @see stte_stop_cb()
 713 * @see stte_foreach_result_time_cb()
 714 */
 715 int stte_send_result(stte_result_event_e event, const char* type, const char** result, int result_count,
 716                                 const char* msg, void* time_info, void* user_data);
 717
 718
 719 /**
 720 * @brief Sends the error to the engine service user.
 721 * @details The following error codes can be delivered.\n
 722 *       #STTE_ERROR_NONE,\n
 723 *       #STTE_ERROR_OUT_OF_MEMORY,\n
 724 *       #STTE_ERROR_IO_ERROR,\n
 725 *       #STTE_ERROR_INVALID_PARAMETER,\n
 726 *       #STTE_ERROR_NETWORK_DOWN,\n
 727 *       #STTE_ERROR_INVALID_STATE,\n
 728 *       #STTE_ERROR_INVALID_LANGUAGE,\n
 729 *       #STTE_ERROR_OPERATION_FAILED,\n
 730 *       #STTE_ERROR_NOT_SUPPORTED_FEATURE,\n
 731 *       #STTE_ERROR_NOT_SUPPORTED,\n
 732 *       #STTE_ERROR_PERMISSION_DENIED,\n
 733 *       #STTE_ERROR_RECORDING_TIMED_OUT.\n
 734 *
 735 * @since_tizen 3.0
 736 *
 737 * @param[in] error The error reason
 738 * @param[in] msg The error message
 739 *
 740 * @return 0 on success, otherwise a negative error value
 741 * @retval #STTE_ERROR_NONE Successful
 742 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 743 * @retval #STTE_ERROR_PERMISSION_DENIED Permission denied
 744 * @retval #STTE_ERROR_NOT_SUPPORTED Not supported
 745 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 746 *
 747 * @pre The stte_main() function should be invoked before this function is called.
 748 */
 749 int stte_send_error(stte_error_e error, const char* msg);
 750
 751 /**
 752 * @brief Sends the speech status to the engine service user when STT engine notifies the change of the speech status.
 753 * @since_tizen 3.0
 754 *
 755 * @remarks This API is invoked when STT engine wants to notify the change of the speech status anytime.
 756 *       NOTE that this API can be invoked for recognizing the speech.
 757 *
 758 * @param[in] status The status of speech (e.g. STTE_SPEECH_STATUS_START_POINT_DETECTED or STTE_SPEECH_STATUS_END_POINT_DETECTED)
 759 * @param[in] user_data The user data passed from the start function.
 760 *
 761 * @return 0 on success, otherwise a negative error value
 762 * @retval #STTE_ERROR_NONE Successful
 763 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 764 * @retval #STTE_ERROR_PERMISSION_DENIED Permission denied
 765 * @retval #STTE_ERROR_NOT_SUPPORTED Not supported
 766 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 767 *
 768 * @pre The stte_main() function should be invoked before this function is called.
 769 *       stte_start_cb() and stte_set_recording_data_cb() will invoke this function.
 770 *
 771 * @see stte_start_cb()
 772 * @see stte_set_recording_data_cb()
 773 */
 774 int stte_send_speech_status(stte_speech_status_e status, void* user_data);
 775
 776
 777 /**
 778 * @brief Sets a callback function for setting the private data.
 779 * @since_tizen 3.0
 780 *
 781 * @privlevel public
 782 * @privilege %http://tizen.org/privilege/recorder
 783 *
 784 * @remarks The stte_private_data_set_cb() function is called when the engine service user sends the private data.
 785 *
 786 * @param[in] callback_func stte_private_data_set event callback function
 787 *
 788 * @return 0 on success, otherwise a negative error value
 789 * @retval #STTE_ERROR_NONE Successful
 790 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 791 * @retval #STTE_ERROR_PERMISSION_DENIED Permission denied
 792 * @retval #STTE_ERROR_NOT_SUPPORTED Not supported
 793 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 794 *
 795 * @pre The stte_main() function should be invoked before this function is called.
 796 *
 797 * @see stte_private_data_set_cb()
 798 */
 799 int stte_set_private_data_set_cb(stte_private_data_set_cb callback_func);
 800
 801 /**
 802 * @brief Sets a callback function for requesting the private data.
 803 * @since_tizen 3.0
 804 *
 805 * @privlevel public
 806 * @privilege %http://tizen.org/privilege/recorder
 807 *
 808 * @remarks The stte_private_data_requested_cb() function is called when the engine service user gets the private data from STT engine.
 809 *
 810 * @param[in] callback_func stte_private_data_requested event callback function
 811 *
 812 * @return 0 on success, otherwise a negative error value
 813 * @retval #STTE_ERROR_NONE Successful
 814 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
 815 * @retval #STTE_ERROR_PERMISSION_DENIED Permission denied
 816 * @retval #STTE_ERROR_NOT_SUPPORTED Not supported
 817 * @retval #STTE_ERROR_OPERATION_FAILED Operation failure
 818 *
 819 * @pre The stte_main() function should be invoked before this function is called.
 820 *
 821 * @see stte_private_data_requested_cb()
 822 */
 823 int stte_set_private_data_requested_cb(stte_private_data_requested_cb callback_func);
 824
 825
 826
 827 #ifdef __cplusplus
 828 }
 829 #endif
 830
 831 /**
 832  * @}@}
 833  */
 834
 835 #endif /* __STT_ENGINE_MAIN_H__ */