2 * Copyright (c) 2011-2014 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_
25 * @addtogroup STT_SETTING_MODULE
34 * @brief Enumerations of error codes.
37 STT_SETTING_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
38 STT_SETTING_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */
39 STT_SETTING_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
40 STT_SETTING_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */
41 STT_SETTING_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< No answer from the daemon */
42 STT_SETTING_ERROR_OUT_OF_NETWORK = TIZEN_ERROR_NETWORK_DOWN, /**< Out of network */
43 STT_SETTING_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,/**< Permission denied */
44 STT_SETTING_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< STT is NOT supported */
45 STT_SETTING_ERROR_INVALID_STATE = TIZEN_ERROR_STT | 0x01, /**< Invalid state */
46 STT_SETTING_ERROR_INVALID_LANGUAGE = TIZEN_ERROR_STT | 0x02, /**< Invalid language */
47 STT_SETTING_ERROR_ENGINE_NOT_FOUND = TIZEN_ERROR_STT | 0x03, /**< No available engine */
48 STT_SETTING_ERROR_OPERATION_FAILED = TIZEN_ERROR_STT | 0x04, /**< Operation failed */
49 STT_SETTING_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_STT | 0x05 /**< Not supported feature of current engine */
53 * @brief Enumerations of setting state.
56 STT_SETTING_STATE_NONE = 0,
57 STT_SETTING_STATE_READY
58 } stt_setting_state_e;
62 * @brief Called to get a engine information.
64 * @param[in] engine_id Engine id.
65 * @param[in] engine_name engine name.
66 * @param[in] setting_path gadget path of engine specific setting.
67 * @param[in] user_data User data passed from the stt_setting_foreach_supported_engines().
69 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
70 * @pre stt_setting_foreach_supported_engines() will invoke this callback.
72 * @see stt_setting_foreach_supported_engines()
74 typedef bool(*stt_setting_supported_engine_cb)(const char* engine_id, const char* engine_name, const char* setting_path, void* user_data);
77 * @brief Called to get a language.
79 * @param[in] engine_id Engine id.
80 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
81 * followed by ISO 639-1 for the two-letter language code.
82 * For example, "ko_KR" for Korean, "en_US" for American English..
83 * @param[in] user_data User data passed from the stt_setting_foreach_supported_languages().
85 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
86 * @pre stt_setting_foreach_supported_languages() will invoke this callback.
88 * @see stt_setting_foreach_supported_languages()
90 typedef bool(*stt_setting_supported_language_cb)(const char* engine_id, const char* language, void* user_data);
93 * @brief Called when the engine information is changed.
95 * @param[in] user_data The user data passed from the callback registration function
97 * @pre An application registers this callback using stt_setting_set_engine_changed_cb().
99 * @see stt_setting_set_engine_changed_cb()
100 * @see stt_setting_unset_engine_changed_cb()
102 typedef void (*stt_setting_engine_changed_cb)(void *user_data);
105 * @brief Called when the STT configure is changed.
107 * @param[in] user_data The user data passed from the callback registration function
109 * @pre An application registers this callback using stt_setting_set_config_changed_cb().
111 * @see stt_setting_set_config_changed_cb()
112 * @see stt_setting_unset_config_changed_cb()
114 typedef void (*stt_setting_config_changed_cb)(void *user_data);
117 * @brief Initialize STT setting.
119 * @remarks If the function succeeds, @a stt setting must be released with stt_setting_finalize().
121 * @return 0 on success, otherwise a negative error value.
122 * @retval #STT_SETTING_ERROR_NONE Success.
123 * @retval #STT_SETTING_ERROR_TIMED_OUT stt daemon is blocked or stt daemon do not exist.
124 * @retval #STT_SETTING_ERROR_INVALID_STATE STT setting has Already been initialized.
125 * @retval #STT_SETTING_ERROR_ENGINE_NOT_FOUND No available stt-engine. Engine should be installed.
126 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
128 * @see stt_setting_finalize()
130 int stt_setting_initialize(void);
133 * @brief finalize stt setting and disconnect to stt-daemon.
135 * @return 0 on success, otherwise a negative error value.
136 * @retval #STT_SETTING_ERROR_NONE Success.
137 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
138 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
139 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
141 * @see stt_setting_initialize()
143 int stt_setting_finalize(void);
146 * @brief Retrieve supported engine informations using callback function.
148 * @param[in] callback callback function
149 * @param[in] user_data User data to be passed to the callback function.
151 * @return 0 on success, otherwise a negative error value.
152 * @retval #STT_SETTING_ERROR_NONE Success.
153 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
154 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
155 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
157 * @post This function invokes stt_setting_supported_engine_cb() repeatedly for getting engine information.
159 * @see stt_setting_supported_engine_cb()
161 int stt_setting_foreach_supported_engines(stt_setting_supported_engine_cb callback, void* user_data);
164 * @brief Get current engine id.
166 * @remark If the function is success, @a engine_id must be released with free() by you.
168 * @param[out] engine_id engine id.
170 * @return 0 on success, otherwise a negative error value.
171 * @retval #STT_SETTING_ERROR_NONE Success.
172 * @retval #STT_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
173 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
174 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
175 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
176 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
178 * @see stt_setting_set_engine()
180 int stt_setting_get_engine(char** engine_id);
183 * @brief Set current engine id.
185 * @param[in] engine_id engine id.
187 * @return 0 on success, otherwise a negative error value.
188 * @retval #STT_SETTING_ERROR_NONE Success.
189 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
190 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
191 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
192 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
194 * @see stt_setting_get_engine()
196 int stt_setting_set_engine(const char* engine_id);
199 * @brief Get supported languages of current engine.
201 * @param[in] callback callback function.
202 * @param[in] user_data User data to be passed to the callback function.
204 * @return 0 on success, otherwise a negative error value.
205 * @retval #STT_SETTING_ERROR_NONE Success.
206 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
207 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
208 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
209 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
211 * @post This function invokes stt_setting_supported_language_cb() repeatedly for getting supported languages.
213 * @see stt_setting_supported_language_cb()
215 int stt_setting_foreach_supported_languages(stt_setting_supported_language_cb callback, void* user_data);
218 * @brief Get a default language of current engine.
220 * @remark If the function is success, @a language must be released with free() by you.
222 * @param[out] language current language
224 * @return 0 on success, otherwise a negative error value.
225 * @retval #STT_SETTING_ERROR_NONE Success.
226 * @retval #STT_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
227 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
228 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
229 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
230 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
232 * @see stt_setting_set_default_language()
234 int stt_setting_get_default_language(char** language);
237 * @brief Set a default language of current engine.
239 * @param[in] language language
241 * @return 0 on success, otherwise a negative error value.
242 * @retval #STT_SETTING_ERROR_NONE Success.
243 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
244 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
245 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
246 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
248 * @see stt_setting_get_default_language()
250 int stt_setting_set_default_language(const char* language);
253 * @brief Set a automatic option of language.
255 * @param[in] value The automatic option
257 * @return 0 on success, otherwise a negative error 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.
262 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
264 * @see stt_setting_get_auto_language()
266 int stt_setting_set_auto_language(bool value);
269 * @brief Get a automatic option of voice.
271 * @param[out] value The automatic option
273 * @return 0 on success, otherwise a negative error value.
274 * @retval #STT_SETTING_ERROR_NONE Success.
275 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
276 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
277 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
278 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
280 * @see stt_setting_set_auto_language()
282 int stt_setting_get_auto_language(bool* value);
285 * @brief Get silence detection.
287 * @param[out] value Value.
289 * @return 0 on success, otherwise a negative error value
290 * @retval #STT_SETTING_ERROR_NONE Success.
291 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
292 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
293 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
294 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
296 * @see stt_setting_set_silence_detection()
298 int stt_setting_get_silence_detection(bool* value);
301 * @brief Set silence detection.
303 * @param[in] value Value.
305 * @return 0 on success, otherwise a negative error value
306 * @retval #STT_SETTING_ERROR_NONE Success.
307 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
308 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
309 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
310 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
312 * @see stt_setting_get_silence_detection()
314 int stt_setting_set_silence_detection(const bool value);
317 * @brief Registers a callback function to be called when engine information is changed
319 * @param[in] callback The callback function to register
320 * @param[in] user_data The user data to be passed to the callback function
322 * @return 0 on success, otherwise a negative error value
323 * @retval #STT_SETTING_ERROR_NONE Successful
324 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter
325 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Invalid state
326 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
328 * @see stt_setting_engine_changed_cb()
329 * @see stt_setting_unset_engine_changed_cb()
331 int stt_setting_set_engine_changed_cb(stt_setting_engine_changed_cb callback, void* user_data);
334 * @brief Unregisters the callback function
336 * @return 0 on success, otherwise a negative error value
337 * @retval #STT_SETTING_ERROR_NONE Successful
338 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Invalid state
340 * @see stt_setting_set_engine_changed_cb()
342 int stt_setting_unset_engine_changed_cb();
345 * @brief Registers a callback function to be called when stt configure is changed
347 * @param[in] callback The callback function to register
348 * @param[in] user_data The user data to be passed to the callback function
350 * @return 0 on success, otherwise a negative error value
351 * @retval #STT_SETTING_ERROR_NONE Successful
352 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter
353 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Invalid state
354 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
356 * @see stt_setting_config_changed_cb()
357 * @see stt_setting_unset_config_changed_cb()
359 int stt_setting_set_config_changed_cb(stt_setting_config_changed_cb callback, void* user_data);
362 * @brief Unregisters the callback function
364 * @return 0 on success, otherwise a negative error value
365 * @retval #STT_SETTING_ERROR_NONE Successful
366 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Invalid state
367 * @retval #STT_SETTING_ERROR_NOT_SUPPORTED STT NOT supported
369 * @see stt_setting_set_config_changed_cb()
371 int stt_setting_unset_config_changed_cb();
381 #endif /* __STT_SETTING_H_ */