include/voice_control_setting.h

   1 /*
   2 * Copyright (c) 2011-2015 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 retrieve supported language.
  52 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  53 *
  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
  58 *
  59 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  60 *
  61 * @pre The function will invoke this callback.
  62 */
  63 typedef bool(*vc_setting_supported_language_cb)(const char* language, void* user_data);
  64
  65 /**
  66 * @brief Called when default language is changed.
  67 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  68 *
  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
  72 *
  73 * @pre An application registers this callback to detect changing mode.
  74 *
  75 * @see vc_setting_set_current_language_changed_cb()
  76 */
  77 typedef void (*vc_setting_current_language_changed_cb)(const char* previous, const char* current, void* user_data);
  78
  79 /**
  80 * @brief Initialize voice control setting
  81 *
  82 * @remarks If the function succeeds, @a vc mgr must be released with vc_setting_finalize().
  83 *
  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.
  88 *
  89 * @see vc_setting_finalize()
  90 */
  91 int vc_setting_initialize(void);
  92
  93 /**
  94 * @brief Deinitialize vc setting
  95 *
  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.
 100 *
 101 * @see vc_setting_initialize()
 102 */
 103 int vc_setting_deinitialize(void);
 104
 105 /**
 106 * @brief Get supported languages of current engine
 107 *
 108 * @param[in] callback callback function
 109 * @param[in] user_data User data to be passed to the callback function
 110 *
 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.
 116 *
 117 * @post This function invokes vc_setting_supported_language_cb() repeatedly for getting supported languages.
 118 *
 119 * @see vc_setting_supported_language_cb()
 120 */
 121 int vc_setting_foreach_supported_languages(vc_setting_supported_language_cb callback, void* user_data);
 122
 123 /**
 124 * @brief Get the default language.
 125 *
 126 * @remark If the function is success, @a language must be released with free() by you.
 127 *
 128 * @param[out] language current language
 129 *
 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.
 136 *
 137 * @see vc_setting_set_language()
 138 */
 139 int vc_setting_get_language(char** language);
 140
 141 /**
 142 * @brief Set the default language.
 143 *
 144 * @param[in] language language
 145 *
 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.
 151 *
 152 * @see vc_setting_get_language()
 153 */
 154 int vc_setting_set_language(const char* language);
 155
 156 /**
 157 * @brief Set a automatic option of language.
 158 *
 159 * @param[in] value The automatic option
 160 *
 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.
 166 *
 167 * @see vc_setting_get_auto_language()
 168 */
 169 int vc_setting_set_auto_language(bool value);
 170
 171 /**
 172 * @brief Get a automatic option of voice.
 173 *
 174 * @param[out] value The automatic option
 175 *
 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.
 181 *
 182 * @see vc_setting_set_auto_language()
 183 */
 184 int vc_setting_get_auto_language(bool* value);
 185
 186 /**
 187 * @brief Set voice control service enabled.
 188 *
 189 * @param[in] value The enabled option
 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 * @see vc_setting_get_enabled()
 198 */
 199 int vc_setting_set_enabled(bool value);
 200
 201 /**
 202 * @brief Get voice control service enabled.
 203 *
 204 * @param[out] value The enabled option
 205 *
 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.
 211 *
 212 * @see vc_setting_set_enabled()
 213 */
 214 int vc_setting_get_enabled(bool* value);
 215
 216 /**
 217 * @brief Sets a callback function to be called when service enabled is changed.
 218 *
 219 * @param[in] callback Callback function to register
 220 * @param[in] user_data The user data to be passed to the callback function
 221 *
 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.
 227 *
 228 * @pre vc_setting_initialize() should be successful.
 229 *
 230 * @see vc_setting_unset_enabled_changed_cb()
 231 */
 232 int vc_setting_set_enabled_changed_cb(vc_setting_enabled_changed_cb callback, void* user_data);
 233
 234 /**
 235 * @brief Unsets the callback function.
 236 *
 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.
 242 *
 243 * @pre vc_setting_initialize() should be successful.
 244 *
 245 * @see vc_setting_set_enabled_changed_cb()
 246 */
 247 int vc_setting_unset_enabled_changed_cb();
 248
 249 /**
 250 * @brief Registers a callback function to be called when current language is changed.
 251 *
 252 * @param[in] callback Callback function to register
 253 * @param[in] user_data The user data to be passed to the callback function
 254 *
 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.
 259 *
 260 * @pre vc_setting_initialize() should be successful.
 261 *
 262 * @see vc_setting_unset_current_language_changed_cb()
 263 */
 264 int vc_setting_set_current_language_changed_cb(vc_setting_current_language_changed_cb callback, void* user_data);
 265
 266 /**
 267 * @brief Unregisters the callback function.
 268 *
 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.
 273 *
 274 * @pre vc_setting_initialize() should be successful.
 275 *
 276 * @see vc_setting_set_current_language_changed_cb()
 277 */
 278 int vc_setting_unset_current_language_changed_cb();
 279
 280
 281 #ifdef __cplusplus
 282 }
 283 #endif
 284
 285 /**
 286 * @}
 287 */
 288
 289 #endif /* __VOICE_CONTROL_SETTING_H__ */