include/stt_setting.h

   1 /*
   2 *  Copyright (c) 2011-2016 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.
  12 */
  13
  14
  15 #ifndef __STT_SETTING_H_
  16 #define __STT_SETTING_H_
  17
  18 #include <tizen.h>
  19
  20 /**
  21  * @file stt_setting.h
  22  */
  23
  24 /**
  25 * @addtogroup STT_SETTING_MODULE
  26 * @{
  27 */
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34 * @brief Enumerations of error codes.
  35 */
  36 typedef enum {
  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 */
  50 } stt_setting_error_e;
  51
  52 /**
  53 * @brief Enumerations of setting state.
  54 */
  55 typedef enum {
  56         STT_SETTING_STATE_NONE = 0,
  57         STT_SETTING_STATE_READY
  58 } stt_setting_state_e;
  59
  60
  61 /**
  62 * @brief Called to get a engine information.
  63 *
  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().
  68 *
  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.
  71 *
  72 * @see stt_setting_foreach_supported_engines()
  73 */
  74 typedef bool(*stt_setting_supported_engine_cb)(const char* engine_id, const char* engine_name, const char* setting_path, void* user_data);
  75
  76 /**
  77 * @brief Called to get a language.
  78 *
  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().
  84 *
  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.
  87 *
  88 * @see stt_setting_foreach_supported_languages()
  89 */
  90 typedef bool(*stt_setting_supported_language_cb)(const char* engine_id, const char* language, void* user_data);
  91
  92 /**
  93 * @brief Called when the engine information is changed.
  94 *
  95 * @param[in] user_data The user data passed from the callback registration function
  96 *
  97 * @pre An application registers this callback using stt_setting_set_engine_changed_cb().
  98 *
  99 * @see stt_setting_set_engine_changed_cb()
 100 * @see stt_setting_unset_engine_changed_cb()
 101 */
 102 typedef void (*stt_setting_engine_changed_cb)(void *user_data);
 103
 104 /**
 105 * @brief Called when the STT configure is changed.
 106 *
 107 * @param[in] user_data The user data passed from the callback registration function
 108 *
 109 * @pre An application registers this callback using stt_setting_set_config_changed_cb().
 110 *
 111 * @see stt_setting_set_config_changed_cb()
 112 * @see stt_setting_unset_config_changed_cb()
 113 */
 114 typedef void (*stt_setting_config_changed_cb)(void *user_data);
 115
 116 /**
 117 * @brief Initialize STT setting.
 118 *
 119 * @remarks If the function succeeds, @a stt setting must be released with stt_setting_finalize().
 120 *
 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
 127 *
 128 * @see stt_setting_finalize()
 129 */
 130 int stt_setting_initialize(void);
 131
 132 /**
 133 * @brief finalize stt setting and disconnect to stt-daemon.
 134 *
 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
 140 *
 141 * @see stt_setting_initialize()
 142 */
 143 int stt_setting_finalize(void);
 144
 145 /**
 146 * @brief Retrieve supported engine informations using callback function.
 147 *
 148 * @param[in] callback callback function
 149 * @param[in] user_data User data to be passed to the callback function.
 150 *
 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
 156 *
 157 * @post This function invokes stt_setting_supported_engine_cb() repeatedly for getting engine information.
 158 *
 159 * @see stt_setting_supported_engine_cb()
 160 */
 161 int stt_setting_foreach_supported_engines(stt_setting_supported_engine_cb callback, void* user_data);
 162
 163 /**
 164 * @brief Get current engine id.
 165 *
 166 * @remark If the function is success, @a engine_id must be released with free() by you.
 167 *
 168 * @param[out] engine_id engine id.
 169 *
 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
 177 *
 178 * @see stt_setting_set_engine()
 179 */
 180 int stt_setting_get_engine(char** engine_id);
 181
 182 /**
 183 * @brief Set current engine id.
 184 *
 185 * @param[in] engine_id engine id.
 186 *
 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
 193 *
 194 * @see stt_setting_get_engine()
 195 */
 196 int stt_setting_set_engine(const char* engine_id);
 197
 198 /**
 199 * @brief Get supported languages of current engine.
 200 *
 201 * @param[in] callback callback function.
 202 * @param[in] user_data User data to be passed to the callback function.
 203 *
 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
 210 *
 211 * @post This function invokes stt_setting_supported_language_cb() repeatedly for getting supported languages.
 212 *
 213 * @see stt_setting_supported_language_cb()
 214 */
 215 int stt_setting_foreach_supported_languages(stt_setting_supported_language_cb callback, void* user_data);
 216
 217 /**
 218 * @brief Get a default language of current engine.
 219 *
 220 * @remark If the function is success, @a language must be released with free() by you.
 221 *
 222 * @param[out] language current language
 223 *
 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
 231 *
 232 * @see stt_setting_set_default_language()
 233 */
 234 int stt_setting_get_default_language(char** language);
 235
 236 /**
 237 * @brief Set a default language of current engine.
 238 *
 239 * @param[in] language language
 240 *
 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
 247 *
 248 * @see stt_setting_get_default_language()
 249 */
 250 int stt_setting_set_default_language(const char* language);
 251
 252 /**
 253 * @brief Set a automatic option of language.
 254 *
 255 * @param[in] value The automatic option
 256 *
 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
 263 *
 264 * @see stt_setting_get_auto_language()
 265 */
 266 int stt_setting_set_auto_language(bool value);
 267
 268 /**
 269 * @brief Get a automatic option of voice.
 270 *
 271 * @param[out] value The automatic option
 272 *
 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
 279 *
 280 * @see stt_setting_set_auto_language()
 281 */
 282 int stt_setting_get_auto_language(bool* value);
 283
 284 /**
 285 * @brief Get silence detection.
 286 *
 287 * @param[out] value Value.
 288 *
 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
 295 *
 296 * @see stt_setting_set_silence_detection()
 297 */
 298 int stt_setting_get_silence_detection(bool* value);
 299
 300 /**
 301 * @brief Set silence detection.
 302 *
 303 * @param[in] value Value.
 304 *
 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
 311 *
 312 * @see stt_setting_get_silence_detection()
 313 */
 314 int stt_setting_set_silence_detection(const bool value);
 315
 316 /**
 317 * @brief Registers a callback function to be called when engine information is changed
 318 *
 319 * @param[in] callback The callback function to register
 320 * @param[in] user_data The user data to be passed to the callback function
 321 *
 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
 327 *
 328 * @see stt_setting_engine_changed_cb()
 329 * @see stt_setting_unset_engine_changed_cb()
 330 */
 331 int stt_setting_set_engine_changed_cb(stt_setting_engine_changed_cb callback, void* user_data);
 332
 333 /**
 334 * @brief Unregisters the callback function
 335 *
 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
 339 *
 340 * @see stt_setting_set_engine_changed_cb()
 341 */
 342 int stt_setting_unset_engine_changed_cb();
 343
 344 /**
 345 * @brief Registers a callback function to be called when stt configure is changed
 346 *
 347 * @param[in] callback The callback function to register
 348 * @param[in] user_data The user data to be passed to the callback function
 349 *
 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
 355 *
 356 * @see stt_setting_config_changed_cb()
 357 * @see stt_setting_unset_config_changed_cb()
 358 */
 359 int stt_setting_set_config_changed_cb(stt_setting_config_changed_cb callback, void* user_data);
 360
 361 /**
 362 * @brief Unregisters the callback function
 363 *
 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
 368 *
 369 * @see stt_setting_set_config_changed_cb()
 370 */
 371 int stt_setting_unset_config_changed_cb();
 372
 373 #ifdef __cplusplus
 374 }
 375 #endif
 376
 377 /**
 378 * @}@}
 379 */
 380
 381 #endif /* __STT_SETTING_H_ */