client/tts_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 __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(tts_setting_initialized_cb callback, void* user_data);
 150
 151 /**
 152 * @brief finalize tts setting and disconnect to tts-daemon.
 153 *
 154 * @return 0 on success, otherwise a negative error value.
 155 * @retval #TTS_SETTING_ERROR_NONE Success.
 156 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 157 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 158 *
 159 * @see tts_setting_initialize()
 160 */
 161 int tts_setting_finalize(void);
 162
 163 /**
 164 * @brief Retrieve supported engine informations using callback function.
 165 *
 166 * @param[in] callback callback function
 167 * @param[in] user_data User data to be passed to the callback function.
 168 *
 169 * @return 0 on success, otherwise a negative error value.
 170 * @retval #TTS_SETTING_ERROR_NONE Success.
 171 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 172 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 173 * @post This function invokes tts_setting_supported_engine_cb() repeatedly for getting engine information.
 174 *
 175 * @see tts_setting_supported_engine_cb()
 176 */
 177 int tts_setting_foreach_supported_engines(tts_setting_supported_engine_cb callback, void* user_data);
 178
 179 /**
 180 * @brief Get current engine id.
 181 *
 182 * @remark If the function is success, @a engine_id must be released with free() by you.
 183 *
 184 * @param[out] engine_id engine id.
 185 *
 186 * @return 0 on success, otherwise a negative error value.
 187 * @retval #TTS_SETTING_ERROR_NONE Success.
 188 * @retval #TTS_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
 189 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 190 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 191 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 192 *
 193 * @see tts_setting_set_engine()
 194 */
 195 int tts_setting_get_engine(char** engine_id);
 196
 197 /**
 198 * @brief Set current engine id.
 199 *
 200 * @param[in] engine_id engine id.
 201 *
 202 * @return 0 on success, otherwise a negative error value.
 203 * @retval #TTS_SETTING_ERROR_NONE Success.
 204 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 205 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 206 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 207 *
 208 * @see tts_setting_get_engine()
 209 */
 210 int tts_setting_set_engine(const char* engine_id);
 211
 212 /**
 213 * @brief Get supported voices of current engine.
 214 *
 215 * @param[in] callback callback function.
 216 * @param[in] user_data User data to be passed to the callback function.
 217 *
 218 * @return 0 on success, otherwise a negative error value.
 219 * @retval #TTS_SETTING_ERROR_NONE Success.
 220 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 221 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 222 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 223 *
 224 * @post This function invokes tts_setting_supported_voice_cb() repeatedly for getting supported voices.
 225 *
 226 * @see tts_setting_supported_voice_cb()
 227 */
 228 int tts_setting_foreach_surpported_voices(tts_setting_supported_voice_cb callback, void* user_data);
 229
 230 /**
 231 * @brief Get a default voice of current engine.
 232 *
 233 * @remark If the function is success, @a language must be released with free() by you.
 234 *
 235 * @param[out] language current language
 236 * @param[out] voice_type current voice type
 237 *
 238 * @return 0 on success, otherwise a negative error value.
 239 * @retval #TTS_SETTING_ERROR_NONE Success.
 240 * @retval #TTS_SETTING_ERROR_OUT_OF_MEMORY Out of memory.
 241 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 242 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 243 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 244 *
 245 * @see tts_setting_set_default_voice()
 246 */
 247 int tts_setting_get_default_voice(char** language, tts_setting_voice_type_e* voice_type);
 248
 249 /**
 250 * @brief Set a default voice of current engine.
 251 *
 252 * @param[in] language language
 253 * @param[in] voice_type voice type.
 254 *
 255 * @return 0 on success, otherwise a negative error value.
 256 * @retval #TTS_SETTING_ERROR_NONE Success.
 257 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 258 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 259 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 260 *
 261 * @see tts_setting_get_default_voice()
 262 */
 263 int tts_setting_set_default_voice(const char* language, tts_setting_voice_type_e voice_type);
 264
 265 /**
 266 * @brief Get default speed.
 267 *
 268 * @param[out] speed voice speed.
 269 *
 270 * @return 0 on success, otherwise a negative error value.
 271 * @retval #TTS_SETTING_ERROR_NONE Success.
 272 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 273 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 274 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 275 *
 276 * @see tts_setting_set_default_speed()
 277 */
 278 int tts_setting_get_default_speed(tts_setting_speed_e* speed);
 279
 280 /**
 281 * @brief Set a default speed.
 282 *
 283 * @param[in] speed voice speed
 284 *
 285 * @return 0 on success, otherwise a negative error value.
 286 * @retval #TTS_SETTING_ERROR_NONE Success.
 287 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 288 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 289 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 290 *
 291 * @see tts_setting_get_default_speed()
 292 */
 293 int tts_setting_set_default_speed(tts_setting_speed_e speed);
 294
 295 /**
 296 * @brief Get setting information of current engine.
 297 *
 298 * @param[in] callback callback function
 299 * @param[in] user_data User data to be passed to the callback function.
 300 *
 301 * @return 0 on success, otherwise a negative error value.
 302 * @retval #TTS_SETTING_ERROR_NONE Success.
 303 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 304 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 305 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 306 *
 307 * @post This function invokes tts_setting_engine_setting_cb() repeatedly for getting engine settings.
 308 *
 309 * @see tts_setting_engine_setting_cb()
 310 */
 311 int tts_setting_foreach_engine_settings(tts_setting_engine_setting_cb callback, void* user_data);
 312
 313 /**
 314 * @brief Set setting information.
 315 *
 316 * @param[in] key Key.
 317 * @param[in] value Value.
 318 *
 319 * @return 0 on success, otherwise a negative error value.
 320 * @retval #TTS_SETTING_ERROR_NONE Success.
 321 * @retval #TTS_SETTING_ERROR_INVALID_PARAMETER Invalid parameter.
 322 * @retval #TTS_SETTING_ERROR_INVALID_STATE TTS Not initialized.
 323 * @retval #TTS_SETTING_ERROR_OPERATION_FAILED Operation failure.
 324 *
 325 * @see tts_setting_foreach_engine_settings()
 326 */
 327 int tts_setting_set_engine_setting(const char* key, const char* value);
 328
 329 #ifdef __cplusplus
 330 }
 331 #endif
 332
 333 /**
 334 * @}
 335 */
 336
 337 #endif /* __TTS_SETTING_H__ */