2 * Copyright (c) 2011-2019 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 __VOICE_CONTROL_SETTING_H__
19 #define __VOICE_CONTROL_SETTING_H__
25 * @addtogroup VOICE_CONTROL_SETTING_MODULE
34 * @brief Definition of audio-in type.
36 #define VC_SETTING_LANGUAGE_AUTO "auto"
39 * @brief Called when voice control service enabled is changed.
41 * @param[in] enabled Service enabled
42 * @param[in] user_data The user data passed from the callback registration function
44 * @pre An application registers this callback to detect changing service enabled.
46 * @see vc_setting_set_enabled_changed_cb()
48 typedef void (*vc_setting_enabled_changed_cb)(bool enabled, void* user_data);
51 * @brief Called to get a engine information.
53 * @param[in] engine_name engine name.
54 * @param[in] engine_appid engine appid.
55 * @param[in] setting_path gadget path of engine specific setting.
56 * @param[in] default_lang default language.
57 * @param[in] non_fixed_support non fixed support.
58 * @param[in] user_data User data passed from the vc_setting_foreach_supported_engines().
60 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
61 * @pre vc_setting_foreach_supported_engines() will invoke this callback.
63 * @see vc_setting_foreach_supported_engines()
65 typedef bool (*vc_setting_supported_engine_cb)(const char *engine_name, const char *engine_appid, const char *setting_path, const char *default_lang, bool non_fixed_support, void *user_data);
68 * @brief Called when the engine information is changed.
70 * @param[in] engine_id Engine id
71 * @param[in] user_data The user data passed from the callback registration function
73 * @pre An application registers this callback using vc_setting_set_engine_changed_cb().
75 * @see vc_setting_set_engine_changed_cb()
76 * @see vc_setting_unset_engine_changed_cb()
78 typedef void (*vc_setting_engine_changed_cb)(const char* engine_id, void *user_data);
81 * @brief Called to retrieve supported language.
84 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
85 * followed by ISO 639-1 for the two-letter language code. \n
86 * For example, "ko_KR" for Korean, "en_US" for American English.
87 * @param[in] user_data The user data passed from the foreach function
89 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
91 * @pre The function will invoke this callback.
93 typedef bool(*vc_setting_supported_language_cb)(const char* language, void* user_data);
96 * @brief Called when default language is changed.
99 * @param[in] previous Previous language
100 * @param[in] current Current language
101 * @param[in] user_data The user data passed from the callback registration function
103 * @pre An application registers this callback to detect changing mode.
105 * @see vc_setting_set_current_language_changed_cb()
107 typedef void (*vc_setting_current_language_changed_cb)(const char* previous, const char* current, void* user_data);
110 * @brief Initializes voice control setting
112 * @remarks If the function succeeds, @a vc mgr must be released with vc_setting_finalize().
114 * @return 0 on success, otherwise a negative error value.
115 * @retval #VC_ERROR_NONE Success.
116 * @retval #VC_ERROR_INVALID_STATE VC setting has Already been initialized.
117 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
119 * @see vc_setting_finalize()
121 int vc_setting_initialize(void);
124 * @brief Deinitializes vc setting
126 * @return 0 on success, otherwise a negative error value.
127 * @retval #VC_ERROR_NONE Success.
128 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
129 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
131 * @see vc_setting_initialize()
133 int vc_setting_deinitialize(void);
136 * @brief Retrieve supported engine informations using callback function.
138 * @param[in] callback callback function
139 * @param[in] user_data User data to be passed to the callback function.
141 * @return 0 on success, otherwise a negative error value.
142 * @retval #VC_ERROR_NONE Success.
143 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
144 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
146 * @post This function invokes vc_setting_supported_engine_cb() repeatedly for getting engine information.
148 * @see vc_setting_supported_engine_cb()
150 int vc_setting_foreach_supported_engines(vc_setting_supported_engine_cb callback, void* user_data);
153 * @brief Get current engine id.
155 * @remark If the function is success, @a engine_id must be released with free() by you.
157 * @param[out] engine_id engine id.
159 * @return 0 on success, otherwise a negative error value.
160 * @retval #VC_ERROR_NONE Success.
161 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory.
162 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
163 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
164 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
166 * @see vc_setting_set_engine()
168 int vc_setting_get_engine(char** engine_id);
171 * @brief Set current engine id.
173 * @param[in] engine_id engine id.
175 * @return 0 on success, otherwise a negative error value.
176 * @retval #VC_ERROR_NONE Success.
177 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
178 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
179 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
181 * @see vc_setting_get_engine()
183 int vc_setting_set_engine(const char* engine_id);
186 * @brief Gets supported languages of current engine
188 * @param[in] callback callback function
189 * @param[in] user_data User data to be passed to the callback function
191 * @return 0 on success, otherwise a negative error value.
192 * @retval #VC_ERROR_NONE Success.
193 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
194 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
195 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
197 * @post This function invokes vc_setting_supported_language_cb() repeatedly for getting supported languages.
199 * @see vc_setting_supported_language_cb()
201 int vc_setting_foreach_supported_languages(vc_setting_supported_language_cb callback, void* user_data);
204 * @brief Gets the default language.
206 * @remark If the function is success, @a language must be released with free() by you.
208 * @param[out] language current language
210 * @return 0 on success, otherwise a negative error value.
211 * @retval #VC_ERROR_NONE Success.
212 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory.
213 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
214 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
215 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
217 * @see vc_setting_set_language()
219 int vc_setting_get_language(char** language);
222 * @brief Sets the default language.
224 * @param[in] language language
226 * @return 0 on success, otherwise a negative error value.
227 * @retval #VC_ERROR_NONE Success.
228 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
229 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
230 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
232 * @see vc_setting_get_language()
234 int vc_setting_set_language(const char* language);
237 * @brief Sets a automatic option of language.
239 * @param[in] value The automatic option
241 * @return 0 on success, otherwise a negative error value.
242 * @retval #VC_ERROR_NONE Success.
243 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
244 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
245 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
247 * @see vc_setting_get_auto_language()
249 int vc_setting_set_auto_language(bool value);
252 * @brief Gets a automatic option of voice.
254 * @param[out] value The automatic option
256 * @return 0 on success, otherwise a negative error value.
257 * @retval #VC_ERROR_NONE Success.
258 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
259 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
260 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
262 * @see vc_setting_set_auto_language()
264 int vc_setting_get_auto_language(bool* value);
267 * @brief Sets voice control service enabled.
269 * @param[in] value The enabled option
271 * @return 0 on success, otherwise a negative error value.
272 * @retval #VC_ERROR_NONE Success.
273 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
274 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
275 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
277 * @see vc_setting_get_enabled()
279 int vc_setting_set_enabled(bool value);
282 * @brief Gets voice control service enabled.
284 * @param[out] value The enabled option
286 * @return 0 on success, otherwise a negative error value.
287 * @retval #VC_ERROR_NONE Success.
288 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
289 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
290 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
292 * @see vc_setting_set_enabled()
294 int vc_setting_get_enabled(bool* value);
297 * @brief Sets a callback function to be called when service enabled is changed.
299 * @param[in] callback Callback function to register
300 * @param[in] user_data The user data to be passed to the callback function
302 * @return 0 on success, otherwise a negative error value.
303 * @retval #VC_ERROR_NONE Success.
304 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
305 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
306 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
308 * @pre vc_setting_initialize() should be successful.
310 * @see vc_setting_unset_enabled_changed_cb()
312 int vc_setting_set_enabled_changed_cb(vc_setting_enabled_changed_cb callback, void* user_data);
315 * @brief Unsets the callback function.
317 * @return 0 on success, otherwise a negative error value
318 * @retval #VC_ERROR_NONE Success.
319 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
320 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
321 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
323 * @pre vc_setting_initialize() should be successful.
325 * @see vc_setting_set_enabled_changed_cb()
327 int vc_setting_unset_enabled_changed_cb();
330 * @brief Registers a callback function to be called when current language is changed.
332 * @param[in] callback Callback function to register
333 * @param[in] user_data The user data to be passed to the callback function
335 * @return 0 on success, otherwise a negative error value
336 * @retval #VC_ERROR_NONE Success.
337 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
338 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
340 * @pre vc_setting_initialize() should be successful.
342 * @see vc_setting_unset_current_language_changed_cb()
344 int vc_setting_set_current_language_changed_cb(vc_setting_current_language_changed_cb callback, void* user_data);
347 * @brief Unregisters the callback function.
349 * @return 0 on success, otherwise a negative error value
350 * @retval #VC_ERROR_NONE Success.
351 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
352 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
354 * @pre vc_setting_initialize() should be successful.
356 * @see vc_setting_set_current_language_changed_cb()
358 int vc_setting_unset_current_language_changed_cb();
361 * @brief Registers a callback function to be called when engine information is changed
363 * @param[in] callback The callback function to register
364 * @param[in] user_data The user data to be passed to the callback function
366 * @return 0 on success, otherwise a negative error value
367 * @retval #VC_ERROR_NONE Successful
368 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter
369 * @retval #VC_ERROR_OPERATION_FAILED Invalid state
371 * @see vc_setting_engine_changed_cb()
372 * @see vc_setting_unset_engine_changed_cb()
374 int vc_setting_set_engine_changed_cb(vc_setting_engine_changed_cb callback, void* user_data);
377 * @brief Unregisters the callback function
379 * @return 0 on success, otherwise a negative error value
380 * @retval #VC_ERROR_NONE Successful
381 * @retval #VC_ERROR_OPERATION_FAILED Invalid state
383 * @see vc_setting_set_engine_changed_cb()
385 int vc_setting_unset_engine_changed_cb();
396 #endif /* __VOICE_CONTROL_SETTING_H__ */