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(stt_setting_initialized_cb callback, void* user_data);
 126
 127 /**
 128 * @brief finalize stt setting and disconnect to stt-daemon.
 129 *
 130 * @return 0 on success, otherwise a negative error value.
 131 * @retval #STT_SETTING_ERROR_NONE Success.
 132 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 133 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 134 *
 135 * @see stt_setting_initialize()
 136 */
 137 int stt_setting_finalize(void);
 138
 139 /**
 140 * @brief Retrieve supported engine informations using callback function.
 141 *
 142 * @param[in] callback callback function
 143 * @param[in] user_data User data to be passed to the callback function.
 144 *
 145 * @return 0 on success, otherwise a negative error value.
 146 * @retval #STT_SETTING_ERROR_NONE Success.
 147 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 148 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 149 * @post This function invokes stt_setting_supported_engine_cb() repeatedly for getting engine information.
 150 *
 151 * @see stt_setting_supported_engine_cb()
 152 */
 153 int stt_setting_foreach_supported_engines(stt_setting_supported_engine_cb callback, void* user_data);
 154
 155 /**
 156 * @brief Get current engine id.
 157 *
 158 * @remark If the function is success, @a engine_id must be released with free() by you.
 159 *
 160 * @param[out] engine_id engine id.
 161 *
 162 * @return 0 on success, otherwise a negative error value.
 163 * @retval #STT_SETTING_ERROR_NONE Success.
 164 * @retval #STT_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
 165 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 166 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 167 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 168 *
 169 * @see stt_setting_set_engine()
 170 */
 171 int stt_setting_get_engine(char** engine_id);
 172
 173 /**
 174 * @brief Set current engine id.
 175 *
 176 * @param[in] engine_id engine id.
 177 *
 178 * @return 0 on success, otherwise a negative error value.
 179 * @retval #STT_SETTING_ERROR_NONE Success.
 180 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 181 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 182 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 183 *
 184 * @see stt_setting_get_engine()
 185 */
 186 int stt_setting_set_engine(const char* engine_id);
 187
 188 /**
 189 * @brief Get supported languages of current engine.
 190 *
 191 * @param[in] callback callback function.
 192 * @param[in] user_data User data to be passed to the callback function.
 193 *
 194 * @return 0 on success, otherwise a negative error value.
 195 * @retval #STT_SETTING_ERROR_NONE Success.
 196 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 197 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 198 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 199 *
 200 * @post This function invokes stt_setting_supported_language_cb() repeatedly for getting supported languages.
 201 *
 202 * @see stt_setting_supported_language_cb()
 203 */
 204 int stt_setting_foreach_supported_languages(stt_setting_supported_language_cb callback, void* user_data);
 205
 206 /**
 207 * @brief Get a default language of current engine.
 208 *
 209 * @remark If the function is success, @a language must be released with free() by you.
 210 *
 211 * @param[out] language current language
 212 *
 213 * @return 0 on success, otherwise a negative error value.
 214 * @retval #STT_SETTING_ERROR_NONE Success.
 215 * @retval #STT_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
 216 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 217 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 218 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 219 *
 220 * @see stt_setting_set_default_language()
 221 */
 222 int stt_setting_get_default_language(char** language);
 223
 224 /**
 225 * @brief Set a default language of current engine.
 226 *
 227 * @param[in] language language
 228 *
 229 * @return 0 on success, otherwise a negative error value.
 230 * @retval #STT_SETTING_ERROR_NONE Success.
 231 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 232 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 233 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 234 *
 235 * @see stt_setting_get_default_language()
 236 */
 237 int stt_setting_set_default_language(const char* language);
 238
 239 /**
 240 * @brief Get profanity filter
 241 *
 242 * @param[out] value Value.
 243 *
 244 * @retval #STT_SETTING_ERROR_NONE Success.
 245 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 246 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 247 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 248 *
 249 * @see stt_setting_set_profanity_filter()
 250 */
 251 int stt_setting_get_profanity_filter(bool* value);
 252
 253 /**
 254 * @brief Set profanity filter.
 255 *
 256 * @param[in] value Value.
 257 *
 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 *
 263 * @see stt_setting_get_profanity_filter()
 264 */
 265 int stt_setting_set_profanity_filter(const bool value);
 266
 267 /**
 268 * @brief Get punctuation override.
 269 *
 270 * @param[out] value Value.
 271 *
 272 * @retval #STT_SETTING_ERROR_NONE Success.
 273 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 274 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 275 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 276 *
 277 * @see stt_setting_set_punctuation_override()
 278 */
 279 int stt_setting_get_punctuation_override(bool* value);
 280
 281 /**
 282 * @brief Set punctuation override.
 283 *
 284 * @param[in] value Value.
 285 *
 286 * @retval #STT_SETTING_ERROR_NONE Success.
 287 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 288 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 289 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 290 *
 291 * @see stt_setting_get_punctuation_override()
 292 */
 293 int stt_setting_set_punctuation_override(const bool value);
 294
 295 /**
 296 * @brief Get silence detection.
 297 *
 298 * @param[out] value Value.
 299 *
 300 * @retval #STT_SETTING_ERROR_NONE Success.
 301 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 302 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 303 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 304 *
 305 * @see stt_setting_set_silence_detection()
 306 */
 307 int stt_setting_get_silence_detection(bool* value);
 308
 309 /**
 310 * @brief Set silence detection.
 311 *
 312 * @param[in] value Value.
 313 *
 314 * @retval #STT_SETTING_ERROR_NONE Success.
 315 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 316 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 317 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 318 *
 319 * @see stt_setting_get_silence_detection()
 320 */
 321 int stt_setting_set_silence_detection(const bool value);
 322
 323 /**
 324 * @brief Get setting information of current engine.
 325 *
 326 * @param[in] callback callback function
 327 * @param[in] user_data User data to be passed to the callback function.
 328 *
 329 * @return 0 on success, otherwise a negative error value.
 330 * @retval #STT_SETTING_ERROR_NONE Success.
 331 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 332 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 333 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 334 *
 335 * @post This function invokes stt_setting_engine_setting_cb() repeatedly for getting engine settings.
 336 *
 337 * @see stt_setting_engine_setting_cb()
 338 */
 339 int stt_setting_foreach_engine_settings(stt_setting_engine_setting_cb callback, void* user_data);
 340
 341 /**
 342 * @brief Set setting information.
 343 *
 344 * @param[in] key Key.
 345 * @param[in] value Value.
 346 *
 347 * @return 0 on success, otherwise a negative error value.
 348 * @retval #STT_SETTING_ERROR_NONE Success.
 349 * @retval #STT_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 350 * @retval #STT_SETTING_ERROR_INVALID_STATE STT Not initialized.
 351 * @retval #STT_SETTING_ERROR_OPERATION_FAILED Operation failure.
 352 *
 353 * @see stt_setting_foreach_engine_settings()
 354 */
 355 int stt_setting_set_engine_setting(const char* key, const char* value);
 356
 357
 358 #ifdef __cplusplus
 359 }
 360 #endif
 361
 362 /**
 363 * @}@}
 364 */
 365
 366 #endif /* __STT_SETTING_H_ */