Update header and doc files written in English
[platform/core/uifw/tts.git] / include / tts.h
1 /*
2  * Copyright (c) 2011-2016 Samsung Electronics Co., Ltd All Rights Reserved
3  *
4  * Licensed under the Apache License, Version 2.0 (the License);
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an AS IS BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17
18 #ifndef __TTS_H__
19 #define __TTS_H__
20
21
22 #include <tizen.h>
23
24
25 /**
26 * @file tts.h
27 */
28
29
30 /**
31 * @addtogroup CAPI_UIX_TTS_MODULE
32 * @{
33 */
34
35
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39
40
41 /**
42  * @brief Enumeration for error code.
43  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
44 */
45 typedef enum {
46         TTS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
47         TTS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of Memory */
48         TTS_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< I/O error */
49         TTS_ERROR_INVALID_PARAMETER     = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
50         TTS_ERROR_OUT_OF_NETWORK = TIZEN_ERROR_NETWORK_DOWN, /**< Network is down */
51         TTS_ERROR_TIMED_OUT = TIZEN_ERROR_TIMED_OUT, /**< No answer from the daemon */
52         TTS_ERROR_PERMISSION_DENIED     = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
53         TTS_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< TTS NOT supported */
54         TTS_ERROR_INVALID_STATE = TIZEN_ERROR_TTS | 0x01, /**< Invalid state */
55         TTS_ERROR_INVALID_VOICE = TIZEN_ERROR_TTS | 0x02, /**< Invalid voice */
56         TTS_ERROR_ENGINE_NOT_FOUND = TIZEN_ERROR_TTS | 0x03, /**< No available engine */
57         TTS_ERROR_OPERATION_FAILED = TIZEN_ERROR_TTS | 0x04, /**< Operation failed */
58         TTS_ERROR_AUDIO_POLICY_BLOCKED = TIZEN_ERROR_TTS | 0x05, /**< Audio policy blocked */
59         TTS_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_TTS | 0x06, /**< Not supported feature of current engine @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
60         TTS_ERROR_SERVICE_RESET = TIZEN_ERROR_TTS | 0x07 /**< Service reset @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
61 } tts_error_e;
62
63
64 /**
65  * @brief Enumeration for TTS mode.
66  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
67 */
68 typedef enum {
69         TTS_MODE_DEFAULT = 0, /**< Default mode for normal application */
70         TTS_MODE_NOTIFICATION = 1, /**< Notification mode */
71         TTS_MODE_SCREEN_READER = 2 /**< Accessibiliity mode */
72 } tts_mode_e;
73
74
75 /**
76  * @brief Enumeration for state.
77  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
78 */
79 typedef enum {
80         TTS_STATE_CREATED = 0, /**< 'CREATED' state */
81         TTS_STATE_READY = 1, /**< 'READY' state */
82         TTS_STATE_PLAYING = 2, /**< 'PLAYING' state */
83         TTS_STATE_PAUSED = 3 /**< 'PAUSED' state*/
84 } tts_state_e;
85
86
87 /**
88  * @brief Definition for automatic speaking speed.
89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
90 */
91 #define TTS_SPEED_AUTO          0
92
93
94 /**
95  * @brief Definition for automatic voice type.
96  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
97 */
98 #define TTS_VOICE_TYPE_AUTO     0
99
100
101 /**
102  * @brief Definition for male voice type.
103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
104 */
105 #define TTS_VOICE_TYPE_MALE     1
106
107
108 /**
109  * @brief Definition for female voice type.
110  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
111 */
112 #define TTS_VOICE_TYPE_FEMALE   2
113
114
115 /**
116  * @brief Definition for child voice type.
117  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
118 */
119 #define TTS_VOICE_TYPE_CHILD    3
120
121
122 /**
123  * @brief The TTS handle.
124  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
125 */
126 typedef struct tts_s *tts_h;
127
128
129 /**
130  * @brief Called when the state of TTS is changed.
131  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
132  * @details If the daemon must stop player because of changing engine and
133  *          the daemon must pause player because of other requests, this callback function is called.
134  * @param[in] tts The TTS handle
135  * @param[in] previous The previous state
136  * @param[in] current The current state
137  * @param[in] user_data The user data passed from the callback registration function
138  * @pre An application registers this callback using tts_set_state_changed_cb() to detect changing state.
139  * @see tts_set_state_changed_cb()
140  * @see tts_unset_state_changed_cb()
141 */
142 typedef void (*tts_state_changed_cb)(tts_h tts, tts_state_e previous, tts_state_e current, void* user_data);
143
144
145 /**
146  * @brief Called when utterance has started.
147  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
148  * @param[in] tts The TTS handle
149  * @param[in] utt_id The utterance ID passed from the add text function
150  * @param[in] user_data The user data passed from the callback registration function
151  * @pre An application registers this callback using tts_set_utterance_started_cb() to detect utterance started.
152  * @see tts_add_text()
153  * @see tts_set_utterance_started_cb()
154  * @see tts_unset_utterance_started_cb()
155 */
156 typedef void (*tts_utterance_started_cb)(tts_h tts, int utt_id, void* user_data);
157
158
159 /**
160  * @brief Called when utterance is finished.
161  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
162  * @param[in] tts The TTS handle
163  * @param[in] utt_id The utterance ID passed from the add text function
164  * @param[in] user_data The user data passed from the callback registration function
165  * @pre An application registers this callback using tts_set_utterance_completed_cb() to detect utterance completed.
166  * @see tts_add_text()
167  * @see tts_set_utterance_completed_cb()
168  * @see tts_unset_utterance_completed_cb()
169 */
170 typedef void (*tts_utterance_completed_cb)(tts_h tts, int utt_id, void *user_data);
171
172
173 /**
174  * @brief Called when an error occurs.
175  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
176  * @param[in] tts The TTS handle
177  * @param[in] utt_id The utterance ID passed from the add text function
178  * @param[in] reason The error code
179  * @param[in] user_data The user data passed from the callback registration function
180  * @pre An application registers this callback using tts_set_error_cb() to detect error.
181  * @see tts_play()
182  * @see tts_pause()
183  * @see tts_stop()
184  * @see tts_set_error_cb()
185  * @see tts_unset_error_cb()
186 */
187 typedef void (*tts_error_cb)(tts_h tts, int utt_id, tts_error_e reason, void* user_data);
188
189
190 /**
191  * @brief Called to retrieve the supported voice.
192  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
193  * @param[in] tts The TTS handle
194  * @param[in] language Language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English)
195  * @param[in] voice_type A voice type (e.g. #TTS_VOICE_TYPE_MALE, #TTS_VOICE_TYPE_FEMALE)
196  * @param[in] user_data The user data passed from the foreach function
197  * @return @c true to continue with the next iteration of the loop,
198  *         @c false to break out of the loop
199  * @pre tts_foreach_supported_voices() will invoke this callback function.
200  * @see tts_foreach_supported_voices()
201 */
202 typedef bool(*tts_supported_voice_cb)(tts_h tts, const char* language, int voice_type, void* user_data);
203
204
205 /**
206  * @brief Called when the default voice is changed.
207  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
208  * @param[in] tts The TTS handle
209  * @param[in] previous_language The previous language
210  * @param[in] previous_voice_type The previous voice type
211  * @param[in] current_language The current language
212  * @param[in] current_voice_type The current voice type
213  * @param[in] user_data The user data passed from the callback registration function
214  * @see tts_set_default_voice_changed_cb()
215 */
216 typedef void (*tts_default_voice_changed_cb)(tts_h tts, const char* previous_language, int previous_voice_type,
217                                 const char* current_language, int current_voice_type, void* user_data);
218
219
220 /**
221  * @brief Called when the engine is changed.
222  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
223  * @param[in] tts The TTS handle
224  * @param[in] engine_id Engine ID
225  * @param[in] language The default language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English)
226  * @param[in] voice_type The default voice type
227  * @param[in] need_credential The necessity of credential
228  * @param[in] user_data The user data passed from the callback registration function
229  * @see tts_set_engine_changed_cb()
230 */
231 typedef void (*tts_engine_changed_cb)(tts_h tts, const char* engine_id, const char* language, int voice_type, bool need_credential, void* user_data);
232
233
234 /**
235  * @brief Creates a handle for TTS.
236  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
237  * @remarks If the function succeeds, @a tts handle must be released with tts_destroy().
238  * @param[out] tts The TTS handle
239  * @return @c 0 on success, 
240  *         otherwise a negative error value
241  * @retval #TTS_ERROR_NONE Successful
242  * @retval #TTS_ERROR_OUT_OF_MEMORY Out of memory
243  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
244  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
245  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
246  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
247  * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
248  * @see tts_destroy()
249 */
250 int tts_create(tts_h* tts);
251
252
253 /**
254  * @brief Destroys the handle and disconnects the daemon.
255  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
256  * @param[in] tts The TTS handle
257  * @return @c 0 on success, 
258  *         otherwise a negative error value
259  * @retval #TTS_ERROR_NONE Successful
260  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
261  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
262  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
263  * @see tts_create()
264 */
265 int tts_destroy(tts_h tts);
266
267
268 /**
269  * @brief Sets the TTS mode.
270  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
271  * @param[in] tts The TTS handle
272  * @param[in] mode The mode
273  * @return @c 0 on success, 
274  *         otherwise a negative error value
275  * @retval #TTS_ERROR_NONE Successful
276  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
277  * @retval #TTS_ERROR_INVALID_STATE Invalid state
278  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
279  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
280  * @pre The state should be #TTS_STATE_CREATED.
281  * @see tts_get_mode()
282 */
283 int tts_set_mode(tts_h tts, tts_mode_e mode);
284
285
286 /**
287  * @brief Gets the TTS mode.
288  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
289  * @param[in] tts The TTS handle
290  * @param[out] mode The mode
291  * @return @c 0 on success, 
292  *         otherwise a negative error value
293  * @retval #TTS_ERROR_NONE Successful
294  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
295  * @retval #TTS_ERROR_INVALID_STATE Invalid state
296  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
297  * @pre The state should be #TTS_STATE_CREATED.
298  * @see tts_set_mode()
299 */
300 int tts_get_mode(tts_h tts, tts_mode_e* mode);
301
302
303 /**
304  * @brief Sets the app credential.
305  * @details Using this API, the application can set a credential.
306  *          The credential is a key to verify the authorization about using the engine.
307  *          If the application sets the credential, it will be able to use functions of the engine entirely.
308  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
309  * @remarks The necessity of the credential depends on the engine. In case of the engine which is basically embedded in Tizen, the credential is not necessary so far.
310  *          However, if the user wants to apply the 3rd party's engine, the credential may be necessary. In that case, please follow the policy provided by the corresponding engine.
311  * @param[in] tts The TTS handle
312  * @param[in] credential The app credential
313  * @return @c 0 on success, 
314  *         otherwise a negative error value
315  * @retval #TTS_ERROR_NONE Success
316  * @retval #TTS_ERROR_INVALID_STATE Invalid state
317  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
318  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
319  * @pre The state should be #TTS_STATE_CREATED or #TTS_STATE_READY.
320  * @see tts_play()
321 */
322 int tts_set_credential(tts_h tts, const char* credential);
323
324
325 /**
326  * @brief Connects the daemon asynchronously.
327  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
328  * @param[in] tts The TTS handle
329  * @return @c 0 on success, 
330  *         otherwise a negative error value
331  * @retval #TTS_ERROR_NONE Successful
332  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
333  * @retval #TTS_ERROR_INVALID_STATE Invalid state
334  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
335  * @pre The state should be #TTS_STATE_CREATED.
336  * @post If this function is successful, the TTS state will be #TTS_STATE_READY.
337  *       If this function is failed, the error callback is called. (e.g. #TTS_ERROR_ENGINE_NOT_FOUND)
338  * @see tts_unprepare()
339 */
340 int tts_prepare(tts_h tts);
341
342
343 /**
344  * @brief Disconnects the daemon.
345  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
346  * @param[in] tts The TTS handle
347  * @return @c 0 on success, 
348  *         otherwise a negative error value
349  * @retval #TTS_ERROR_NONE Successful
350  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
351  * @retval #TTS_ERROR_INVALID_STATE Invalid state
352  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
353  * @pre The state should be #TTS_STATE_READY.
354  * @post If this function is called, the TTS state will be #TTS_STATE_CREATED.
355  * @see tts_prepare()
356 */
357 int tts_unprepare(tts_h tts);
358
359
360 /**
361  * @brief Retrieves all supported voices of the current engine using callback function.
362  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
363  * @param[in] tts The TTS handle
364  * @param[in] callback The callback function to invoke
365  * @param[in] user_data The user data to be passed to the callback function
366  * @return @c 0 on success, 
367  *         otherwise a negative error value
368  * @retval #TTS_ERROR_NONE Successful
369  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
370  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
371  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
372  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
373  * @post This function invokes tts_supported_voice_cb() repeatedly for getting voices.
374  * @see tts_get_default_voice()
375 */
376 int tts_foreach_supported_voices(tts_h tts, tts_supported_voice_cb callback, void* user_data);
377
378
379 /**
380  * @brief Gets the default voice set by the user.
381  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
382  * @remarks If the function succeeds, @a language must be released with free().
383  * @param[in] tts The TTS handle
384  * @param[out] language Language specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code (for example, "ko_KR" for Korean, "en_US" for American English)
385  * @param[out] voice_type The voice type
386  * @return @c 0 on success, 
387  *         otherwise a negative error value
388  * @retval #TTS_ERROR_NONE Successful
389  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
390  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
391  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
392  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
393  * @see tts_foreach_supported_voices()
394 */
395 int tts_get_default_voice(tts_h tts, char** language, int* voice_type);
396
397
398 /**
399  * @brief Sets the private data to tts engine.
400  * @details The private data is the setting parameter for applying keys provided by the engine.
401  *          Using this API, the application can set the private data and use the corresponding key of the engine.
402  *          For example, if the engine provides 'girl's voice' as a voice type, the application can set the private data as the following.
403  *          int ret = tts_set_private_data(tts_h, "voice_type", "GIRL");
404  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
405  * @remarks If the engine is replaced with the other engine, the key may be ignored.
406  * @param[in] tts The TTS handle
407  * @param[in] key The field name of private data
408  * @param[in] data The data for set
409  * @return @c 0 on success, 
410  *         otherwise a negative error value
411  * @retval #TTS_ERROR_NONE Successful
412  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
413  * @retval #TTS_ERROR_INVALID_STATE Invalid state
414  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
415  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
416  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
417  * @pre The state should be #TTS_STATE_READY.
418  * @see tts_get_private_data()
419 */
420 int tts_set_private_data(tts_h tts, const char* key, const char* data);
421
422
423 /**
424  * @brief Gets the private data from tts engine.
425  * @details The private data is the information provided by the engine.
426  *          Using this API, the application can get the private data which corresponds to the key from the engine.
427  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
428  * @remarks The @a data must be released using free() when it is no longer required.
429  *          If the engine is replaced with the other engine, the key may be ignored.
430  * @param[in] tts The TTS handle
431  * @param[in] key The field name of private data
432  * @param[out] data The data field of private data
433  * @return @c 0 on success, 
434  *         otherwise a negative error value
435  * @retval #TTS_ERROR_NONE Successful
436  * @retval #TTS_ERROR_INVALID_STATE Invalid state
437  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
438  * @retval #TTS_ERROR_ENGINE_NOT_FOUND Engine not found
439  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
440  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
441  * @pre The state should be #TTS_STATE_READY.
442  * @see tts_set_private_data()
443 */
444 int tts_get_private_data(tts_h tts, const char* key, char** data);
445
446
447 /**
448  * @brief Gets the maximum byte size for text.
449  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
450  * @param[in] tts The TTS handle
451  * @param[out] size The maximum byte size for text
452  * @return @c 0 on success, 
453  *         otherwise a negative error value
454  * @retval #TTS_ERROR_NONE Successful
455  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
456  * @retval #TTS_ERROR_INVALID_STATE Invalid state
457  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
458  * @pre The state should be #TTS_STATE_READY.
459  * @see tts_add_text()
460 */
461 int tts_get_max_text_size(tts_h tts, unsigned int* size);
462
463
464 /**
465  * @brief Gets the current state of TTS.
466  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
467  * @param[in] tts The TTS handle
468  * @param[out] state The current state of TTS
469  * @return @c 0 on success, 
470  *         otherwise a negative error value
471  * @retval #TTS_ERROR_NONE Successful
472  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
473  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
474  * @see tts_play()
475  * @see tts_stop()
476  * @see tts_pause()
477 */
478 int tts_get_state(tts_h tts, tts_state_e* state);
479
480
481 /**
482  * @brief Gets the speed range.
483  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
484  * @param[in] tts The TTS handle
485  * @param[out] min The minimum speed value
486  * @param[out] normal The normal speed value
487  * @param[out] max The maximum speed value
488  * @return @c 0 on success, 
489  *         otherwise a negative error value
490  * @retval #TTS_ERROR_NONE Successful
491  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
492  * @retval #TTS_ERROR_INVALID_STATE Invalid state
493  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
494  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
495  * @pre The state should be #TTS_STATE_CREATED.
496  * @see tts_add_text()
497 */
498 int tts_get_speed_range(tts_h tts, int* min, int* normal, int* max);
499
500
501 /**
502  * @brief Gets the current error message.
503  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
504  * @remarks This function should be called from a tts error callback. Calling in any other context will result in an Operation failed error.
505  *          A successful call will allocate @a err_msg, which must be released by calling free() when it is no longer required.
506  * @param[in] tts The TTS handle
507  * @param[out] err_msg The current error message
508  * @return @c 0 on success, 
509  *         otherwise a negative error value
510  * @retval #TTS_ERROR_NONE Successful
511  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
512  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
513  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
514  * @see tts_set_error_cb()
515  * @see tts_unset_error_cb()
516 */
517 int tts_get_error_message(tts_h tts, char** err_msg);
518
519
520 /**
521  * @brief Adds a text to the queue.
522  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
523  * @remarks Locale(e.g. setlocale()) MUST be set for utf8 text validation check.
524  * @param[in] tts The TTS handle
525  * @param[in] text An input text based utf8
526  * @param[in] language The language selected from the tts_foreach_supported_voices() (e.g. 'NULL'(Automatic), 'en_US')
527  * @param[in] voice_type The voice type selected from the tts_foreach_supported_voices() (e.g. #TTS_VOICE_TYPE_AUTO, #TTS_VOICE_TYPE_FEMALE)
528  * @param[in] speed A speaking speed (e.g. #TTS_SPEED_AUTO or the value from tts_get_speed_range())
529  * @param[out] utt_id The utterance ID passed to the callback function
530  * @return @c 0 on success, 
531  *         otherwise a negative error value
532  * @retval #TTS_ERROR_NONE Successful
533  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
534  * @retval #TTS_ERROR_INVALID_STATE Invalid state
535  * @retval #TTS_ERROR_INVALID_VOICE Invalid voice about language, voice type
536  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
537  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
538  * @retval #TTS_ERROR_PERMISSION_DENIED Permission denied
539  * @pre The state should be #TTS_STATE_READY, #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
540  * @see tts_get_max_text_size()
541  * @see tts_set_credential()
542 */
543 int tts_add_text(tts_h tts, const char* text, const char* language, int voice_type, int speed, int* utt_id);
544
545
546 /**
547  * @brief Starts synthesizing voice from the text and plays the synthesized audio data.
548  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
549  * @param[in] tts The TTS handle
550  * @return @c 0 on success, 
551  *         otherwise a negative error value
552  * @retval #TTS_ERROR_NONE Successful
553  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
554  * @retval #TTS_ERROR_OUT_OF_NETWORK Out of network
555  * @retval #TTS_ERROR_INVALID_STATE Invalid state
556  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
557  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
558  * @retval #TTS_ERROR_PERMISSION_DENIED Permission denied
559  * @pre The current state should be #TTS_STATE_READY or #TTS_STATE_PAUSED.
560  * @post If this function succeeds, the TTS state will be #TTS_STATE_PLAYING.
561  * @see tts_add_text()
562  * @see tts_pause()
563  * @see tts_stop()
564  * @see tts_utterance_started_cb()
565  * @see tts_utterance_completed_cb()
566  * @see tts_error_cb()
567  * @see tts_set_credential()
568 */
569 int tts_play(tts_h tts);
570
571
572 /**
573  * @brief Stops playing the utterance and clears the queue.
574  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
575  * @param[in] tts The TTS handle
576  * @return @c 0 on success, 
577  *         otherwise a negative error value
578  * @retval #TTS_ERROR_NONE Successful
579  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
580  * @retval #TTS_ERROR_INVALID_STATE Invalid state
581  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
582  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
583  * @pre The TTS state should be #TTS_STATE_READY or #TTS_STATE_PLAYING or #TTS_STATE_PAUSED.
584  * @post If this function succeeds, the TTS state will be #TTS_STATE_READY.
585  *       This function will remove all text via tts_add_text() and synthesized sound data.
586  * @see tts_play()
587  * @see tts_pause()
588 */
589 int tts_stop(tts_h tts);
590
591
592 /**
593  * @brief Pauses the currently playing utterance.
594  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
595  * @param[in] tts The TTS handle
596  * @return @c 0 on success, 
597  *         otherwise a negative error value
598  * @retval #TTS_ERROR_NONE Successful
599  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
600  * @retval #TTS_ERROR_INVALID_STATE Invalid state
601  * @retval #TTS_ERROR_OPERATION_FAILED Operation failure
602  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
603  * @pre The TTS state should be #TTS_STATE_PLAYING.
604  * @post If this function succeeds, the TTS state will be #TTS_STATE_PAUSED.
605  * @see tts_play()
606  * @see tts_stop()
607  * @see tts_error_cb()
608  * @see tts_interrupted_cb()
609 */
610 int tts_pause(tts_h tts);
611
612
613 /**
614  * @brief Registers a callback function to be called when the TTS state changes.
615  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
616  * @param[in] tts The TTS handle
617  * @param[in] callback The callback function to register
618  * @param[in] user_data The user data to be passed to the callback function
619  * @return @c 0 on success, 
620  *         otherwise a negative error value
621  * @retval #TTS_ERROR_NONE Successful
622  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
623  * @retval #TTS_ERROR_INVALID_STATE Invalid state
624  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
625  * @pre The state should be #TTS_STATE_CREATED.
626  * @see tts_state_changed_cb()
627  * @see tts_unset_state_changed_cb()
628 */
629 int tts_set_state_changed_cb(tts_h tts, tts_state_changed_cb callback, void* user_data);
630
631
632 /**
633  * @brief Unregisters the callback function.
634  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
635  * @param[in] tts The TTS handle
636  * @return @c 0 on success, 
637  *         otherwise a negative error value
638  * @retval #TTS_ERROR_NONE Successful
639  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
640  * @retval #TTS_ERROR_INVALID_STATE Invalid state
641  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
642  * @pre The state should be #TTS_STATE_CREATED.
643  * @see tts_set_state_changed_cb()
644 */
645 int tts_unset_state_changed_cb(tts_h tts);
646
647
648 /**
649  * @brief Registers a callback function to detect utterance start.
650  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
651  * @param[in] tts The TTS handle
652  * @param[in] callback The callback function to register
653  * @param[in] user_data The user data to be passed to the callback function
654  * @return @c 0 on success, 
655  *         otherwise a negative error value
656  * @retval #TTS_ERROR_NONE Successful
657  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
658  * @retval #TTS_ERROR_INVALID_STATE Invalid state
659  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
660  * @pre The state should be #TTS_STATE_CREATED.
661  * @see tts_utterance_started_cb()
662  * @see tts_unset_utterance_started_cb()
663 */
664 int tts_set_utterance_started_cb(tts_h tts, tts_utterance_started_cb callback, void* user_data);
665
666
667 /**
668  * @brief Unregisters the callback function.
669  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
670  * @param[in] tts The TTS handle
671  * @return @c 0 on success, 
672  *         otherwise a negative error value
673  * @retval #TTS_ERROR_NONE Successful
674  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
675  * @retval #TTS_ERROR_INVALID_STATE Invalid state
676  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
677  * @pre The state should be #TTS_STATE_CREATED.
678  * @see tts_set_utterance_started_cb()
679 */
680 int tts_unset_utterance_started_cb(tts_h tts);
681
682
683 /**
684  * @brief Registers a callback function to detect utterance completion.
685  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
686  * @param[in] tts The TTS handle
687  * @param[in] callback The callback function to register
688  * @param[in] user_data The user data to be passed to the callback function
689  * @return @c 0 on success, 
690  *         otherwise a negative error value
691  * @retval #TTS_ERROR_NONE Successful
692  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
693  * @retval #TTS_ERROR_INVALID_STATE Invalid state
694  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
695  * @pre The state should be #TTS_STATE_CREATED.
696  * @see tts_utterance_completed_cb()
697  * @see tts_unset_utterance_completed_cb()
698 */
699 int tts_set_utterance_completed_cb(tts_h tts, tts_utterance_completed_cb callback, void* user_data);
700
701
702 /**
703  * @brief Unregisters the callback function.
704  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
705  * @param[in] tts The TTS handle
706  * @return @c 0 on success, 
707  *         otherwise a negative error value
708  * @retval #TTS_ERROR_NONE Successful
709  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
710  * @retval #TTS_ERROR_INVALID_STATE Invalid state
711  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
712  * @pre The state should be #TTS_STATE_CREATED.
713  * @see tts_set_utterance_completed_cb()
714 */
715 int tts_unset_utterance_completed_cb(tts_h tts);
716
717
718 /**
719  * @brief Registers a callback function to detect errors.
720  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
721  * @param[in] tts The TTS handle
722  * @param[in] callback The callback function to register
723  * @param[in] user_data The user data to be passed to the callback function
724  * @return @c 0 on success, 
725  *         otherwise a negative error value
726  * @retval #TTS_ERROR_NONE Successful
727  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
728  * @retval #TTS_ERROR_INVALID_STATE Invalid state
729  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
730  * @pre The state should be #TTS_STATE_CREATED.
731  * @see tts_error_cb()
732  * @see tts_unset_error_cb()
733 */
734 int tts_set_error_cb(tts_h tts, tts_error_cb callback, void* user_data);
735
736
737 /**
738  * @brief Unregisters the callback function.
739  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
740  * @param[in] tts The TTS handle
741  * @return @c 0 on success, 
742  *         otherwise a negative error value
743  * @retval #TTS_ERROR_NONE Successful
744  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
745  * @retval #TTS_ERROR_INVALID_STATE Invalid state
746  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
747  * @pre The state should be #TTS_STATE_CREATED.
748  * @see tts_set_error_cb()
749 */
750 int tts_unset_error_cb(tts_h tts);
751
752
753 /**
754  * @brief Registers a callback function to detect default voice change.
755  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
756  * @param[in] tts The TTS handle
757  * @param[in] callback The callback function to register
758  * @param[in] user_data The user data to be passed to the callback function
759  * @return @c 0 on success, 
760  *         otherwise a negative error value
761  * @retval #TTS_ERROR_NONE Successful
762  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
763  * @retval #TTS_ERROR_INVALID_STATE Invalid state
764  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
765  * @pre The state should be #TTS_STATE_CREATED.
766  * @see tts_default_voice_changed_cb()
767  * @see tts_unset_default_voice_changed_cb()
768 */
769 int tts_set_default_voice_changed_cb(tts_h tts, tts_default_voice_changed_cb callback, void* user_data);
770
771
772 /**
773  * @brief Unregisters the callback function.
774  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
775  * @param[in] tts The TTS handle
776  * @return @c 0 on success, 
777  *         otherwise a negative error value
778  * @retval #TTS_ERROR_NONE Successful
779  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
780  * @retval #TTS_ERROR_INVALID_STATE Invalid state
781  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
782  * @pre The state should be #TTS_STATE_CREATED.
783  * @see tts_set_default_voice_changed_cb()
784 */
785 int tts_unset_default_voice_changed_cb(tts_h tts);
786
787
788  /**
789  * @brief Registers a callback function to detect the engine change.
790  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
791  * @param[in] tts The TTS handle
792  * @param[in] callback The callback function to register
793  * @param[in] user_data The user data to be passed to the callback function
794  * @return @c 0 on success, 
795  *         otherwise a negative error value
796  * @retval #TTS_ERROR_NONE Successful
797  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
798  * @retval #TTS_ERROR_INVALID_STATE Invalid state
799  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
800  * @pre The state should be #TTS_STATE_CREATED.
801  * @see tts_engine_changed_cb()
802  * @see tts_unset_engine_changed_cb()
803 */
804 int tts_set_engine_changed_cb(tts_h tts, tts_engine_changed_cb callback, void* user_data);
805
806
807 /**
808  * @brief Unregisters the callback function.
809  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
810  * @param[in] tts The TTS handle
811  * @return @c 0 on success, 
812  *         otherwise a negative error value
813  * @retval #TTS_ERROR_NONE Successful
814  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
815  * @retval #TTS_ERROR_INVALID_STATE Invalid state
816  * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
817  * @pre The state should be #TTS_STATE_CREATED.
818  * @see tts_set_engine_changed_cb()
819 */
820 int tts_unset_engine_changed_cb(tts_h tts);
821
822
823 #ifdef __cplusplus
824 }
825 #endif
826
827
828 /**
829  * @}@}
830  */
831
832
833 #endif  /* __TTS_H__ */