Add codes in client side to set/unset callback for retrieving sythesized pcm data

[platform/core/uifw/tts.git] / include / ttse.h

diff --git a/include/ttse.h b/include/ttse.h
index a9e5e7b..32c52a2 100755 (executable)
--- a/include/ttse.h
+++ b/include/ttse.h
@@ -71,6 +71,17 @@ typedef enum {
        TTSE_RESULT_EVENT_FINISH = 3 /**< Event when the sound data is last data or sound data is only one result */
 } ttse_result_event_e;
 
+/**
+* @brief Enumeration for TTS mode mask.
+* @since_tizen 7.0
+*/
+typedef enum {
+       TTSE_MODE_MASK_DEFAULT = 0x01, /**< Default mode */
+       TTSE_MODE_MASK_NOTIFICATION = 0x02, /**< Notification mode */
+       TTSE_MODE_MASK_SCREEN_READER = 0x04, /**< Screen reader mode */
+       TTSE_MODE_MASK_INTERRUPT = 0x08 /**< Interrupt mode */
+} ttse_mode_mask_e;
+
 
 /**
 * @brief Definition for male voice type.
@@ -103,7 +114,7 @@ typedef enum {
 *                     For example, "ko_KR" for Korean, "en_US" for American English
 * @param[in] type The voice type
 * @param[in] user_data The user data passed from ttse_foreach_supported_voices_cb()
-* @return @c true to continue with the next iteration of the loop 
+* @return @c true to continue with the next iteration of the loop
 *         @c false to break out of the loop
 * @pre ttse_foreach_supported_voices_cb() will invoke this callback function.
 * @see ttse_foreach_supported_voices_cb()
@@ -115,7 +126,7 @@ typedef bool (*ttse_supported_voice_cb)(const char* language, int type, void* us
 * @brief Called when the engine service user initializes TTS engine.
 * @since_tizen 3.0
 * @remarks This callback function is mandatory and must be registered using ttse_main().
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -133,7 +144,7 @@ typedef int (*ttse_initialize_cb)(void);
 * @remarks This callback function is mandatory and must be registered using ttse_main().
 *          NOTE that the engine may be terminated automatically.
 *          When this callback function is invoked, the release of resources is necessary.
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
@@ -150,7 +161,7 @@ typedef int (*ttse_deinitialize_cb)(void);
 *          If 'ttse_supported_voice_cb()' returns @c false, it should be stopped to call 'ttse_supported_voice_cb()'.
 * @param[in] callback The callback function
 * @param[in] user_data The user data which must be passed to ttse_supported_voice_cb()
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -169,10 +180,10 @@ typedef int (*ttse_foreach_supported_voices_cb)(ttse_supported_voice_cb callback
 *                     followed by ISO 639-1 for the two-letter language code.
 *                     For example, "ko_KR" for Korean, "en_US" for American English
 * @param[in] type The voice type
-* @param[out] is_valid A variable for checking whether the corresponding voice is valid or not. 
+* @param[out] is_valid A variable for checking whether the corresponding voice is valid or not.
 *                      @c true to be valid,
 *                      @c false to be invalid
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -186,7 +197,7 @@ typedef int (*ttse_is_valid_voice_cb)(const char* language, int type, bool* is_v
 * @since_tizen 3.0
 * @remarks This callback function is mandatory and must be registered using ttse_main().
 * @param[in] pitch The default pitch
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -204,7 +215,7 @@ typedef int (*ttse_set_pitch_cb)(int pitch);
 *                     followed by ISO 639-1 for the two-letter language code.
 *                     For example, "ko_KR" for Korean, "en_US" for American English
 * @param[in] type The voice type
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -225,7 +236,7 @@ typedef int (*ttse_load_voice_cb)(const char* language, int type);
 *                     followed by ISO 639-1 for the two-letter language code.
 *                     For example, "ko_KR" for Korean, "en_US" for American English
 * @param[in] type The voice type
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -249,7 +260,7 @@ typedef int (*ttse_unload_voice_cb)(const char* language, int type);
 * @param[out] is_agreed A variable for checking whether the application agreed to use TTS engine or not.
 *                       @c true to agree,
 *                       @c false to disagree
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_STATE Not initialized
@@ -284,7 +295,7 @@ typedef bool (*ttse_need_app_credential_cb)(void);
 * @param[in] appid The Application ID
 * @param[in] credential The credential granted to the application
 * @param[in] user_data The user data which must be passed to ttse_send_result()
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -305,7 +316,7 @@ typedef int (*ttse_start_synthesis_cb)(const char* language, int type, const cha
 * @brief Called when the engine service user cancels to synthesize a voice.
 * @since_tizen 3.0
 * @remarks This callback function is mandatory and must be registered using ttse_main().
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_STATE Not initialized or not started synthesis
@@ -326,7 +337,7 @@ typedef int (*ttse_cancel_synthesis_cb)(void);
 * @param[out] engine_name Name of engine
 * @param[out] engine_setting The engine setting application(ui app)'s app ID
 * @param[out] use_network The status for using network
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error code on failure
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -342,7 +353,7 @@ typedef int (*ttse_get_info_cb)(char** engine_uuid, char** engine_name, char** e
 * @remarks This callback function is optional and is registered using ttse_set_private_data_set_cb().
 * @param[in] key The key field of private data
 * @param[in] data The data field of private data
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -361,7 +372,7 @@ typedef int (*ttse_private_data_set_cb)(const char* key, const char* data);
 * @remarks This callback function is optional and is registered using ttse_set_private_data_requested_cb().
 * @param[out] key The key field of private data
 * @param[out] data The data field of private data
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -374,6 +385,23 @@ typedef int (*ttse_private_data_requested_cb)(const char* key, char** data);
 
 
 /**
+* @brief Called when activated modes are changed.
+* @details When a client connects to TTS engine, the engine activates the TTS mode of the client.
+*          For example, if two clients, one is default mode and other is screen reader mode, connect to TTS engine, then the
+*          @a activated_mode has the same bit sequence as '#TTSE_MODE_MASK_DEFAULT | #TTSE_MODE_MASK_SCREEN_READER'.
+*          The activated TTS modes are decided according to the connected clients, so when a client connects or disconnects to
+*          the engine, the activated TTS modes may be changed.
+*          This callback function is called when the activated TTS modes are changed.
+* @since_tizen 7.0
+* @remarks This callback function is optional and is registered using ttse_set_activated_mode_changed_cb().
+* @param[in] activated_mode The activated TTS modes by connected clients, values of ttse_mode_mask_e combined with bitwise 'or'.
+* @see ttse_set_activated_mode_changed_cb()
+* @see ttse_get_activated_mode()
+*/
+typedef void (*ttse_activated_mode_changed_cb)(int activated_mode);
+
+
+/**
 * @brief A structure for the TTS engine functions.
 * @details This structure contains essential callback functions for operating TTS engine.
 * @since_tizen 3.0
@@ -409,7 +437,7 @@ typedef struct {
 * @param[in] argc The argument count(original)
 * @param[in] argv The argument(original)
 * @param[in] callback The structure of engine request callback function
-* @return This function returns zero on success, 
+* @return This function returns zero on success,
 *         or negative with error code on failure
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -488,13 +516,26 @@ int ttse_main(int argc, char** argv, ttse_request_callback_s *callback);
 
 
 /**
+* @brief Terminates the main function of TTS engine.
+* @since_tizen 7.0
+* @remarks This function invokes ttse_deinitialize_cb() in #ttse_request_callback_s which is registered by ttse_main().
+*          And this function should be called before terminating the engine to ensure safe termination.
+* @return @c 0 on success,
+*         otherwise a negative error value
+* @retval #TTSE_ERROR_NONE Successful
+* @retval #TTSE_ERROR_OPERATION_FAILED Operation failure
+*/
+int ttse_terminate(void);
+
+
+/**
 * @brief Gets the speed range from Tizen platform.
 * @since_tizen 3.0
 * @remarks This API is used when TTS engine wants to get the speed range from Tizen platform.
 * @param[out] min The minimum speed value
 * @param[out] normal The normal speed value
 * @param[out] max The maximum speed value
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -511,7 +552,7 @@ int ttse_get_speed_range(int* min, int* normal, int* max);
 * @param[out] min The minimum pitch value
 * @param[out] normal The normal pitch value
 * @param[out] max The maximum pitch value
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -532,7 +573,7 @@ int ttse_get_pitch_range(int* min, int* normal, int* max);
 * @param[in] audio_type The audio type
 * @param[in] rate The sample rate
 * @param[in] user_data The user data passed from ttse_start_synthesis_cb()
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -563,7 +604,7 @@ int ttse_send_result(ttse_result_event_e event, const void* data, unsigned int d
 * @since_tizen 3.0
 * @param[in] error The error reason
 * @param[in] msg The error message
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -579,7 +620,7 @@ int ttse_send_error(ttse_error_e error, const char* msg);
 * @since_tizen 3.0
 * @remarks The ttse_private_data_set_cb() function is called when the engine service user sends the private data.
 * @param[in] callback_func ttse_private_data_set event callback function
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -596,7 +637,7 @@ int ttse_set_private_data_set_cb(ttse_private_data_set_cb callback_func);
 * @since_tizen 3.0
 * @remarks The ttse_private_data_requested_cb() function is called when the engine service user gets the private data from TTS engine.
 * @param[in] callback_func ttse_private_data_requested event callback function
-* @return @c 0 on success, 
+* @return @c 0 on success,
 *         otherwise a negative error value
 * @retval #TTSE_ERROR_NONE Successful
 * @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
@@ -608,6 +649,44 @@ int ttse_set_private_data_set_cb(ttse_private_data_set_cb callback_func);
 int ttse_set_private_data_requested_cb(ttse_private_data_requested_cb callback_func);
 
 
+/**
+* @brief Gets activated modes.
+* @details When a client connects to TTS engine, the engine activates the TTS mode of the client.
+*          For example, if two clients, one is default mode and other is screen reader mode, connect to TTS engine, then the
+*          @a activated_mode has the same bit sequence as '#TTSE_MODE_MASK_DEFAULT | #TTSE_MODE_MASK_SCREEN_READER'.
+*          Using this API, the engine can get the activated TTS modes information.
+* @since_tizen 7.0
+* @param[out] activated_mode The activated TTS mode by connected clients, values of ttse_mode_mask_e combined with bitwise 'or'.
+* @return @c 0 on success,
+*         otherwise a negative error value
+* @retval #TTSE_ERROR_NONE Successful
+* @retval #TTSE_ERROR_NOT_SUPPORTED TTS NOT supported
+* @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
+* @retval #TTSE_ERROR_INVALID_STATE Not initialized
+* @pre The ttse_main() function should be invoked before this function is called.
+* @see ttse_set_activated_mode_changed_cb()
+*/
+int ttse_get_activated_mode(int* activated_mode);
+
+
+/**
+* @brief Sets a callback function to be called when the activated TTS modes are changed.
+* @since_tizen 7.0
+* @remarks The ttse_activated_mode_changed_cb() function is called when the activated TTS modes are changed.
+* @param[in] callback ttse_activated_mode_changed event callback function
+* @return @c 0 on success,
+*         otherwise a negative error value
+* @retval #TTSE_ERROR_NONE Successful
+* @retval #TTSE_ERROR_NOT_SUPPORTED TTS NOT supported
+* @retval #TTSE_ERROR_INVALID_PARAMETER Invalid parameter
+* @retval #TTSE_ERROR_INVALID_STATE Not initialized
+* @pre The ttse_main() function should be invoked before this function is called.
+* @see ttse_activated_mode_changed_cb()
+* @see ttse_get_activated_mode()
+*/
+int ttse_set_activated_mode_changed_cb(ttse_activated_mode_changed_cb callback);
+
+
 #ifdef __cplusplus
 }
 #endif