2 * Copyright (c) 2011-2016 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the License);
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an AS IS BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __TIZEN_UIX_STT_ENGINE_DOC_H__
19 #define __TIZEN_UIX_STT_ENGINE_DOC_H__
22 * @ingroup CAPI_UIX_FRAMEWORK
23 * @defgroup CAPI_UIX_STTE_MODULE STT Engine
24 * @brief The @ref CAPI_UIX_STTE_MODULE APIs provide functions to operate Speech-To-Text Engine.
27 * @section CAPI_UIX_STTE_MODULE_HEADER Required Header
31 * @section CAPI_UIX_STTE_MODULE_OVERVIEW Overview
32 * Speech-To-Text Engine (below STTE) is an engine for recording speech and resulting in texts of speech recognition.
33 * Using the @ref CAPI_UIX_STTE_MODULE APIs, STTE developers can provide STTE service users, who want to apply STTE, with functions necessary to operate the engine.
34 * According to the indispensability of STTE services, there are two ways to provide them to the users. <br>
36 * <b>A. Required STTE services</b> <br>
37 * These services are indispensable to operate STTE. Therefore, the STTE developers MUST implement callback functions corresponding to the required STTE services.
38 * The following is a list of the callback functions. <br>
43 * <th>DESCRIPTION</th>
46 * <td>stte_get_info_cb()</td>
47 * <td>Called when the engine service user requests the basic information of STT engine.</td>
50 * <td>stte_initialize_cb()</td>
51 * <td>Called when the engine service user initializes STT engine.</td>
54 * <td>stte_deinitialize_cb()</td>
55 * <td>Called when the engine service user deinitializes STT engine.</td>
58 * <td>stte_is_valid_language_cb()</td>
59 * <td>Called when the engine service user checks whether the corresponding language is valid or not.</td>
62 * <td>stte_foreach_supported_langs_cb()</td>
63 * <td>Called when the engine service user gets the whole supported language list.</td>
66 * <td>stte_support_silence_detection_cb()</td>
67 * <td>Called when the engine service user checks whether STT engine supports silence detection.</td>
70 * <td>stte_set_silence_detection_cb()</td>
71 * <td>Called when the engine service user sets the silence detection.</td>
74 * <td>stte_support_recognition_type_cb()</td>
75 * <td>Called when the engine service user checks whether STT engine supports the corresponding recognition type.</td>
78 * <td>stte_get_recording_format_cb()</td>
79 * <td>Called when the engine service user gets the proper recording format of STT engine.</td>
82 * <td>stte_set_recording_data_cb()</td>
83 * <td>Called when the engine service user sets and sends the recording data for speech recognition.</td>
86 * <td>stte_foreach_result_time_cb()</td>
87 * <td>Called when the engine service user gets the result time information(stamp).</td>
90 * <td>stte_start_cb()</td>
91 * <td>Called when the engine service user starts to recognize the recording data.</td>
94 * <td>stte_stop_cb()</td>
95 * <td>Called when the engine service user stops to recognize the recording data.</td>
98 * <td>stte_cancel_cb()</td>
99 * <td>Called when the engine service user cancels to recognize the recording data.</td>
102 * <td>stte_check_app_agreed_cb()</td>
103 * <td>Called when the engine service user requests for STT engine to check whether the application agreed the usage of STT engine.</td>
106 * <td>stte_need_app_credential_cb()</td>
107 * <td>Called when the engine service user checks whether STT engine needs the application's credential.</td>
111 * The STTE developers can register the above callback functions at a time with using a structure 'stte_request_callback_s' and an API 'stte_main()'.
112 * To operate STTE, the following steps should be used: <br>
113 * 1. Create a structure 'stte_request_callback_s'. <br>
114 * 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction.
115 * If the callback function returns an unstated value, STT framework will handle it as #STTE_ERROR_OPERATION_FAILED.)<br>
116 * 3. Register callback functions using 'stte_main()'. (The registered callback functions will be called when the STTE service users request the STTE services.) <br>
117 * 4. Use 'service_app_main()' for working STTE. <br>
119 * <b>B. Optional STTE services</b> <br>
120 * Unlike the required STTE services, these services are optional to operate STTE. The followings are optional STTE services. <br>
121 * - receive/provide the private data <br>
123 * If the STTE developers want to provide the above services, use the following APIs and implement the corresponding callback functions: <br>
127 * <th>DESCRIPTION</th>
128 * <th>CORRESPONDING CALLBACK</th>
131 * <td>stte_set_private_data_set_cb()</td>
132 * <td>Sets a callback function for receiving the private data from the engine service user.</td>
133 * <td>stte_private_data_set_cb()</td>
136 * <td>stte_set_private_data_requested_cb()</td>
137 * <td>Sets a callback function for providing the private data to the engine service user.</td>
138 * <td>stte_private_data_requested_cb()</td>
143 * Using the above APIs, the STTE developers can register the optional callback functions respectively.
144 * (For normal operation, put those APIs before 'service_app_main()' starts.)
146 * Unlike callback functions, the following APIs are functions for getting and sending data. The STTE developers can use these APIs when they implement STTE services: <br>
150 * <th>DESCRIPTION</th>
153 * <td>stte_send_result()</td>
154 * <td>Sends the recognition result to the engine service user.</td>
157 * <td>stte_send_error()</td>
158 * <td>Sends the error to the engine service user.</td>
161 * <td>stte_send_speech_status()</td>
162 * <td>Sends the speech status to the engine service user when STT engine notifies the change of the speech status.</td>
167 * @section CAPI_UIX_STTE_MODULE_FEATURE Related Features
168 * This API is related with the following features:<br>
169 * - http://tizen.org/feature/speech.recognition<br>
170 * - http://tizen.org/feature/microphone<br>
172 * It is recommended to design feature related codes in your application for reliability.<br>
173 * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.<br>
174 * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.<br>
175 * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tools/native-tools/manifest-text-editor#feature"><b>Feature Element</b>.</a>
179 #endif /* __TIZEN_UIX_STT_ENGINE_DOC_H__ */