2 * Copyright (c) 2011-2015 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 retrieve supported language.
52 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
54 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code \n
55 * followed by ISO 639-1 for the two-letter language code. \n
56 * For example, "ko_KR" for Korean, "en_US" for American English.
57 * @param[in] user_data The user data passed from the foreach function
59 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
61 * @pre The function will invoke this callback.
63 typedef bool(*vc_setting_supported_language_cb)(const char* language, void* user_data);
66 * @brief Called when default language is changed.
67 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
69 * @param[in] previous Previous language
70 * @param[in] current Current language
71 * @param[in] user_data The user data passed from the callback registration function
73 * @pre An application registers this callback to detect changing mode.
75 * @see vc_setting_set_current_language_changed_cb()
77 typedef void (*vc_setting_current_language_changed_cb)(const char* previous, const char* current, void* user_data);
80 * @brief Initializes voice control setting
82 * @remarks If the function succeeds, @a vc mgr must be released with vc_setting_finalize().
84 * @return 0 on success, otherwise a negative error value.
85 * @retval #VC_ERROR_NONE Success.
86 * @retval #VC_ERROR_INVALID_STATE VC setting has Already been initialized.
87 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
89 * @see vc_setting_finalize()
91 int vc_setting_initialize(void);
94 * @brief Deinitializes vc setting
96 * @return 0 on success, otherwise a negative error value.
97 * @retval #VC_ERROR_NONE Success.
98 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
99 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
101 * @see vc_setting_initialize()
103 int vc_setting_deinitialize(void);
106 * @brief Gets supported languages of current engine
108 * @param[in] callback callback function
109 * @param[in] user_data User data to be passed to the callback function
111 * @return 0 on success, otherwise a negative error value.
112 * @retval #VC_ERROR_NONE Success.
113 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
114 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
115 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
117 * @post This function invokes vc_setting_supported_language_cb() repeatedly for getting supported languages.
119 * @see vc_setting_supported_language_cb()
121 int vc_setting_foreach_supported_languages(vc_setting_supported_language_cb callback, void* user_data);
124 * @brief Gets the default language.
126 * @remark If the function is success, @a language must be released with free() by you.
128 * @param[out] language current language
130 * @return 0 on success, otherwise a negative error value.
131 * @retval #VC_ERROR_NONE Success.
132 * @retval #VC_ERROR_OUT_OF_MEMORY Out of memory.
133 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
134 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
135 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
137 * @see vc_setting_set_language()
139 int vc_setting_get_language(char** language);
142 * @brief Sets the default language.
144 * @param[in] language language
146 * @return 0 on success, otherwise a negative error value.
147 * @retval #VC_ERROR_NONE Success.
148 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
149 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
150 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
152 * @see vc_setting_get_language()
154 int vc_setting_set_language(const char* language);
157 * @brief Sets a automatic option of language.
159 * @param[in] value The automatic option
161 * @return 0 on success, otherwise a negative error value.
162 * @retval #VC_ERROR_NONE Success.
163 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
164 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
165 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
167 * @see vc_setting_get_auto_language()
169 int vc_setting_set_auto_language(bool value);
172 * @brief Gets a automatic option of voice.
174 * @param[out] value The automatic option
176 * @return 0 on success, otherwise a negative error value.
177 * @retval #VC_ERROR_NONE Success.
178 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
179 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
180 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
182 * @see vc_setting_set_auto_language()
184 int vc_setting_get_auto_language(bool* value);
187 * @brief Sets voice control service enabled.
189 * @param[in] value The enabled option
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 * @see vc_setting_get_enabled()
199 int vc_setting_set_enabled(bool value);
202 * @brief Gets voice control service enabled.
204 * @param[out] value The enabled option
206 * @return 0 on success, otherwise a negative error value.
207 * @retval #VC_ERROR_NONE Success.
208 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
209 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
210 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
212 * @see vc_setting_set_enabled()
214 int vc_setting_get_enabled(bool* value);
217 * @brief Sets a callback function to be called when service enabled is changed.
219 * @param[in] callback Callback function to register
220 * @param[in] user_data The user data to be passed to the callback function
222 * @return 0 on success, otherwise a negative error value.
223 * @retval #VC_ERROR_NONE Success.
224 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
225 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
226 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
228 * @pre vc_setting_initialize() should be successful.
230 * @see vc_setting_unset_enabled_changed_cb()
232 int vc_setting_set_enabled_changed_cb(vc_setting_enabled_changed_cb callback, void* user_data);
235 * @brief Unsets the callback function.
237 * @return 0 on success, otherwise a negative error value
238 * @retval #VC_ERROR_NONE Success.
239 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
240 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
241 * @retval #VC_ERROR_OPERATION_FAILED Operation failure.
243 * @pre vc_setting_initialize() should be successful.
245 * @see vc_setting_set_enabled_changed_cb()
247 int vc_setting_unset_enabled_changed_cb();
250 * @brief Registers a callback function to be called when current language is changed.
252 * @param[in] callback Callback function to register
253 * @param[in] user_data The user data to be passed to the callback function
255 * @return 0 on success, otherwise a negative error value
256 * @retval #VC_ERROR_NONE Success.
257 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
258 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
260 * @pre vc_setting_initialize() should be successful.
262 * @see vc_setting_unset_current_language_changed_cb()
264 int vc_setting_set_current_language_changed_cb(vc_setting_current_language_changed_cb callback, void* user_data);
267 * @brief Unregisters the callback function.
269 * @return 0 on success, otherwise a negative error value
270 * @retval #VC_ERROR_NONE Success.
271 * @retval #VC_ERROR_INVALID_PARAMETER Invalid parameter.
272 * @retval #VC_ERROR_INVALID_STATE VC Not initialized.
274 * @pre vc_setting_initialize() should be successful.
276 * @see vc_setting_set_current_language_changed_cb()
278 int vc_setting_unset_current_language_changed_cb();
289 #endif /* __VOICE_CONTROL_SETTING_H__ */