client/tts_setting.h

   1 /*
   2 *  Copyright (c) 2012 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 __TTS_SETTING_H__
  16 #define __TTS_SETTING_H__
  17
  18 #include <errno.h>
  19 #include <stdbool.h>
  20
  21 /**
  22 * @addtogroup TTS_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         TTS_SETTING_ERROR_NONE                  = 0,            /**< Success, No error */
  35         TTS_SETTING_ERROR_OUT_OF_MEMORY         = -ENOMEM,      /**< Out of Memory */
  36         TTS_SETTING_ERROR_IO_ERROR              = -EIO,         /**< I/O error */
  37         TTS_SETTING_ERROR_INVALID_PARAMETER     = -EINVAL,      /**< Invalid parameter */
  38         TTS_SETTING_ERROR_INVALID_STATE         = -0x0100021,   /**< Invalid state */
  39         TTS_SETTING_ERROR_INVALID_VOICE         = -0x0100022,   /**< Invalid voice */
  40         TTS_SETTING_ERROR_ENGINE_NOT_FOUND      = -0x0100023,   /**< No available TTS-engine  */
  41         TTS_SETTING_ERROR_TIMED_OUT             = -0x0100024,   /**< No answer from TTS daemon */
  42         TTS_SETTING_ERROR_OPERATION_FAILED      = -0x0100025,   /**< TTS daemon failed  */
  43 } tts_setting_error_e;
  44
  45 /**
  46 * @brief Enumerations of speaking speed.
  47 */
  48 typedef enum {
  49         TTS_SETTING_SPEED_AUTO  = 0,    /**< Speed from settings */
  50         TTS_SETTING_SPEED_VERY_SLOW,    /**< Very slow */
  51         TTS_SETTING_SPEED_SLOW,         /**< Slow */
  52         TTS_SETTING_SPEED_NORMAL,       /**< Normal */
  53         TTS_SETTING_SPEED_FAST,         /**< Fast */
  54         TTS_SETTING_SPEED_VERY_FAST     /**< Very fast */
  55 } tts_setting_speed_e;
  56
  57 /**
  58 * @brief Enumerations of voice type.
  59 */
  60 typedef enum {
  61         TTS_SETTING_VOICE_TYPE_AUTO = 0,        /**< Voice type from settings or auto selection based language*/
  62         TTS_SETTING_VOICE_TYPE_MALE,            /**< Male */
  63         TTS_SETTING_VOICE_TYPE_FEMALE,          /**< Female */
  64         TTS_SETTING_VOICE_TYPE_CHILD,           /**< Child */
  65         TTS_SETTING_VOICE_TYPE_USER1,           /**< Engine defined */
  66         TTS_SETTING_VOICE_TYPE_USER2,           /**< Engine defined */
  67         TTS_SETTING_VOICE_TYPE_USER3            /**< Engine defined */
  68 } tts_setting_voice_type_e;
  69
  70 /**
  71 * @brief Enumerations of setting state.
  72 */
  73 typedef enum {
  74         TTS_SETTING_STATE_NONE = 0,
  75         TTS_SETTING_STATE_READY
  76 } tts_setting_state_e;
  77
  78 /**
  79 * @brief Called to get a engine information.
  80 *
  81 * @param[in] engine_id Engine id.
  82 * @param[in] engine_name engine name.
  83 * @param[in] setting_path gadget path of engine specific setting.
  84 * @param[in] user_data User data passed from the tts_setting_foreach_supported_engines().
  85 *
  86 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
  87 * @pre tts_setting_foreach_supported_engines() will invoke this callback.
  88 *
  89 * @see tts_setting_foreach_supported_engines()
  90 */
  91 typedef bool(*tts_setting_supported_engine_cb)(const char* engine_id, const char* engine_name, const char* setting_path, void* user_data);
  92
  93 /**
  94 * @brief Called to get a voice.
  95 *
  96 * @param[in] engine_id Engine id.
  97 * @param[in] language A language is specified as an ISO 3166 alpha-2 two letter country-code
  98 *               followed by ISO 639-1 for the two-letter language code.
  99 *               For example, "ko_KR" for Korean, "en_US" for American English..
 100 * @param[in] voice_type Voice type.
 101 * @param[in] user_data User data passed from the tts_setting_foreach_surpported_voices().
 102 *
 103 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 104 * @pre tts_setting_foreach_surpported_voices() will invoke this callback.
 105 *
 106 * @see tts_setting_foreach_surpported_voices()
 107 */
 108 typedef bool(*tts_setting_supported_voice_cb)(const char* engine_id, const char* language, tts_setting_voice_type_e voice_type, void* user_data);
 109
 110 /**
 111 * @brief Called to get a engine setting.
 112 *
 113 * @param[in] engine_id Engine id.
 114 * @param[in] key Key.
 115 * @param[in] value Value.
 116 * @param[in] user_data User data passed from the tts_setting_foreach_engine_settings().
 117 *
 118 * @return @c true to continue with the next iteration of the loop, \n @c false to break out of the loop.
 119 * @pre tts_setting_foreach_engine_settings() will invoke this callback.
 120 *
 121 * @see tts_setting_foreach_engine_settings()
 122 */
 123 typedef bool(*tts_setting_engine_setting_cb)(const char* engine_id, const char* key, const char* value, void* user_data);
 124
 125 /**
 126 * @brief Called to initialize setting.
 127 *
 128 * @param[in] state Current state.
 129 * @param[in] reason Error reason.
 130 * @param[in] user_data User data passed from the tts_setting_initialize_async().
 131 *
 132 * @pre tts_setting_initialize_async() will invoke this callback.
 133 *
 134 * @see tts_setting_initialize_async()
 135 */
 136 typedef void(*tts_setting_initialized_cb)(tts_setting_state_e state, tts_setting_error_e reason, void* user_data);
 137
 138 /**
 139 * @brief Initialize TTS setting and connect to tts-daemon asynchronously.
 140 *
 141 * @return 0 on success, otherwise a negative error value.
 142 * @retval #TTS_SETTING_ERROR_NONE Success.
 143 * @retval #TTS_SETTING_ERROR_TIMED_OUT tts daemon is blocked or tts daemon do not exist.
 144 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS setting has Already been initialized.
 145 * @retval #TTS_SETTING_ERROR_ENGINE_NOT_FOUND No available tts-engine. Engine should be installed.
 146 *
 147 * @see tts_setting_finalize()
 148 */
 149 int tts_setting_initialize();
 150
 151 int tts_setting_initialize_async(tts_setting_initialized_cb callback, void* user_data);
 152
 153 /**
 154 * @brief finalize tts setting and disconnect to tts-daemon.
 155 *
 156 * @return 0 on success, otherwise a negative error value.
 157 * @retval #TTS_SETTING_ERROR_NONE Success.
 158 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 159 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 160 *
 161 * @see tts_setting_initialize()
 162 */
 163 int tts_setting_finalize(void);
 164
 165 /**
 166 * @brief Retrieve supported engine informations using callback function.
 167 *
 168 * @param[in] callback callback function
 169 * @param[in] user_data User data to be passed to the callback function.
 170 *
 171 * @return 0 on success, otherwise a negative error value.
 172 * @retval #TTS_SETTING_ERROR_NONE Success.
 173 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 174 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 175 * @post This function invokes tts_setting_supported_engine_cb() repeatedly for getting engine information.
 176 *
 177 * @see tts_setting_supported_engine_cb()
 178 */
 179 int tts_setting_foreach_supported_engines(tts_setting_supported_engine_cb callback, void* user_data);
 180
 181 /**
 182 * @brief Get current engine id.
 183 *
 184 * @remark If the function is success, @a engine_id must be released with free() by you.
 185 *
 186 * @param[out] engine_id engine id.
 187 *
 188 * @return 0 on success, otherwise a negative error value.
 189 * @retval #TTS_SETTING_ERROR_NONE Success.
 190 * @retval #TTS_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
 191 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 192 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 193 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 194 *
 195 * @see tts_setting_set_engine()
 196 */
 197 int tts_setting_get_engine(char** engine_id);
 198
 199 /**
 200 * @brief Set current engine id.
 201 *
 202 * @param[in] engine_id engine id.
 203 *
 204 * @return 0 on success, otherwise a negative error value.
 205 * @retval #TTS_SETTING_ERROR_NONE Success.
 206 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 207 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 208 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 209 *
 210 * @see tts_setting_get_engine()
 211 */
 212 int tts_setting_set_engine(const char* engine_id);
 213
 214 /**
 215 * @brief Get supported voices of current engine.
 216 *
 217 * @param[in] callback callback function.
 218 * @param[in] user_data User data to be passed to the callback function.
 219 *
 220 * @return 0 on success, otherwise a negative error value.
 221 * @retval #TTS_SETTING_ERROR_NONE Success.
 222 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 223 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 224 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 225 *
 226 * @post This function invokes tts_setting_supported_voice_cb() repeatedly for getting supported voices.
 227 *
 228 * @see tts_setting_supported_voice_cb()
 229 */
 230 int tts_setting_foreach_surpported_voices(tts_setting_supported_voice_cb callback, void* user_data);
 231
 232 /**
 233 * @brief Get a default voice of current engine.
 234 *
 235 * @remark If the function is success, @a language must be released with free() by you.
 236 *
 237 * @param[out] language current language
 238 * @param[out] voice_type current voice type
 239 *
 240 * @return 0 on success, otherwise a negative error value.
 241 * @retval #TTS_SETTING_ERROR_NONE Success.
 242 * @retval #TTS_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
 243 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 244 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 245 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 246 *
 247 * @see tts_setting_set_default_voice()
 248 */
 249 int tts_setting_get_default_voice(char** language, tts_setting_voice_type_e* voice_type);
 250
 251 /**
 252 * @brief Set a default voice of current engine.
 253 *
 254 * @param[in] language language
 255 * @param[in] voice_type voice type.
 256 *
 257 * @return 0 on success, otherwise a negative error value.
 258 * @retval #TTS_SETTING_ERROR_NONE Success.
 259 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 260 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 261 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 262 *
 263 * @see tts_setting_get_default_voice()
 264 */
 265 int tts_setting_set_default_voice(const char* language, tts_setting_voice_type_e voice_type);
 266
 267 /**
 268 * @brief Get default speed.
 269 *
 270 * @param[out] speed voice speed.
 271 *
 272 * @return 0 on success, otherwise a negative error value.
 273 * @retval #TTS_SETTING_ERROR_NONE Success.
 274 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 275 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 276 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 277 *
 278 * @see tts_setting_set_default_speed()
 279 */
 280 int tts_setting_get_default_speed(tts_setting_speed_e* speed);
 281
 282 /**
 283 * @brief Set a default speed.
 284 *
 285 * @param[in] speed voice speed
 286 *
 287 * @return 0 on success, otherwise a negative error value.
 288 * @retval #TTS_SETTING_ERROR_NONE Success.
 289 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 290 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 291 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 292 *
 293 * @see tts_setting_get_default_speed()
 294 */
 295 int tts_setting_set_default_speed(tts_setting_speed_e speed);
 296
 297 /**
 298 * @brief Get setting information of current engine.
 299 *
 300 * @param[in] callback callback function
 301 * @param[in] user_data User data to be passed to the callback function.
 302 *
 303 * @return 0 on success, otherwise a negative error value.
 304 * @retval #TTS_SETTING_ERROR_NONE Success.
 305 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 306 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 307 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 308 *
 309 * @post This function invokes tts_setting_engine_setting_cb() repeatedly for getting engine settings.
 310 *
 311 * @see tts_setting_engine_setting_cb()
 312 */
 313 int tts_setting_foreach_engine_settings(tts_setting_engine_setting_cb callback, void* user_data);
 314
 315 /**
 316 * @brief Set setting information.
 317 *
 318 * @param[in] key Key.
 319 * @param[in] value Value.
 320 *
 321 * @return 0 on success, otherwise a negative error value.
 322 * @retval #TTS_SETTING_ERROR_NONE Success.
 323 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 324 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 325 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 326 *
 327 * @see tts_setting_foreach_engine_settings()
 328 */
 329 int tts_setting_set_engine_setting(const char* key, const char* value);
 330
 331 #ifdef __cplusplus
 332 }
 333 #endif
 334
 335 /**
 336 * @}
 337 */
 338
 339 #endif /* __TTS_SETTING_H__ */