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.
14 #ifndef __STT_ENGINE_MAIN_H__
15 #define __STT_ENGINE_MAIN_H__
20 * @addtogroup CAPI_UIX_STTE_MODULE
29 * @brief Enumerations for error codes.
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 */
48 * @brief Enumerations for audio type.
52 STTE_AUDIO_TYPE_PCM_S16_LE = 0, /**< Signed 16bit audio type, Little endian */
53 STTE_AUDIO_TYPE_PCM_U8 /**< Unsigned 8bit audio type */
57 * @brief Enumerations for callback event.
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;
67 * @brief Enumerations for result time callback event.
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;
77 * @brief Enumerations for speech status.
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;
86 * @brief Definition for free form dictation and default type.
89 #define STTE_RECOGNITION_TYPE_FREE "stt.recognition.type.FREE"
92 * @brief Definition for free form dictation continuously.
95 #define STTE_RECOGNITION_TYPE_FREE_PARTIAL "stt.recognition.type.FREE.PARTIAL"
98 * @brief Definition for None message.
101 #define STTE_RESULT_MESSAGE_NONE "stt.result.message.none"
104 * @brief Definition for failed recognition because the speech started too soon.
107 #define STTE_RESULT_MESSAGE_ERROR_TOO_SOON "stt.result.message.error.too.soon"
110 * @brief Definition for failed recognition because the speech started too short.
113 #define STTE_RESULT_MESSAGE_ERROR_TOO_SHORT "stt.result.message.error.too.short"
116 * @brief Definition for failed recognition because the speech started too long.
119 #define STTE_RESULT_MESSAGE_ERROR_TOO_LONG "stt.result.message.error.too.long"
122 * @brief Definition for failed recognition because the speech started too quiet to listen.
125 #define STTE_RESULT_MESSAGE_ERROR_TOO_QUIET "stt.result.message.error.too.quiet"
128 * @brief Definition for failed recognition because the speech started too loud to listen.
131 #define STTE_RESULT_MESSAGE_ERROR_TOO_LOUD "stt.result.message.error.too.loud"
134 * @brief Definition for failed recognition because the speech started too fast to listen.
137 #define STTE_RESULT_MESSAGE_ERROR_TOO_FAST "stt.result.message.error.too.fast"
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.
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().
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()
155 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
157 * @pre stte_send_result() should be called.
159 * @see stte_send_result()
160 * @see stte_foreach_result_time_cb()
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);
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.
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().
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()
179 * @return @c true to continue with the next iteration of the loop \n @c false to break out of the loop
181 * @pre stte_foreach_supported_langs_cb() will invoke this callback function.
183 * @see stte_foreach_supported_langs_cb()
185 typedef bool (*stte_supported_language_cb)(const char* language, void* user_data);
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.
192 * @remarks This callback function is mandatory and must be registered using stte_main().
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
200 * @see stte_deinitialize_cb()
202 typedef int (*stte_initialize_cb)(void);
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.
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.
213 * @return 0 on success, otherwise a negative error value
214 * @retval #STTE_ERROR_NONE Successful
215 * @retval #STTE_ERROR_INVALID_STATE Not initialized
217 * @see stte_initialize_cb()
219 typedef int (*stte_deinitialize_cb)(void);
222 * @brief Called when the engine service user gets the whole supported language list.
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()'.
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()'
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
237 * @post This callback function invokes stte_supported_language_cb() repeatedly for getting supported languages.
239 * @see stte_supported_language_cb()
241 typedef int (*stte_foreach_supported_langs_cb)(stte_supported_language_cb callback, void* user_data);
244 * @brief Called when the engine service user checks whether the corresponding language is valid or not in STT engine.
247 * @remarks This callback function is mandatory and must be registered using stte_main().
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.
254 * @return 0 on success, otherwise a negative error value
255 * @retval #STTE_ERROR_NONE Successful
256 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
258 * @see stte_foreach_supported_languages_cb()
260 typedef int (*stte_is_valid_language_cb)(const char* language, bool* is_valid);
263 * @brief Called when the engine service user checks whether STT engine supports silence detection.
266 * @remarks This callback function is mandatory and must be registered using stte_main().
268 * @return @c true to support silence detection, @c false not to support silence detection
270 * @see stte_set_silence_detection_cb()
272 typedef bool (*stte_support_silence_detection_cb)(void);
275 * @brief Called when the engine service user checks whether STT engine supports the corresponding recognition type.
278 * @remarks This callback function is mandatory and must be registered using stte_main().
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.
283 * @return 0 on success, otherwise a negative error value
284 * @retval #STTE_ERROR_NONE Successful
285 * @retval #STTE_ERROR_INVALID_PARAMETER Invalid parameter
288 typedef int (*stte_support_recognition_type_cb)(const char* type, bool* is_supported);
291 * @brief Called when the engine service user gets the proper recording format of STT engine.
294 * @remarks This callback function is mandatory and must be registered using stte_main().
295 * The recording format is used for creating the recorder.
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.
301 * @return 0 on success, otherwise a negative error value
302 * @retval #STTE_ERROR_NONE Successful
303 * @retval #STTE_ERROR_INVALID_STATE Not initialized
305 typedef int (*stte_get_recording_format_cb)(stte_audio_type_e* types, int* rate, int* channels);
308 * @brief Called when the engine service user sets the silence detection.
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.
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.
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
321 typedef int (*stte_set_silence_detection_cb)(bool is_set);
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.
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.
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.
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
341 typedef int (*stte_check_app_agreed_cb)(const char* appid, bool* is_agreed);
344 * @brief Called when the engine service user checks whether STT engine needs the application's credential.
347 * @remarks This callback function is mandatory and must be registered using stte_main().
349 * @return @c true if STT engine needs the application's credential, otherwise @c false
351 typedef bool (*stte_need_app_credential_cb)(void);
354 * @brief Called when the engine service user gets the result time information(stamp).
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.
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()'
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
371 * @pre stte_send_result() will invoke this function.
372 * @post This function invokes stte_result_time_cb() repeatedly for getting result time information.
374 * @see stte_result_time_cb()
376 typedef int (*stte_foreach_result_time_cb)(void* time_info, stte_result_time_cb callback, void* user_data);
379 * @brief Called when the engine service user starts to recognize the recording data.
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.
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.
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
402 * @pre The engine is not in recognition processing.
404 * @see stte_set_recording_data_cb()
405 * @see stte_stop_cb()
406 * @see stte_cancel_cb()
407 * @see stte_need_app_credential_cb()
409 typedef int (*stte_start_cb)(const char* language, const char* type, const char* appid, const char* credential, void *user_data);
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.
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.
420 * @param[in] data The recording data
421 * @param[in] length The length of recording data
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
429 * @pre stte_start_cb() should succeed.
430 * @post If the engine supports partial result, stte_send_result() should be invoked.
432 * @see stte_start_cb()
433 * @see stte_cancel_cb()
434 * @see stte_stop_cb()
436 typedef int (*stte_set_recording_data_cb)(const void* data, unsigned int length);
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.
443 * @remarks This callback function is mandatory and must be registered using stte_main().
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
451 * @pre stte_start_cb() should succeed.
452 * @post After processing of the engine, stte_send_result() must be called.
454 * @see stte_start_cb()
455 * @see stte_set_recording_data_cb()
456 * @see stte_cancel_cb()
457 * @see stte_send_result()
459 typedef int (*stte_stop_cb)(void);
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.
467 * @remarks This callback function is mandatory and must be registered using stte_main().
469 * @return 0 on success, otherwise a negative error value.
470 * @retval #STTE_ERROR_NONE Successful.
471 * @retval #STTE_ERROR_INVALID_STATE Invalid state.
473 * @pre STT engine is in recognition processing or recording.
475 * @see stte_start_cb()
476 * @see stte_stop_cb()
478 typedef int (*stte_cancel_cb)(void);
481 * @brief Called when the engine service user requests the basic information of STT engine.
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.
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
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
500 typedef int (*stte_get_info_cb)(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
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.
507 * @remarks This callback function is optional and is registered using stte_set_private_data_set_cb().
509 * @param[in] key The key field of private data.
510 * @param[in] data The data field of private data.
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
517 * @see stte_private_data_requested_cb()
518 * @see stte_set_private_data_set_cb()
520 typedef int (*stte_private_data_set_cb)(const char* key, const char* data);
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.
527 * @remarks This callback function is optional and is registered using stte_set_private_data_requested_cb().
529 * @param[out] key The key field of private data.
530 * @param[out] data The data field of private data.
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
537 * @see stte_private_data_set_cb()
538 * @see stte_set_private_data_requested_cb()
540 typedef int (*stte_private_data_requested_cb)(const char* key, char** data);
543 * @brief A structure for the STT engine functions.
544 * @details This structure contains essential callback functions for operating STT engine.
547 * @remarks These functions are mandatory for operating STT engine. Therefore, all functions MUST be implemented.
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 */
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 */
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) */
563 stte_set_silence_detection_cb set_silence_detection; /**< Called when the engine service user sets the silence detection */
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 */
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;
575 * @brief Main function for Speech-To-Text (STT) engine.
576 * @details This function is the main function for operating STT engine.
580 * @privilege %http://tizen.org/privilege/recorder
582 * @remarks The service_app_main() should be used for working the engine after this function.
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
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
595 * @see stte_request_callback_s
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);
618 // Optional callback function
619 static int sttengine_private_data_set_cb(const char* key, const char* data);
621 int main(int argc, char* argv[])
623 // 1. Create a structure 'stte_request_callback_s'
624 stte_request_callback_s engine_callback = { 0, };
626 engine_callback.size = sizeof(stte_request_callback_s);
627 engine_callback.version = 1;
628 engine_callback.get_info = sttengine_get_info_cb;
630 engine_callback.initialize = sttengine_initialize_cb;
631 engine_callback.deinitialize = sttengine_deinitialize_cb;
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;
638 engine_callback.get_audio_format = sttengine_get_recording_format_cb;
639 engine_callback.foreach_result_time = sttengine_foreach_result_time_cb;
641 engine_callback.set_silence_detection = sttengine_set_silence_detection_cb;
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;
648 engine_callback.check_app_agreed = sttengine_check_app_agreed_cb;
649 engine_callback.need_app_credential = sttengine_need_app_credential_cb;
651 // 2. Run 'stte_main()'
652 if (0 != stte_main(argc, argv, &engine_callback)) {
657 stte_set_private_data_set_cb(sttengine_private_data_set_cb);
659 // 3. Set event callbacks for service app and Run 'service_app_main()'
660 char ad[50] = { 0, };
662 service_app_lifecycle_callback_s event_callback;
663 app_event_handler_h handlers[5] = { NULL, };
665 event_callback.create = service_app_create;
666 event_callback.terminate = service_app_terminate;
667 event_callback.app_control = service_app_control;
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);
674 return service_app_main(argc, argv, &event_callback, ad);
679 int stte_main(int argc, char** argv, stte_request_callback_s *callback);
683 * @brief Sends the recognition result to the engine service user.
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.
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()
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
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().
710 * @see stte_start_cb()
711 * @see stte_set_recording_data_cb()
712 * @see stte_stop_cb()
713 * @see stte_foreach_result_time_cb()
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);
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
737 * @param[in] error The error reason
738 * @param[in] msg The error message
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
747 * @pre The stte_main() function should be invoked before this function is called.
749 int stte_send_error(stte_error_e error, const char* msg);
752 * @brief Sends the speech status to the engine service user when STT engine notifies the change of the speech status.
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.
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.
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
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.
771 * @see stte_start_cb()
772 * @see stte_set_recording_data_cb()
774 int stte_send_speech_status(stte_speech_status_e status, void* user_data);
778 * @brief Sets a callback function for setting the private data.
782 * @privilege %http://tizen.org/privilege/recorder
784 * @remarks The stte_private_data_set_cb() function is called when the engine service user sends the private data.
786 * @param[in] callback_func stte_private_data_set event callback function
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
795 * @pre The stte_main() function should be invoked before this function is called.
797 * @see stte_private_data_set_cb()
799 int stte_set_private_data_set_cb(stte_private_data_set_cb callback_func);
802 * @brief Sets a callback function for requesting the private data.
806 * @privilege %http://tizen.org/privilege/recorder
808 * @remarks The stte_private_data_requested_cb() function is called when the engine service user gets the private data from STT engine.
810 * @param[in] callback_func stte_private_data_requested event callback function
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
819 * @pre The stte_main() function should be invoked before this function is called.
821 * @see stte_private_data_requested_cb()
823 int stte_set_private_data_requested_cb(stte_private_data_requested_cb callback_func);
835 #endif /* __STT_ENGINE_MAIN_H__ */