client/stt_setting.h

   1 /*
   2 *  Copyright (c) 2012, 2013 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 <errno.h>
  19 #include <stdbool.h>
  20
  21 /**
  22 * @addtogroup STT_SETTING_MODULE
  23 * @{
  24 */
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /**
  31 * @brief Enumerations of error codes.
  32 */
  33 typedef enum {
  34         STT_SETTING_ERROR_NONE                  = 0,            /**< Success, No error */
  35         STT_SETTING_ERROR_OUT_OF_MEMORY         = -ENOMEM,      /**< Out of Memory */
  36         STT_SETTING_ERROR_IO_ERROR              = -EIO,         /**< I/O error */
  37         STT_SETTING_ERROR_INVALID_PARAMETER     = -EINVAL,      /**< Invalid parameter */
  38         STT_SETTING_ERROR_TIMED_OUT             = -ETIMEDOUT,   /**< No answer from the daemon */
  39         STT_SETTING_ERROR_OUT_OF_NETWORK        = -ENETDOWN,    /**< Out of network */
  40         STT_SETTING_ERROR_INVALID_STATE         = -0x0100031,   /**< Invalid state */
  41         STT_SETTING_ERROR_INVALID_LANGUAGE      = -0x0100032,   /**< Invalid language */
  42         STT_SETTING_ERROR_ENGINE_NOT_FOUND      = -0x0100033,   /**< No available STT-engine  */
  43         STT_SETTING_ERROR_OPERATION_FAILED      = -0x0100034,   /**< STT daemon failed  */
  44         STT_SETTING_ERROR_NOT_SUPPORTED_FEATURE = -0x0100035    /**< Not supported feature of current engine */
  45 }stt_setting_error_e;
  46
  47 /**
  48 * @brief Enumerations of setting state.
  49 */
  50 typedef enum {
  51         STT_SETTING_STATE_NONE = 0,
  52         STT_SETTING_STATE_READY
  53 } stt_setting_state_e;
  54
  55 /**
  56 * @brief Called to get a engine information.
  57 *
  58 * @param[in] engine_id Engine id.
  59 * @param[in] engine_name engine name.
  60 * @param[in] setting_path gadget path of engine specific setting.
  61 * @param[in] user_data User data passed from the stt_setting_foreach_supported_engines().
  62 *
  63 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  64 * @pre stt_setting_foreach_supported_engines() will invoke this callback.
  65 *
  66 * @see stt_setting_foreach_supported_engines()
  67 */
  68 typedef bool(*stt_setting_supported_engine_cb)(const char* engine_id, const char* engine_name, const char* setting_path, void* user_data);
  69
  70 /**
  71 * @brief Called to get a language.
  72 *
  73 * @param[in] engine_id Engine id.
  74 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
  75 *               followed by ISO 639-1 for the two-letter language code.
  76 *               For example, "ko_KR" for Korean, "en_US" for American English..
  77 * @param[in] user_data User data passed from the stt_setting_foreach_supported_languages().
  78 *
  79 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  80 * @pre stt_setting_foreach_supported_languages() will invoke this callback.
  81 *
  82 * @see stt_setting_foreach_supported_languages()
  83 */
  84 typedef bool(*stt_setting_supported_language_cb)(const char* engine_id, const char* language, void* user_data);
  85
  86 /**
  87 * @brief Called to get a engine setting.
  88 *
  89 * @param[in] engine_id Engine id.
  90 * @param[in] key Key.
  91 * @param[in] value Value.
  92 * @param[in] user_data User data passed from the stt_setting_foreach_engine_settings().
  93 *
  94 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  95 * @pre stt_setting_foreach_engine_settings() will invoke this callback.
  96 *
  97 * @see stt_setting_foreach_engine_settings()
  98 */
  99 typedef bool(*stt_setting_engine_setting_cb)(const char* engine_id, const char* key, const char* value, void* user_data);
 100
 101 /**
 102 * @brief Called to initialize setting.
 103 *
 104 * @param[in] state Current state.
 105 * @param[in] reason Error reason.
 106 * @param[in] user_data User data passed from the stt_setting_initialize_async().
 107 *
 108 * @pre stt_setting_initialize_async() will invoke this callback.
 109 *
 110 * @see stt_setting_initialize_async()
 111 */
 112 typedef void(*stt_setting_initialized_cb)(stt_setting_state_e state, stt_setting_error_e reason, void* user_data);
 113
 114 /**
 115 * @brief Initialize STT setting and connect to stt-daemon.
 116 *
 117 * @return 0 on success, otherwise a negative error value.
 118 * @retval #STT_SETTING_ERROR_NONE Success.
 119 * @retval #STT_SETTING_ERROR_TIMED_OUT stt daemon is blocked or stt daemon do not exist.
 120 * @retval #STT_SETTING_ERROR_INVALID_STATE STT setting has Already been initialized.
 121 * @retval #STT_SETTING_ERROR_ENGINE_NOT_FOUND No available stt-engine. Engine should be installed.
 122 *
 123 * @see stt_setting_finalize()
 124 */
 125 int stt_setting_initialize(void);
 126 int stt_setting_initialize_async(stt_setting_initialized_cb callback, void* user_data);
 127
 128 /**
 129 * @brief finalize stt setting and disconnect to stt-daemon.
 130 *
 131 * @return 0 on success, otherwise a negative error value.
 132 * @retval #STT_SETTING_ERROR_NONE Success.
 133 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 134 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 135 *
 136 * @see stt_setting_initialize()
 137 */
 138 int stt_setting_finalize(void);
 139
 140 /**
 141 * @brief Retrieve supported engine informations using callback function.
 142 *
 143 * @param[in] callback callback function
 144 * @param[in] user_data User data to be passed to the callback function.
 145 *
 146 * @return 0 on success, otherwise a negative error value.
 147 * @retval #STT_SETTING_ERROR_NONE Success.
 148 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 149 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 150 * @post This function invokes stt_setting_supported_engine_cb() repeatedly for getting engine information.
 151 *
 152 * @see stt_setting_supported_engine_cb()
 153 */
 154 int stt_setting_foreach_supported_engines(stt_setting_supported_engine_cb callback, void* user_data);
 155
 156 /**
 157 * @brief Get current engine id.
 158 *
 159 * @remark If the function is success, @a engine_id must be released with free() by you.
 160 *
 161 * @param[out] engine_id engine id.
 162 *
 163 * @return 0 on success, otherwise a negative error value.
 164 * @retval #STT_SETTING_ERROR_NONE Success.
 165 * @retval #STT_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
 166 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 167 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 168 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 169 *
 170 * @see stt_setting_set_engine()
 171 */
 172 int stt_setting_get_engine(char** engine_id);
 173
 174 /**
 175 * @brief Set current engine id.
 176 *
 177 * @param[in] engine_id engine id.
 178 *
 179 * @return 0 on success, otherwise a negative error value.
 180 * @retval #STT_SETTING_ERROR_NONE Success.
 181 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 182 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 183 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 184 *
 185 * @see stt_setting_get_engine()
 186 */
 187 int stt_setting_set_engine(const char* engine_id);
 188
 189 /**
 190 * @brief Get supported languages of current engine.
 191 *
 192 * @param[in] callback callback function.
 193 * @param[in] user_data User data to be passed to the callback function.
 194 *
 195 * @return 0 on success, otherwise a negative error value.
 196 * @retval #STT_SETTING_ERROR_NONE Success.
 197 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 198 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 199 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 200 *
 201 * @post This function invokes stt_setting_supported_language_cb() repeatedly for getting supported languages.
 202 *
 203 * @see stt_setting_supported_language_cb()
 204 */
 205 int stt_setting_foreach_supported_languages(stt_setting_supported_language_cb callback, void* user_data);
 206
 207 /**
 208 * @brief Get a default language of current engine.
 209 *
 210 * @remark If the function is success, @a language must be released with free() by you.
 211 *
 212 * @param[out] language current language
 213 *
 214 * @return 0 on success, otherwise a negative error value.
 215 * @retval #STT_SETTING_ERROR_NONE Success.
 216 * @retval #STT_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
 217 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 218 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 219 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 220 *
 221 * @see stt_setting_set_default_language()
 222 */
 223 int stt_setting_get_default_language(char** language);
 224
 225 /**
 226 * @brief Set a default language of current engine.
 227 *
 228 * @param[in] language language
 229 *
 230 * @return 0 on success, otherwise a negative error value.
 231 * @retval #STT_SETTING_ERROR_NONE Success.
 232 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 233 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 234 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 235 *
 236 * @see stt_setting_get_default_language()
 237 */
 238 int stt_setting_set_default_language(const char* language);
 239
 240 /**
 241 * @brief Get profanity filter
 242 *
 243 * @param[out] value Value.
 244 *
 245 * @retval #STT_SETTING_ERROR_NONE Success.
 246 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 247 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 248 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 249 *
 250 * @see stt_setting_set_profanity_filter()
 251 */
 252 int stt_setting_get_profanity_filter(bool* value);
 253
 254 /**
 255 * @brief Set profanity filter.
 256 *
 257 * @param[in] value Value.
 258 *
 259 * @retval #STT_SETTING_ERROR_NONE Success.
 260 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 261 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 262 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 263 *
 264 * @see stt_setting_get_profanity_filter()
 265 */
 266 int stt_setting_set_profanity_filter(const bool value);
 267
 268 /**
 269 * @brief Get punctuation override.
 270 *
 271 * @param[out] value Value.
 272 *
 273 * @retval #STT_SETTING_ERROR_NONE Success.
 274 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 275 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 276 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 277 *
 278 * @see stt_setting_set_punctuation_override()
 279 */
 280 int stt_setting_get_punctuation_override(bool* value);
 281
 282 /**
 283 * @brief Set punctuation override.
 284 *
 285 * @param[in] value Value.
 286 *
 287 * @retval #STT_SETTING_ERROR_NONE Success.
 288 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 289 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 290 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 291 *
 292 * @see stt_setting_get_punctuation_override()
 293 */
 294 int stt_setting_set_punctuation_override(const bool value);
 295
 296 /**
 297 * @brief Get silence detection.
 298 *
 299 * @param[out] value Value.
 300 *
 301 * @retval #STT_SETTING_ERROR_NONE Success.
 302 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 303 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 304 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 305 *
 306 * @see stt_setting_set_silence_detection()
 307 */
 308 int stt_setting_get_silence_detection(bool* value);
 309
 310 /**
 311 * @brief Set silence detection.
 312 *
 313 * @param[in] value Value.
 314 *
 315 * @retval #STT_SETTING_ERROR_NONE Success.
 316 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 317 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 318 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 319 *
 320 * @see stt_setting_get_silence_detection()
 321 */
 322 int stt_setting_set_silence_detection(const bool value);
 323
 324 /**
 325 * @brief Get setting information of current engine.
 326 *
 327 * @param[in] callback callback function
 328 * @param[in] user_data User data to be passed to the callback function.
 329 *
 330 * @return 0 on success, otherwise a negative error value.
 331 * @retval #STT_SETTING_ERROR_NONE Success.
 332 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 333 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 334 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 335 *
 336 * @post This function invokes stt_setting_engine_setting_cb() repeatedly for getting engine settings.
 337 *
 338 * @see stt_setting_engine_setting_cb()
 339 */
 340 int stt_setting_foreach_engine_settings(stt_setting_engine_setting_cb callback, void* user_data);
 341
 342 /**
 343 * @brief Set setting information.
 344 *
 345 * @param[in] key Key.
 346 * @param[in] value Value.
 347 *
 348 * @return 0 on success, otherwise a negative error value.
 349 * @retval #STT_SETTING_ERROR_NONE Success.
 350 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 351 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 352 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 353 *
 354 * @see stt_setting_foreach_engine_settings()
 355 */
 356 int stt_setting_set_engine_setting(const char* key, const char* value);
 357
 358
 359 #ifdef __cplusplus
 360 }
 361 #endif
 362
 363 /**
 364 * @}@}
 365 */
 366
 367 #endif /* __STT_SETTING_H_ */