include/voice_control_setting.h

   1 /*
   2 * Copyright (c) 2011-2019 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   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
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  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.
  15 */
  16
  17
  18 #ifndef __VOICE_CONTROL_SETTING_H__
  19 #define __VOICE_CONTROL_SETTING_H__
  20
  21 #include <stdbool.h>
  22
  23
  24 /**
  25 * @addtogroup VOICE_CONTROL_SETTING_MODULE
  26 * @{
  27 */
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34 * @brief Definition of audio-in type.
  35 */
  36 #define VC_SETTING_LANGUAGE_AUTO        "auto"
  37
  38 /**
  39 * @brief Called when voice control service enabled is changed.
  40 *
  41 * @param[in] enabled Service enabled
  42 * @param[in] user_data The user data passed from the callback registration function
  43 *
  44 * @pre An application registers this callback to detect changing service enabled.
  45 *
  46 * @see vc_setting_set_enabled_changed_cb()
  47 */
  48 typedef void (*vc_setting_enabled_changed_cb)(bool enabled, void* user_data);
  49
  50 /**
  51 * @brief Called to get a engine information.
  52 *
  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().
  59 *
  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.
  62 *
  63 * @see vc_setting_foreach_supported_engines()
  64 */
  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);
  66
  67 /**
  68 * @brief Called when the engine information is changed.
  69 *
  70 * @param[in] engine_id Engine id
  71 * @param[in] user_data The user data passed from the callback registration function
  72 *
  73 * @pre An application registers this callback using vc_setting_set_engine_changed_cb().
  74 *
  75 * @see vc_setting_set_engine_changed_cb()
  76 * @see vc_setting_unset_engine_changed_cb()
  77 */
  78 typedef void (*vc_setting_engine_changed_cb)(const char* engine_id, void *user_data);
  79
  80 /**
  81 * @brief Called to retrieve supported language.
  82 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  83 *
  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
  88 *
  89 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  90 *
  91 * @pre The function will invoke this callback.
  92 */
  93 typedef bool(*vc_setting_supported_language_cb)(const char* language, void* user_data);
  94
  95 /**
  96 * @brief Called when default language is changed.
  97 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  98 *
  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
 102 *
 103 * @pre An application registers this callback to detect changing mode.
 104 *
 105 * @see vc_setting_set_current_language_changed_cb()
 106 */
 107 typedef void (*vc_setting_current_language_changed_cb)(const char* previous, const char* current, void* user_data);
 108
 109 /**
 110 * @brief Initializes voice control setting
 111 *
 112 * @remarks If the function succeeds, @a vc mgr must be released with vc_setting_finalize().
 113 *
 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.
 118 *
 119 * @see vc_setting_finalize()
 120 */
 121 int vc_setting_initialize(void);
 122
 123 /**
 124 * @brief Deinitializes vc setting
 125 *
 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.
 130 *
 131 * @see vc_setting_initialize()
 132 */
 133 int vc_setting_deinitialize(void);
 134
 135 /**
 136 * @brief Retrieve supported engine informations using callback function.
 137 *
 138 * @param[in] callback callback function
 139 * @param[in] user_data User data to be passed to the callback function.
 140 *
 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.
 145 *
 146 * @post This function invokes vc_setting_supported_engine_cb() repeatedly for getting engine information.
 147 *
 148 * @see vc_setting_supported_engine_cb()
 149 */
 150 int vc_setting_foreach_supported_engines(vc_setting_supported_engine_cb callback, void* user_data);
 151
 152 /**
 153 * @brief Get current engine id.
 154 *
 155 * @remark If the function is success, @a engine_id must be released with free() by you.
 156 *
 157 * @param[out] engine_id engine id.
 158 *
 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.
 165 *
 166 * @see vc_setting_set_engine()
 167 */
 168 int vc_setting_get_engine(char** engine_id);
 169
 170 /**
 171 * @brief Set current engine id.
 172 *
 173 * @param[in] engine_id engine id.
 174 *
 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.
 180 *
 181 * @see vc_setting_get_engine()
 182 */
 183 int vc_setting_set_engine(const char* engine_id);
 184
 185 /**
 186 * @brief Gets supported languages of current engine
 187 *
 188 * @param[in] callback callback function
 189 * @param[in] user_data User data to be passed to the callback function
 190 *
 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.
 196 *
 197 * @post This function invokes vc_setting_supported_language_cb() repeatedly for getting supported languages.
 198 *
 199 * @see vc_setting_supported_language_cb()
 200 */
 201 int vc_setting_foreach_supported_languages(vc_setting_supported_language_cb callback, void* user_data);
 202
 203 /**
 204 * @brief Gets the default language.
 205 *
 206 * @remark If the function is success, @a language must be released with free() by you.
 207 *
 208 * @param[out] language current language
 209 *
 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.
 216 *
 217 * @see vc_setting_set_language()
 218 */
 219 int vc_setting_get_language(char** language);
 220
 221 /**
 222 * @brief Sets the default language.
 223 *
 224 * @param[in] language language
 225 *
 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.
 231 *
 232 * @see vc_setting_get_language()
 233 */
 234 int vc_setting_set_language(const char* language);
 235
 236 /**
 237 * @brief Sets a automatic option of language.
 238 *
 239 * @param[in] value The automatic option
 240 *
 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.
 246 *
 247 * @see vc_setting_get_auto_language()
 248 */
 249 int vc_setting_set_auto_language(bool value);
 250
 251 /**
 252 * @brief Gets a automatic option of voice.
 253 *
 254 * @param[out] value The automatic option
 255 *
 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.
 261 *
 262 * @see vc_setting_set_auto_language()
 263 */
 264 int vc_setting_get_auto_language(bool* value);
 265
 266 /**
 267 * @brief Sets voice control service enabled.
 268 *
 269 * @param[in] value The enabled option
 270 *
 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.
 276 *
 277 * @see vc_setting_get_enabled()
 278 */
 279 int vc_setting_set_enabled(bool value);
 280
 281 /**
 282 * @brief Gets voice control service enabled.
 283 *
 284 * @param[out] value The enabled option
 285 *
 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.
 291 *
 292 * @see vc_setting_set_enabled()
 293 */
 294 int vc_setting_get_enabled(bool* value);
 295
 296 /**
 297 * @brief Sets a callback function to be called when service enabled is changed.
 298 *
 299 * @param[in] callback Callback function to register
 300 * @param[in] user_data The user data to be passed to the callback function
 301 *
 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.
 307 *
 308 * @pre vc_setting_initialize() should be successful.
 309 *
 310 * @see vc_setting_unset_enabled_changed_cb()
 311 */
 312 int vc_setting_set_enabled_changed_cb(vc_setting_enabled_changed_cb callback, void* user_data);
 313
 314 /**
 315 * @brief Unsets the callback function.
 316 *
 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.
 322 *
 323 * @pre vc_setting_initialize() should be successful.
 324 *
 325 * @see vc_setting_set_enabled_changed_cb()
 326 */
 327 int vc_setting_unset_enabled_changed_cb();
 328
 329 /**
 330 * @brief Registers a callback function to be called when current language is changed.
 331 *
 332 * @param[in] callback Callback function to register
 333 * @param[in] user_data The user data to be passed to the callback function
 334 *
 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.
 339 *
 340 * @pre vc_setting_initialize() should be successful.
 341 *
 342 * @see vc_setting_unset_current_language_changed_cb()
 343 */
 344 int vc_setting_set_current_language_changed_cb(vc_setting_current_language_changed_cb callback, void* user_data);
 345
 346 /**
 347 * @brief Unregisters the callback function.
 348 *
 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.
 353 *
 354 * @pre vc_setting_initialize() should be successful.
 355 *
 356 * @see vc_setting_set_current_language_changed_cb()
 357 */
 358 int vc_setting_unset_current_language_changed_cb();
 359
 360 /**
 361 * @brief Registers a callback function to be called when engine information is changed
 362 *
 363 * @param[in] callback The callback function to register
 364 * @param[in] user_data The user data to be passed to the callback function
 365 *
 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
 370 *
 371 * @see vc_setting_engine_changed_cb()
 372 * @see vc_setting_unset_engine_changed_cb()
 373 */
 374 int vc_setting_set_engine_changed_cb(vc_setting_engine_changed_cb callback, void* user_data);
 375
 376 /**
 377 * @brief Unregisters the callback function
 378 *
 379 * @return 0 on success, otherwise a negative error value
 380 * @retval #VC_ERROR_NONE Successful
 381 * @retval #VC_ERROR_OPERATION_FAILED Invalid state
 382 *
 383 * @see vc_setting_set_engine_changed_cb()
 384 */
 385 int vc_setting_unset_engine_changed_cb();
 386
 387
 388 #ifdef __cplusplus
 389 }
 390 #endif
 391
 392 /**
 393 * @}
 394 */
 395
 396 #endif /* __VOICE_CONTROL_SETTING_H__ */