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__
23 * @ingroup CAPI_UIX_FRAMEWORK
24 * @defgroup CAPI_UIX_STTE_MODULE STT Engine
25 * @brief The @ref CAPI_UIX_STTE_MODULE APIs provide functions to operate Speech-To-Text Engine.
26 * @section CAPI_UIX_STTE_MODULE_HEADER Required Header
29 * @section CAPI_UIX_STTE_MODULE_OVERVIEW Overview
30 * Speech-To-Text Engine (below STTE) is an engine for recording speech and resulting in texts of speech recognition.
31 * 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.
32 * According to the indispensability of STTE services, there are two ways to provide them to the users. <br>
33 * <b>A. Required STTE services</b> <br>
34 * These services are indispensable to operate STTE. Therefore, the STTE developers MUST implement callback functions corresponding to the required STTE services.
35 * The following is a list of the callback functions. <br>
39 * <th>DESCRIPTION</th>
42 * <td>stte_get_info_cb()</td>
43 * <td>Called when the engine service user requests the basic information of STT engine.</td>
46 * <td>stte_initialize_cb()</td>
47 * <td>Called when the engine service user initializes STT engine.</td>
50 * <td>stte_deinitialize_cb()</td>
51 * <td>Called when the engine service user deinitializes STT engine.</td>
54 * <td>stte_is_valid_language_cb()</td>
55 * <td>Called when the engine service user checks whether the corresponding language is valid or not.</td>
58 * <td>stte_foreach_supported_langs_cb()</td>
59 * <td>Called when the engine service user gets the whole supported language list.</td>
62 * <td>stte_support_silence_detection_cb()</td>
63 * <td>Called when the engine service user checks whether STT engine supports silence detection.</td>
66 * <td>stte_set_silence_detection_cb()</td>
67 * <td>Called when the engine service user sets the silence detection.</td>
70 * <td>stte_support_recognition_type_cb()</td>
71 * <td>Called when the engine service user checks whether STT engine supports the corresponding recognition type.</td>
74 * <td>stte_get_recording_format_cb()</td>
75 * <td>Called when the engine service user gets the proper recording format of STT engine.</td>
78 * <td>stte_set_recording_data_cb()</td>
79 * <td>Called when the engine service user sets and sends the recording data for speech recognition.</td>
82 * <td>stte_foreach_result_time_cb()</td>
83 * <td>Called when the engine service user gets the result time information(stamp).</td>
86 * <td>stte_start_cb()</td>
87 * <td>Called when the engine service user starts to recognize the recording data.</td>
90 * <td>stte_stop_cb()</td>
91 * <td>Called when the engine service user stops to recognize the recording data.</td>
94 * <td>stte_cancel_cb()</td>
95 * <td>Called when the engine service user cancels to recognize the recording data.</td>
98 * <td>stte_check_app_agreed_cb()</td>
99 * <td>Called when the engine service user requests for STT engine to check whether the application agreed the usage of STT engine.</td>
102 * <td>stte_need_app_credential_cb()</td>
103 * <td>Called when the engine service user checks whether STT engine needs the application's credential.</td>
106 * 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()'.
107 * To operate STTE, the following steps should be used: <br>
108 * 1. Create a structure 'stte_request_callback_s'. <br>
109 * 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction.
110 * If the callback function returns an unstated value, STT framework will handle it as #STTE_ERROR_OPERATION_FAILED.)<br>
111 * 3. Register callback functions using 'stte_main()'. (The registered callback functions will be called when the STTE service users request the STTE services.) <br>
112 * 4. Use 'service_app_main()' for working STTE. <br>
113 * <b>B. Optional STTE services</b> <br>
114 * Unlike the required STTE services, these services are optional to operate STTE. The followings are optional STTE services. <br>
115 * - receive/provide the private data <br>
116 * If the STTE developers want to provide the above services, use the following APIs and implement the corresponding callback functions: <br>
120 * <th>DESCRIPTION</th>
121 * <th>CORRESPONDING CALLBACK</th>
124 * <td>stte_set_private_data_set_cb()</td>
125 * <td>Sets a callback function for receiving the private data from the engine service user.</td>
126 * <td>stte_private_data_set_cb()</td>
129 * <td>stte_set_private_data_requested_cb()</td>
130 * <td>Sets a callback function for providing the private data to the engine service user.</td>
131 * <td>stte_private_data_requested_cb()</td>
135 * Using the above APIs, the STTE developers can register the optional callback functions respectively.
136 * (For normal operation, put those APIs before 'service_app_main()' starts.)
137 * 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>
141 * <th>DESCRIPTION</th>
144 * <td>stte_send_result()</td>
145 * <td>Sends the recognition result to the engine service user.</td>
148 * <td>stte_send_error()</td>
149 * <td>Sends the error to the engine service user.</td>
152 * <td>stte_send_speech_status()</td>
153 * <td>Sends the speech status to the engine service user when STT engine notifies the change of the speech status.</td>
157 * @section CAPI_UIX_STTE_MODULE_FEATURE Related Features
158 * This API is related with the following features:<br>
159 * - http://tizen.org/feature/speech.recognition<br>
160 * - http://tizen.org/feature/microphone<br>
161 * It is recommended to design feature related codes in your application for reliability.<br>
162 * 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>
163 * 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>
164 * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature"><b>Feature Element</b>.</a>
168 #endif /* __TIZEN_UIX_STT_ENGINE_DOC_H__ */