2 * Copyright (c) 2012, 2013 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.
15 #ifndef __STT_SETTING_H_
16 #define __STT_SETTING_H_
22 * @addtogroup STT_SETTING_MODULE
31 * @brief Enumerations of error codes.
34 STT_SETTING_ERROR_NONE = 0, /**< Success, No error */
35 STT_SETTING_ERROR_OUT_OF_MEMORY = -ENOMEM, /**< Out of Memory */
36 STT_SETTING_ERROR_IO_ERROR = -EIO, /**< I/O error */
37 STT_SETTING_ERROR_INVALID_PARAMETER = -EINVAL, /**< Invalid parameter */
38 STT_SETTING_ERROR_TIMED_OUT = -ETIMEDOUT, /**< No answer from the daemon */
39 STT_SETTING_ERROR_OUT_OF_NETWORK = -ENETDOWN, /**< Out of network */
40 STT_SETTING_ERROR_INVALID_STATE = -0x0100031, /**< Invalid state */
41 STT_SETTING_ERROR_INVALID_LANGUAGE = -0x0100032, /**< Invalid language */
42 STT_SETTING_ERROR_ENGINE_NOT_FOUND = -0x0100033, /**< No available STT-engine */
43 STT_SETTING_ERROR_OPERATION_FAILED = -0x0100034, /**< STT daemon failed */
44 STT_SETTING_ERROR_NOT_SUPPORTED_FEATURE = -0x0100035 /**< Not supported feature of current engine */
48 * @brief Enumerations of setting state.
51 STT_SETTING_STATE_NONE = 0,
52 STT_SETTING_STATE_READY
53 } stt_setting_state_e;
56 * @brief Called to get a engine information.
58 * @param[in] engine_id Engine id.
59 * @param[in] engine_name engine name.
60 * @param[in] setting_path gadget path of engine specific setting.
61 * @param[in] user_data User data passed from the stt_setting_foreach_supported_engines().
63 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
64 * @pre stt_setting_foreach_supported_engines() will invoke this callback.
66 * @see stt_setting_foreach_supported_engines()
68 typedef bool(*stt_setting_supported_engine_cb)(const char* engine_id, const char* engine_name, const char* setting_path, void* user_data);
71 * @brief Called to get a language.
73 * @param[in] engine_id Engine id.
74 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
75 * followed by ISO 639-1 for the two-letter language code.
76 * For example, "ko_KR" for Korean, "en_US" for American English..
77 * @param[in] user_data User data passed from the stt_setting_foreach_supported_languages().
79 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
80 * @pre stt_setting_foreach_supported_languages() will invoke this callback.
82 * @see stt_setting_foreach_supported_languages()
84 typedef bool(*stt_setting_supported_language_cb)(const char* engine_id, const char* language, void* user_data);
87 * @brief Called to get a engine setting.
89 * @param[in] engine_id Engine id.
91 * @param[in] value Value.
92 * @param[in] user_data User data passed from the stt_setting_foreach_engine_settings().
94 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
95 * @pre stt_setting_foreach_engine_settings() will invoke this callback.
97 * @see stt_setting_foreach_engine_settings()
99 typedef bool(*stt_setting_engine_setting_cb)(const char* engine_id, const char* key, const char* value, void* user_data);
102 * @brief Called to initialize setting.
104 * @param[in] state Current state.
105 * @param[in] reason Error reason.
106 * @param[in] user_data User data passed from the stt_setting_initialize_async().
108 * @pre stt_setting_initialize_async() will invoke this callback.
110 * @see stt_setting_initialize_async()
112 typedef void(*stt_setting_initialized_cb)(stt_setting_state_e state, stt_setting_error_e reason, void* user_data);
115 * @brief Initialize STT setting and connect to stt-daemon.
117 * @return 0 on success, otherwise a negative error value.
118 * @retval #STT_SETTING_ERROR_NONE Success.
119 * @retval #STT_SETTING_ERROR_TIMED_OUT stt daemon is blocked or stt daemon do not exist.
120 * @retval #STT_SETTING_ERROR_INVALID_STATE STT setting has Already been initialized.
121 * @retval #STT_SETTING_ERROR_ENGINE_NOT_FOUND No available stt-engine. Engine should be installed.
123 * @see stt_setting_finalize()
125 int stt_setting_initialize(stt_setting_initialized_cb callback, void* user_data);
128 * @brief finalize stt setting and disconnect to stt-daemon.
130 * @return 0 on success, otherwise a negative error value.
131 * @retval #STT_SETTING_ERROR_NONE Success.
132 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
133 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
135 * @see stt_setting_initialize()
137 int stt_setting_finalize(void);
140 * @brief Retrieve supported engine informations using callback function.
142 * @param[in] callback callback function
143 * @param[in] user_data User data to be passed to the callback function.
145 * @return 0 on success, otherwise a negative error value.
146 * @retval #STT_SETTING_ERROR_NONE Success.
147 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
148 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
149 * @post This function invokes stt_setting_supported_engine_cb() repeatedly for getting engine information.
151 * @see stt_setting_supported_engine_cb()
153 int stt_setting_foreach_supported_engines(stt_setting_supported_engine_cb callback, void* user_data);
156 * @brief Get current engine id.
158 * @remark If the function is success, @a engine_id must be released with free() by you.
160 * @param[out] engine_id engine id.
162 * @return 0 on success, otherwise a negative error value.
163 * @retval #STT_SETTING_ERROR_NONE Success.
164 * @retval #STT_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
165 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
166 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
167 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
169 * @see stt_setting_set_engine()
171 int stt_setting_get_engine(char** engine_id);
174 * @brief Set current engine id.
176 * @param[in] engine_id engine id.
178 * @return 0 on success, otherwise a negative error value.
179 * @retval #STT_SETTING_ERROR_NONE Success.
180 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
181 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
182 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
184 * @see stt_setting_get_engine()
186 int stt_setting_set_engine(const char* engine_id);
189 * @brief Get supported languages of current engine.
191 * @param[in] callback callback function.
192 * @param[in] user_data User data to be passed to the callback function.
194 * @return 0 on success, otherwise a negative error value.
195 * @retval #STT_SETTING_ERROR_NONE Success.
196 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
197 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
198 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
200 * @post This function invokes stt_setting_supported_language_cb() repeatedly for getting supported languages.
202 * @see stt_setting_supported_language_cb()
204 int stt_setting_foreach_supported_languages(stt_setting_supported_language_cb callback, void* user_data);
207 * @brief Get a default language of current engine.
209 * @remark If the function is success, @a language must be released with free() by you.
211 * @param[out] language current language
213 * @return 0 on success, otherwise a negative error value.
214 * @retval #STT_SETTING_ERROR_NONE Success.
215 * @retval #STT_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
216 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
217 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
218 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
220 * @see stt_setting_set_default_language()
222 int stt_setting_get_default_language(char** language);
225 * @brief Set a default language of current engine.
227 * @param[in] language language
229 * @return 0 on success, otherwise a negative error value.
230 * @retval #STT_SETTING_ERROR_NONE Success.
231 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
232 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
233 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
235 * @see stt_setting_get_default_language()
237 int stt_setting_set_default_language(const char* language);
240 * @brief Get profanity filter
242 * @param[out] value Value.
244 * @retval #STT_SETTING_ERROR_NONE Success.
245 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
246 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
247 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
249 * @see stt_setting_set_profanity_filter()
251 int stt_setting_get_profanity_filter(bool* value);
254 * @brief Set profanity filter.
256 * @param[in] value Value.
258 * @retval #STT_SETTING_ERROR_NONE Success.
259 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
260 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
261 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
263 * @see stt_setting_get_profanity_filter()
265 int stt_setting_set_profanity_filter(const bool value);
268 * @brief Get punctuation override.
270 * @param[out] value Value.
272 * @retval #STT_SETTING_ERROR_NONE Success.
273 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
274 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
275 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
277 * @see stt_setting_set_punctuation_override()
279 int stt_setting_get_punctuation_override(bool* value);
282 * @brief Set punctuation override.
284 * @param[in] value Value.
286 * @retval #STT_SETTING_ERROR_NONE Success.
287 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
288 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
289 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
291 * @see stt_setting_get_punctuation_override()
293 int stt_setting_set_punctuation_override(const bool value);
296 * @brief Get silence detection.
298 * @param[out] value Value.
300 * @retval #STT_SETTING_ERROR_NONE Success.
301 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
302 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
303 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
305 * @see stt_setting_set_silence_detection()
307 int stt_setting_get_silence_detection(bool* value);
310 * @brief Set silence detection.
312 * @param[in] value Value.
314 * @retval #STT_SETTING_ERROR_NONE Success.
315 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
316 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
317 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
319 * @see stt_setting_get_silence_detection()
321 int stt_setting_set_silence_detection(const bool value);
324 * @brief Get setting information of current engine.
326 * @param[in] callback callback function
327 * @param[in] user_data User data to be passed to the callback function.
329 * @return 0 on success, otherwise a negative error value.
330 * @retval #STT_SETTING_ERROR_NONE Success.
331 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
332 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
333 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
335 * @post This function invokes stt_setting_engine_setting_cb() repeatedly for getting engine settings.
337 * @see stt_setting_engine_setting_cb()
339 int stt_setting_foreach_engine_settings(stt_setting_engine_setting_cb callback, void* user_data);
342 * @brief Set setting information.
344 * @param[in] key Key.
345 * @param[in] value Value.
347 * @return 0 on success, otherwise a negative error value.
348 * @retval #STT_SETTING_ERROR_NONE Success.
349 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
350 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
351 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
353 * @see stt_setting_foreach_engine_settings()
355 int stt_setting_set_engine_setting(const char* key, const char* value);
366 #endif /* __STT_SETTING_H_ */