include/ttse.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 __TTSE_H__
  16 #define __TTSE_H__
  17
  18
  19 #include <tizen.h>
  20
  21
  22 /**
  23 * @addtogroup CAPI_UIX_TTSE_MODULE
  24 * @{
  25 */
  26
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32
  33 /**
  34 * @brief Enumeration for error codes.
  35 * @since_tizen 3.0
  36 */
  37 typedef enum {
  38         TTSE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  39         TTSE_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */
  40         TTSE_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
  41         TTSE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  42         TTSE_ERROR_NETWORK_DOWN = TIZEN_ERROR_NETWORK_DOWN, /**< Out of network */
  43         TTSE_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  44         TTSE_ERROR_INVALID_STATE = TIZEN_ERROR_TTS | 0x01, /**< Invalid state */
  45         TTSE_ERROR_INVALID_VOICE = TIZEN_ERROR_TTS | 0x02, /**< Invalid voice */
  46         TTSE_ERROR_OPERATION_FAILED = TIZEN_ERROR_TTS | 0x04, /**< Operation failed */
  47         TTSE_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_TTS | 0x06, /**< Not supported feature */
  48         TTSE_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED /**< Not supported */
  49 } ttse_error_e;
  50
  51
  52 /**
  53 * @brief Enumeration for audio type.
  54 * @since_tizen 3.0
  55 */
  56 typedef enum {
  57         TTSE_AUDIO_TYPE_RAW_S16 = 0, /**< Signed 16-bit audio type */
  58         TTSE_AUDIO_TYPE_RAW_U8, /**< Unsigned 8-bit audio type */
  59         TTSE_AUDIO_TYPE_MAX
  60 } ttse_audio_type_e;
  61
  62
  63 /**
  64 * @brief Enumeration for result event type.
  65 * @since_tizen 3.0
  66 */
  67 typedef enum {
  68         TTSE_RESULT_EVENT_FAIL = -1, /**< Event when the voice synthesis is failed */
  69         TTSE_RESULT_EVENT_START = 1, /**< Event when the sound data is first data by callback function */
  70         TTSE_RESULT_EVENT_CONTINUE      = 2, /**< Event when the next sound data exist, not first and not last */
  71         TTSE_RESULT_EVENT_FINISH = 3 /**< Event when the sound data is last data or sound data is only one result */
  72 } ttse_result_event_e;
  73
  74 /**
  75 * @brief Enumeration for TTS mode mask.
  76 * @since_tizen 7.0
  77 */
  78 typedef enum {
  79         TTSE_MODE_MASK_DEFAULT = 0x01, /**< Default mode */
  80         TTSE_MODE_MASK_NOTIFICATION = 0x02, /**< Notification mode */
  81         TTSE_MODE_MASK_SCREEN_READER = 0x04, /**< Screen reader mode */
  82         TTSE_MODE_MASK_INTERRUPT = 0x08 /**< Interrupt mode */
  83 } ttse_mode_mask_e;
  84
  85
  86 /**
  87 * @brief Definition for male voice type.
  88 * @since_tizen 3.0
  89 */
  90 #define TTSE_VOICE_TYPE_MALE    1
  91
  92
  93 /**
  94 * @brief Definition for female voice type.
  95 * @since_tizen 3.0
  96 */
  97 #define TTSE_VOICE_TYPE_FEMALE  2
  98
  99
 100 /**
 101 * @brief Definition for child's voice type.
 102 * @since_tizen 3.0
 103 */
 104 #define TTSE_VOICE_TYPE_CHILD   3
 105
 106 /**
 107 * @brief Called when TTS engine informs the engine service user about whole supported language and voice type list.
 108 * @details This callback function is implemented by the engine service user. Therefore, the engine developer does NOT have to implement this callback function.
 109 * @since_tizen 3.0
 110 * @remarks This callback function is called by ttse_foreach_supported_voices_cb() to inform the whole supported voice list.
 111 *          @a user_data must be transferred from ttse_foreach_supported_voices_cb().
 112 * @param[in] language The language is specified as an ISO 3166 alpha-2 two-letter country code
 113 *                     followed by ISO 639-1 for the two-letter language code.
 114 *                     For example, "ko_KR" for Korean, "en_US" for American English
 115 * @param[in] type The voice type
 116 * @param[in] user_data The user data passed from ttse_foreach_supported_voices_cb()
 117 * @return @c true to continue with the next iteration of the loop
 118 *         @c false to break out of the loop
 119 * @pre ttse_foreach_supported_voices_cb() will invoke this callback function.
 120 * @see ttse_foreach_supported_voices_cb()
 121 */
 122 typedef bool (*ttse_supported_voice_cb)(const char* language, int type, void* user_data);
 123
 124
 125 /**
 126 * @brief Called when the engine service user initializes TTS engine.
 127 * @since_tizen 3.0
 128 * @remarks This callback function is mandatory and must be registered using ttse_main().
 129 * @return @c 0 on success,
 130 *         otherwise a negative error value
 131 * @retval #TTSE_ERROR_NONE Successful
 132 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 133 * @retval #TTSE_ERROR_INVALID_STATE Already initialized
 134 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 135 * @retval #TTSE_ERROR_PERMISSION_DENIED Permission denied
 136 * @see ttse_deinitialize_cb()
 137 */
 138 typedef int (*ttse_initialize_cb)(void);
 139
 140
 141 /**
 142 * @brief Called when the engine service user deinitializes TTS engine.
 143 * @since_tizen 3.0
 144 * @remarks This callback function is mandatory and must be registered using ttse_main().
 145 *          NOTE that the engine may be terminated automatically.
 146 *          When this callback function is invoked, the release of resources is necessary.
 147 * @return @c 0 on success,
 148 *         otherwise a negative error value
 149 * @retval #TTSE_ERROR_NONE Successful
 150 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 151 * @see ttse_initialize_cb()
 152 */
 153 typedef int (*ttse_deinitialize_cb)(void);
 154
 155
 156 /**
 157 * @brief Called when the engine service user gets the whole supported voice list.
 158 * @since_tizen 3.0
 159 * @remarks This callback function is mandatory and must be registered using ttse_main().
 160 *          In this function, the engine service user's callback function 'ttse_supported_voice_cb()' is invoked repeatedly for getting all supported voices, and @a user_data must be transferred to 'ttse_supported_voice_cb()'.
 161 *          If 'ttse_supported_voice_cb()' returns @c false, it should be stopped to call 'ttse_supported_voice_cb()'.
 162 * @param[in] callback The callback function
 163 * @param[in] user_data The user data which must be passed to ttse_supported_voice_cb()
 164 * @return @c 0 on success,
 165 *         otherwise a negative error value
 166 * @retval #TTSE_ERROR_NONE Successful
 167 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 168 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 169 * @post This callback function invokes ttse_supported_voice_cb() repeatedly for getting all supported voices.
 170 * @see ttse_supported_voice_cb()
 171 */
 172 typedef int (*ttse_foreach_supported_voices_cb)(ttse_supported_voice_cb callback, void* user_data);
 173
 174
 175 /**
 176 * @brief Called when the engine service user checks whether the voice is valid or not in TTS engine.
 177 * @since_tizen 3.0
 178 * @remarks This callback function is mandatory and must be registered using ttse_main().
 179 * @param[in] language The language is specified as an ISO 3166 alpha-2 two-letter country code
 180 *                     followed by ISO 639-1 for the two-letter language code.
 181 *                     For example, "ko_KR" for Korean, "en_US" for American English
 182 * @param[in] type The voice type
 183 * @param[out] is_valid A variable for checking whether the corresponding voice is valid or not.
 184 *                      @c true to be valid,
 185 *                      @c false to be invalid
 186 * @return @c 0 on success,
 187 *         otherwise a negative error value
 188 * @retval #TTSE_ERROR_NONE Successful
 189 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 190 * @see ttse_foreach_supported_voices_cb()
 191 */
 192 typedef int (*ttse_is_valid_voice_cb)(const char* language, int type, bool* is_valid);
 193
 194
 195 /**
 196 * @brief Called when the engine service user sets the default pitch of TTS engine.
 197 * @since_tizen 3.0
 198 * @remarks This callback function is mandatory and must be registered using ttse_main().
 199 * @param[in] pitch The default pitch
 200 * @return @c 0 on success,
 201 *         otherwise a negative error value
 202 * @retval #TTSE_ERROR_NONE Successful
 203 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 204 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 205 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 206 */
 207 typedef int (*ttse_set_pitch_cb)(int pitch);
 208
 209
 210 /**
 211 * @brief Called when the engine service user sets the personal tts id of TTS engine.
 212 * @since_tizen 9.0
 213 * @remarks This callback function is optional and is registered using ttse_set_personal_tts_id_set_cb().
 214 * @param[in] ptts_id The personal tts id
 215 * @return @c 0 on success,
 216 *         otherwise a negative error value
 217 * @retval #TTSE_ERROR_NONE Successful
 218 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 219 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 220 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 221 */
 222 typedef int (*ttse_set_personal_tts_id_cb)(const char* ptts_id);
 223
 224
 225 /**
 226 * @brief Called when the engine service user requests to load the corresponding voice type for the first time.
 227 * @since_tizen 3.0
 228 * @remarks This callback function is mandatory and must be registered using ttse_main().
 229 * @param[in] language The language is specified as an ISO 3166 alpha-2 two-letter country code
 230 *                     followed by ISO 639-1 for the two-letter language code.
 231 *                     For example, "ko_KR" for Korean, "en_US" for American English
 232 * @param[in] type The voice type
 233 * @return @c 0 on success,
 234 *         otherwise a negative error value
 235 * @retval #TTSE_ERROR_NONE Successful
 236 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 237 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 238 * @retval #TTSE_ERROR_OUT_OF_MEMORY Out of memory
 239 * @retval #TTSE_ERROR_INVALID_VOICE Invalid voice
 240 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 241 * @see ttse_unload_voice_cb()
 242 */
 243 typedef int (*ttse_load_voice_cb)(const char* language, int type);
 244
 245
 246 /**
 247 * @brief Called when the engine service user requests to unload the corresponding voice type or to stop using voice.
 248 * @since_tizen 3.0
 249 * @remarks This callback function is mandatory and must be registered using ttse_main().
 250 * @param[in] language The language is specified as an ISO 3166 alpha-2 two-letter country code
 251 *                     followed by ISO 639-1 for the two-letter language code.
 252 *                     For example, "ko_KR" for Korean, "en_US" for American English
 253 * @param[in] type The voice type
 254 * @return @c 0 on success,
 255 *         otherwise a negative error value
 256 * @retval #TTSE_ERROR_NONE Successful
 257 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 258 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 259 * @retval #TTSE_ERROR_INVALID_VOICE Invalid voice
 260 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 261 * @see ttse_load_voice_cb()
 262 */
 263 typedef int (*ttse_unload_voice_cb)(const char* language, int type);
 264
 265
 266 /**
 267 * @brief Called when the engine service user requests for TTS engine to check whether the application agreed the usage of TTS engine.
 268 * @details This callback function is called when the engine service user requests for TTS engine to check the application's agreement about using the engine.
 269 *          According to the need, the engine developer can provide some user interfaces to check the agreement.
 270 * @since_tizen 3.0
 271 * @remarks This callback function is mandatory and must be registered using ttse_main().
 272 *          If the TTS engine developer wants not to check the agreement, the developer has need to return proper values as @a is_agreed in accordance with the intention. @c true if the developer regards that every application agreed the usage of the engine, @c false if the developer regards that every application disagreed.
 273 *          NOTE that, however, there may be any legal issue unless the developer checks the agreement. Therefore, we suggest that the engine developers should provide a function to check the agreement.
 274 * @param[in] appid The Application ID
 275 * @param[out] is_agreed A variable for checking whether the application agreed to use TTS engine or not.
 276 *                       @c true to agree,
 277 *                       @c false to disagree
 278 * @return @c 0 on success,
 279 *         otherwise a negative error value
 280 * @retval #TTSE_ERROR_NONE Successful
 281 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 282 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 283 * @retval #TTSE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 284 */
 285 typedef int (*ttse_check_app_agreed_cb)(const char* appid, bool* is_agreed);
 286
 287
 288 /**
 289 * @brief Called when the engine service user checks whether TTS engine needs the application's credential.
 290 * @since_tizen 3.0
 291 * @remarks This callback function is mandatory and must be registered using ttse_main().
 292 * @return @c true if TTS engine needs the application's credential,
 293 *         otherwise @c false
 294 */
 295 typedef bool (*ttse_need_app_credential_cb)(void);
 296
 297
 298 /**
 299 * @brief Called when the engine service user starts to synthesize a voice, asynchronously.
 300 * @since_tizen 3.0
 301 * @remarks This callback function is mandatory and must be registered using ttse_main().
 302 *          In this callback function, TTS engine must transfer the synthesized result and @a user_data to the engine service user using ttse_send_result().
 303 *          Also, if TTS engine needs the application's credential, it can set the credential granted to the application.
 304 * @param[in] language The language is specified as an ISO 3166 alpha-2 two-letter country code
 305 *                     followed by ISO 639-1 for the two-letter language code.
 306 *                     For example, "ko_KR" for Korean, "en_US" for American English
 307 * @param[in] type The voice type
 308 * @param[in] text Texts
 309 * @param[in] speed The speed of speaking
 310 * @param[in] appid The Application ID
 311 * @param[in] credential The credential granted to the application
 312 * @param[in] user_data The user data which must be passed to ttse_send_result()
 313 * @return @c 0 on success,
 314 *         otherwise a negative error value
 315 * @retval #TTSE_ERROR_NONE Successful
 316 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 317 * @retval #TTSE_ERROR_INVALID_STATE Not initialized or already started synthesis
 318 * @retval #TTSE_ERROR_INVALID_VOICE Invalid voice
 319 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 320 * @retval #TTSE_ERROR_NETWORK_DOWN Out of network
 321 * @retval #TTSE_ERROR_PERMISSION_DENIED Permission denied
 322 * @post This function invokes ttse_send_result().
 323 * @see ttse_send_result()
 324 * @see ttse_cancel_synthesis_cb()
 325 * @see ttse_need_app_credential_cb()
 326 */
 327 typedef int (*ttse_start_synthesis_cb)(const char* language, int type, const char* text, int speed, const char* appid, const char* credential, void* user_data);
 328
 329
 330 /**
 331 * @brief Called when the engine service user cancels to synthesize a voice.
 332 * @since_tizen 3.0
 333 * @remarks This callback function is mandatory and must be registered using ttse_main().
 334 * @return @c 0 on success,
 335 *         otherwise a negative error value
 336 * @retval #TTSE_ERROR_NONE Successful
 337 * @retval #TTSE_ERROR_INVALID_STATE Not initialized or not started synthesis
 338 * @pre The ttse_start_synthesis_cb() should be performed
 339 * @see ttse_start_synthesis_cb()
 340 */
 341 typedef int (*ttse_cancel_synthesis_cb)(void);
 342
 343
 344 /**
 345 * @brief Called when the engine service user requests the basic information of TTS engine.
 346 * @since_tizen 3.0
 347 * @remarks This callback function is mandatory and must be registered using ttse_main().
 348 *          The allocated @a engine_uuid, @a engine_name, and @a engine_setting will be released internally.
 349 *          In order to upload the engine at Tizen Appstore, both a service app and a ui app are necessary.
 350 *          Therefore, @a engine_setting must be transferred to the engine service user.
 351 * @param[out] engine_uuid UUID of engine
 352 * @param[out] engine_name Name of engine
 353 * @param[out] engine_setting The engine setting application(ui app)'s app ID
 354 * @param[out] use_network The status for using network
 355 * @return @c 0 on success,
 356 *         otherwise a negative error code on failure
 357 * @retval #TTSE_ERROR_NONE Successful
 358 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 359 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 360 */
 361 typedef int (*ttse_get_info_cb)(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
 362
 363
 364 /**
 365 * @brief Called when TTS engine receives the private data from the engine service user.
 366 * @details This callback function is called when the engine service user sends the private data to TTS engine.
 367 * @since_tizen 3.0
 368 * @remarks This callback function is optional and is registered using ttse_set_private_data_set_cb().
 369 * @param[in] key The key field of private data
 370 * @param[in] data The data field of private data
 371 * @return @c 0 on success,
 372 *         otherwise a negative error value
 373 * @retval #TTSE_ERROR_NONE Successful
 374 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 375 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 376 * @retval #TTSE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 377 * @see ttse_private_data_requested_cb()
 378 * @see ttse_set_private_data_set_cb()
 379 */
 380 typedef int (*ttse_private_data_set_cb)(const char* key, const char* data);
 381
 382
 383 /**
 384 * @brief Called when TTS engine provides the engine service user with the private data.
 385 * @details This callback function is called when the engine service user gets the private data from TTS engine.
 386 * @since_tizen 3.0
 387 * @remarks This callback function is optional and is registered using ttse_set_private_data_requested_cb().
 388 * @param[out] key The key field of private data
 389 * @param[out] data The data field of private data
 390 * @return @c 0 on success,
 391 *         otherwise a negative error value
 392 * @retval #TTSE_ERROR_NONE Successful
 393 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 394 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 395 * @retval #TTSE_ERROR_NOT_SUPPORTED_FEATURE Not supported feature
 396 * @see ttse_private_data_set_cb()
 397 * @see ttse_set_private_data_requested_cb()
 398 */
 399 typedef int (*ttse_private_data_requested_cb)(const char* key, char** data);
 400
 401
 402 /**
 403 * @brief Called when activated modes are changed.
 404 * @details When a client connects to TTS engine, the engine activates the TTS mode of the client.
 405 *          For example, if two clients, one is default mode and other is screen reader mode, connect to TTS engine, then the
 406 *          @a activated_mode has the same bit sequence as '#TTSE_MODE_MASK_DEFAULT | #TTSE_MODE_MASK_SCREEN_READER'.
 407 *          The activated TTS modes are decided according to the connected clients, so when a client connects or disconnects to
 408 *          the engine, the activated TTS modes may be changed.
 409 *          This callback function is called when the activated TTS modes are changed.
 410 * @since_tizen 7.0
 411 * @remarks This callback function is optional and is registered using ttse_set_activated_mode_changed_cb().
 412 * @param[in] activated_mode The activated TTS modes by connected clients, values of #ttse_mode_mask_e combined with bitwise 'or'.
 413 * @see ttse_set_activated_mode_changed_cb()
 414 * @see ttse_get_activated_mode()
 415 */
 416 typedef void (*ttse_activated_mode_changed_cb)(int activated_mode);
 417
 418
 419 /**
 420 * @brief A structure for the TTS engine functions.
 421 * @details This structure contains essential callback functions for operating TTS engine.
 422 * @since_tizen 3.0
 423 * @remarks These functions are mandatory for operating TTS engine. Therefore, all functions MUST be implemented.
 424 */
 425 typedef struct {
 426         int version; /**< The version of the structure 'ttse_request_callback_s' */
 427         ttse_get_info_cb                        get_info; /**< Called when the engine service user requests the basic information of TTS engine */
 428
 429         ttse_initialize_cb                      initialize; /**< Called when the engine service user initializes TTS engine */
 430         ttse_deinitialize_cb                    deinitialize; /**< Called when the engine service user deinitializes TTS engine */
 431
 432         ttse_foreach_supported_voices_cb        foreach_voices; /**< Called when the engine service user gets the whole supported voice list */
 433         ttse_is_valid_voice_cb                  is_valid_voice; /**< Called when the engine service user checks whether the voice is valid or not in TTS engine */
 434         ttse_set_pitch_cb                       set_pitch; /**< Called when the engine service user sets the default pitch of TTS engine */
 435
 436         ttse_load_voice_cb                      load_voice; /**< Called when the engine service user requests to load the corresponding voice type for the first time */
 437         ttse_unload_voice_cb                    unload_voice; /**< Called when the engine service user requests to unload the corresponding voice type or to stop using voice */
 438
 439         ttse_start_synthesis_cb                 start_synth; /**< Called when the engine service user starts to synthesize a voice, asynchronously */
 440         ttse_cancel_synthesis_cb                cancel_synth; /**< Called when the engine service user cancels to synthesize a voice */
 441
 442         ttse_check_app_agreed_cb                check_app_agreed; /**< Called when the engine service user requests for TTS engine to check whether the application agreed the usage of TTS engine */
 443         ttse_need_app_credential_cb             need_app_credential; /**< Called when the engine service user checks whether TTS engine needs the application's credential */
 444 } ttse_request_callback_s;
 445
 446
 447 /**
 448 * @brief Main function for Text-To-Speech (TTS) engine.
 449 * @details This function is the main function for operating TTS engine.
 450 * @since_tizen 3.0
 451 * @remarks The service_app_main() should be used for working the engine after this function.
 452 * @param[in] argc The argument count(original)
 453 * @param[in] argv The argument(original)
 454 * @param[in] callback The structure of engine request callback function
 455 * @return This function returns zero on success,
 456 *         or negative with error code on failure
 457 * @retval #TTSE_ERROR_NONE Successful
 458 * @retval #TTSE_ERROR_NOT_SUPPORTED Not supported
 459 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 460 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 461 * @see ttse_request_callback_s
 462 * @code
 463 #include <ttse.h>
 464
 465 // Required callback functions - MUST BE IMPLEMENTED
 466 static int ttsengine_get_info_cb(char** engine_uuid, char** engine_name, char** engine_setting, bool* use_network);
 467 static int ttsengine_initialize_cb(void);
 468 static int ttsengine_deinitialize_cb(void);
 469 static int ttsengine_is_valid_voice_cb(const char* language, int type, bool* is_valid);
 470 static int ttsengine_foreach_supported_voices_cb(ttse_supported_voice_cb callback, void* user_data);
 471 static int ttsengine_set_pitch_cb(int pitch);
 472 static int ttsengine_load_voice_cb(const char* language, int type);
 473 static int ttsengine_unload_voice_cb(const char* language, int type);
 474 static int ttsengine_start_synthesis_cb(const char* language, int type, const char* text, int speed, void* user_data);
 475 static int ttsengine_cancel_synthesis_cb(void);
 476 static int ttsengine_check_app_agreed_cb(const char* appid, bool* is_agreed);
 477 static bool ttsengine_need_app_credential_cb(void);
 478
 479 // Optional callback function
 480 static int ttsengine_private_data_set_cb(const char* key, const char* data);
 481
 482 int main(int argc, char* argv[])
 483 {
 484         // 1. Create a structure 'ttse_request_callback_s'
 485         ttse_request_callback_s engine_callback = { 0, };
 486
 487         engine_callback.size = sizeof(ttse_request_callback_s);
 488         engine_callback.version = 1;
 489         engine_callback.get_info = ttsengine_get_info_cb;
 490         engine_callback.initialize = ttsengine_initialize_cb;
 491         engine_callback.deinitialize = ttsengine_deinitialize_cb;
 492         engine_callback.foreach_voices = ttsengine_foreach_supported_voices_cb;
 493         engine_callback.is_valid_voice = ttsengine_is_valid_voice_cb;
 494         engine_callback.set_pitch = ttsengine_set_pitch_cb;
 495         engine_callback.load_voice = ttsengine_load_voice_cb;
 496         engine_callback.unload_voice = ttsengine_unload_voice_cb;
 497         engine_callback.start_synth = ttsengine_start_synthesis_cb;
 498         engine_callback.cancel_synth = ttsengine_cancel_synthesis_cb;
 499         engine_callback.check_app_agreed = ttsengine_check_app_agreed_cb;
 500         engine_callback.need_app_credential = ttsengine_need_app_credential_cb;
 501
 502         // 2. Run 'ttse_main()'
 503         if (0 != ttse_main(argc, argv, &engine_callback)) {
 504                 return -1;
 505         }
 506
 507         // Optional
 508         ttse_set_private_data_set_cb(ttsengine_private_data_set_cb);
 509
 510         // 3. Set event callbacks for service app and Run 'service_app_main()'
 511         char ad[50] = { 0, };
 512
 513         service_app_lifecycle_callback_s event_callback;
 514         app_event_handler_h handlers[5] = { NULL, };
 515
 516         event_callback.create = service_app_create;
 517         event_callback.terminate = service_app_terminate;
 518         event_callback.app_control = service_app_control;
 519
 520         service_app_add_event_handler(&handlers[APP_EVENT_LOW_BATTERY], APP_EVENT_LOW_BATTERY, service_app_low_battery, &ad);
 521         service_app_add_event_handler(&handlers[APP_EVENT_LOW_MEMORY], APP_EVENT_LOW_MEMORY, service_app_low_memory, &ad);
 522         service_app_add_event_handler(&handlers[APP_EVENT_LANGUAGE_CHANGED], APP_EVENT_LANGUAGE_CHANGED, service_app_lang_changed, &ad);
 523         service_app_add_event_handler(&handlers[APP_EVENT_REGION_FORMAT_CHANGED], APP_EVENT_REGION_FORMAT_CHANGED, service_app_region_changed, &ad);
 524
 525         return service_app_main(argc, argv, &event_callback, ad);
 526 }
 527
 528 * @endcode
 529 */
 530 int ttse_main(int argc, char** argv, ttse_request_callback_s *callback);
 531
 532
 533 /**
 534 * @brief Terminates the main function of TTS engine.
 535 * @since_tizen 7.0
 536 * @remarks This function invokes ttse_deinitialize_cb() in #ttse_request_callback_s which is registered by ttse_main().
 537 *          And this function should be called before terminating the engine to ensure safe termination.
 538 * @return @c 0 on success,
 539 *         otherwise a negative error value
 540 * @retval #TTSE_ERROR_NONE Successful
 541 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 542 */
 543 int ttse_terminate(void);
 544
 545
 546 /**
 547 * @brief Gets the speed range from Tizen platform.
 548 * @since_tizen 3.0
 549 * @remarks This API is used when TTS engine wants to get the speed range from Tizen platform.
 550 * @param[out] min The minimum speed value
 551 * @param[out] normal The normal speed value
 552 * @param[out] max The maximum speed value
 553 * @return @c 0 on success,
 554 *         otherwise a negative error value
 555 * @retval #TTSE_ERROR_NONE Successful
 556 * @retval #TTSE_ERROR_NOT_SUPPORTED Not supported
 557 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 558 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 559 */
 560 int ttse_get_speed_range(int* min, int* normal, int* max);
 561
 562
 563 /**
 564 * @brief Gets the pitch range from Tizen platform.
 565 * @since_tizen 3.0
 566 * @remarks This API is used when TTS engine wants to get the pitch range from Tizen platform.
 567 * @param[out] min The minimum pitch value
 568 * @param[out] normal The normal pitch value
 569 * @param[out] max The maximum pitch value
 570 * @return @c 0 on success,
 571 *         otherwise a negative error value
 572 * @retval #TTSE_ERROR_NONE Successful
 573 * @retval #TTSE_ERROR_NOT_SUPPORTED Not supported
 574 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 575 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 576 */
 577 int ttse_get_pitch_range(int* min, int* normal, int* max);
 578
 579
 580 /**
 581 * @brief Sends the synthesized result to the engine service user.
 582 * @since_tizen 3.0
 583 * @remarks This API is used in ttse_start_synthesis_cb(), when TTS engine sends the synthesized result to the engine service user.
 584 *          The synthesized result and @a user_data must be transferred to the engine service user through this function.
 585 * @param[in] event The result event
 586 * @param[in] data Result data
 587 * @param[in] data_size Result data size
 588 * @param[in] audio_type The audio type
 589 * @param[in] rate The sample rate
 590 * @param[in] user_data The user data passed from ttse_start_synthesis_cb()
 591 * @return @c 0 on success,
 592 *         otherwise a negative error value
 593 * @retval #TTSE_ERROR_NONE Successful
 594 * @retval #TTSE_ERROR_NOT_SUPPORTED Not supported
 595 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 596 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 597 * @pre The ttse_main() function should be invoked before this function is called.
 598 *          ttse_start_synthesis_cb() will invoke this function.
 599 * @see ttse_start_synthesis_cb()
 600 */
 601 int ttse_send_result(ttse_result_event_e event, const void* data, unsigned int data_size,
 602                         ttse_audio_type_e audio_type, int rate, void* user_data);
 603
 604
 605 /**
 606 * @brief Sends the error to the engine service user.
 607 * @details The following error codes can be delivered.
 608 *          #TTSE_ERROR_NONE,
 609 *          #TTSE_ERROR_OUT_OF_MEMORY,
 610 *          #TTSE_ERROR_IO_ERROR,
 611 *          #TTSE_ERROR_INVALID_PARAMETER,
 612 *          #TTSE_ERROR_NETWORK_DOWN,
 613 *          #TTSE_ERROR_PERMISSION_DENIED,
 614 *          #TTSE_ERROR_INVALID_STATE,
 615 *          #TTSE_ERROR_INVALID_VOICE,
 616 *          #TTSE_ERROR_OPERATION_FAILED,
 617 *          #TTSE_ERROR_NOT_SUPPORTED_FEATURE,
 618 *          #TTSE_ERROR_NOT_SUPPORTED.
 619 * @since_tizen 3.0
 620 * @param[in] error The error reason
 621 * @param[in] msg The error message
 622 * @return @c 0 on success,
 623 *         otherwise a negative error value
 624 * @retval #TTSE_ERROR_NONE Successful
 625 * @retval #TTSE_ERROR_NOT_SUPPORTED Not supported
 626 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 627 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 628 * @pre The ttse_main() function should be invoked before this function is called.
 629 */
 630 int ttse_send_error(ttse_error_e error, const char* msg);
 631
 632
 633 /**
 634 * @brief Sets a callback function for setting the private data.
 635 * @since_tizen 3.0
 636 * @remarks The ttse_private_data_set_cb() function is called when the engine service user sends the private data.
 637 * @param[in] callback_func ttse_private_data_set event callback function
 638 * @return @c 0 on success,
 639 *         otherwise a negative error value
 640 * @retval #TTSE_ERROR_NONE Successful
 641 * @retval #TTSE_ERROR_NOT_SUPPORTED Not supported
 642 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 643 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 644 * @pre The ttse_main() function should be invoked before this function is called.
 645 * @see ttse_private_data_set_cb()
 646 */
 647 int ttse_set_private_data_set_cb(ttse_private_data_set_cb callback_func);
 648
 649
 650 /**
 651 * @brief Sets a callback function for requesting the private data.
 652 * @since_tizen 3.0
 653 * @remarks The ttse_private_data_requested_cb() function is called when the engine service user gets the private data from TTS engine.
 654 * @param[in] callback_func ttse_private_data_requested event callback function
 655 * @return @c 0 on success,
 656 *         otherwise a negative error value
 657 * @retval #TTSE_ERROR_NONE Successful
 658 * @retval #TTSE_ERROR_NOT_SUPPORTED Not supported
 659 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 660 * @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
 661 * @pre The ttse_main() function should be invoked before this function is called.
 662 * @see ttse_private_data_requested_cb()
 663 */
 664 int ttse_set_private_data_requested_cb(ttse_private_data_requested_cb callback_func);
 665
 666
 667 /**
 668 * @brief Gets activated modes.
 669 * @details When a client connects to TTS engine, the engine activates the TTS mode of the client.
 670 *          For example, if two clients, one is default mode and other is screen reader mode, connect to TTS engine, then the
 671 *          @a activated_mode has the same bit sequence as '#TTSE_MODE_MASK_DEFAULT | #TTSE_MODE_MASK_SCREEN_READER'.
 672 *          Using this API, the engine can get the activated TTS modes information.
 673 * @since_tizen 7.0
 674 * @param[out] activated_mode The activated TTS mode by connected clients, values of #ttse_mode_mask_e combined with bitwise 'or'.
 675 * @return @c 0 on success,
 676 *         otherwise a negative error value
 677 * @retval #TTSE_ERROR_NONE Successful
 678 * @retval #TTSE_ERROR_NOT_SUPPORTED TTS NOT supported
 679 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 680 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 681 * @pre The ttse_main() function should be invoked before this function is called.
 682 * @see ttse_set_activated_mode_changed_cb()
 683 */
 684 int ttse_get_activated_mode(int* activated_mode);
 685
 686
 687 /**
 688 * @brief Sets a callback function to be called when the activated TTS modes are changed.
 689 * @since_tizen 7.0
 690 * @remarks The ttse_activated_mode_changed_cb() function is called when the activated TTS modes are changed.
 691 * @param[in] callback ttse_activated_mode_changed event callback function
 692 * @return @c 0 on success,
 693 *         otherwise a negative error value
 694 * @retval #TTSE_ERROR_NONE Successful
 695 * @retval #TTSE_ERROR_NOT_SUPPORTED TTS NOT supported
 696 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 697 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 698 * @pre The ttse_main() function should be invoked before this function is called.
 699 * @see ttse_activated_mode_changed_cb()
 700 * @see ttse_get_activated_mode()
 701 */
 702 int ttse_set_activated_mode_changed_cb(ttse_activated_mode_changed_cb callback);
 703
 704
 705 /**
 706 * @brief Sets a callback function to be called when a personal TTS id is set.
 707 * @since_tizen 9.0
 708 * @remarks The ttse_set_personal_tts_id_cb() function is called when the activated TTS modes are changed.
 709 * @param[in] callback ttse_activated_mode_changed event callback function
 710 * @return @c 0 on success,
 711 *         otherwise a negative error value
 712 * @retval #TTSE_ERROR_NONE Successful
 713 * @retval #TTSE_ERROR_NOT_SUPPORTED TTS NOT supported
 714 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
 715 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
 716 * @pre The ttse_main() function should be invoked before this function is called.
 717 * @see ttse_activated_mode_changed_cb()
 718 * @see ttse_get_activated_mode()
 719 */
 720 int ttse_set_personal_tts_id_set_cb(ttse_set_personal_tts_id_cb callback);
 721
 722
 723 #ifdef __cplusplus
 724 }
 725 #endif
 726
 727
 728 /**
 729  * @}
 730  */
 731
 732
 733 #endif /* __TTSE_H__ */