Add new APIs about service state information

- Requirement:
An application needs state of TTS service in order to check whether the
TTS service is able to handle the request of the application.

- Solution:
This patch adds new APIs for checking state of TTS service. Through
these new APIs, applications which use TTS can check the state of TTS
service and handle the TTS request according to the state of TTS
service.

Change-Id: I7fbbf3f9e316b91468423c26c38452383498cf34
Signed-off-by: Suyeon Hwang <stom.hwang@samsung.com>

diff --git a/client/tts.c b/client/tts.c
index 21469fa4e9aea20e967d7b2f672c049e90142aa0..94432c853a5c21d9463f119b1d74a48e1edf58ed 100644 (file)
--- a/client/tts.c
+++ b/client/tts.c
@@ -709,6 +709,23 @@ int tts_check_screen_reader_on(tts_h tts, bool* is_on)
        return TTS_ERROR_NONE;
 }
 
+int tts_get_service_state(tts_h tts, tts_service_state_e* service_state)
+{
+       RETV_IF(TTS_ERROR_NONE != __tts_get_feature_enabled(), TTS_ERROR_NOT_SUPPORTED);
+
+       RETVM_IF(NULL == service_state, TTS_ERROR_INVALID_PARAMETER, "[ERROR] Get service state : Input parameter is null");
+
+       tts_client_s* client = tts_client_get(tts);
+       RETVM_IF(NULL == client, TTS_ERROR_INVALID_PARAMETER, "[ERROR] A handle is not valid. tts(%p)", tts);
+
+       tts_state_e current_state = tts_client_get_current_state(client);
+       RETVM_IF(TTS_STATE_CREATED == current_state, TTS_ERROR_INVALID_STATE, "[ERROR] The current state(%d) is invalid", current_state);
+
+       // TODO: Implement business logic
+
+       return TTS_ERROR_NONE;
+}
+
 int tts_add_text(tts_h tts, const char* text, const char* language, int voice_type, int speed, int* utt_id)
 {
        RETV_IF(TTS_ERROR_NONE != __tts_get_feature_enabled(), TTS_ERROR_NOT_SUPPORTED);
@@ -1339,3 +1356,36 @@ int tts_repeat(tts_h tts, char** text_repeat, int* utt_id)
        SLOG(LOG_DEBUG, TAG_TTSC, "@@@");
        return TTS_ERROR_NONE;
 }
+
+int tts_set_service_state_changed_cb(tts_h tts, tts_service_state_changed_cb callback, void* user_data)
+{
+       RETV_IF(TTS_ERROR_NONE != __tts_get_feature_enabled(), TTS_ERROR_NOT_SUPPORTED);
+
+       tts_client_s* client = tts_client_get(tts);
+       RETVM_IF(NULL == client, TTS_ERROR_INVALID_PARAMETER, "[ERROR] A handle is not valid. tts(%p)", tts);
+       RETVM_IF(NULL == callback, TTS_ERROR_INVALID_PARAMETER, "[ERROR] Set service state changed cb : Input parameter is null");
+
+       tts_state_e current_state = tts_client_get_current_state(client);
+       RETVM_IF(TTS_STATE_CREATED != current_state, TTS_ERROR_INVALID_STATE, "[ERROR] The current state(%d) is invalid", current_state);
+
+       // TODO: Implement business logic
+
+       SLOG(LOG_INFO, TAG_TTSC, "[SUCCESS] Set service state changed cb");
+       return TTS_ERROR_NONE;
+}
+
+int tts_unset_service_state_changed_cb(tts_h tts)
+{
+       RETV_IF(TTS_ERROR_NONE != __tts_get_feature_enabled(), TTS_ERROR_NOT_SUPPORTED);
+
+       tts_client_s* client = tts_client_get(tts);
+       RETVM_IF(NULL == client, TTS_ERROR_INVALID_PARAMETER, "[ERROR] A handle is not valid. tts(%p)", tts);
+
+       tts_state_e current_state = tts_client_get_current_state(client);
+       RETVM_IF(TTS_STATE_CREATED != current_state, TTS_ERROR_INVALID_STATE, "[ERROR] The current state(%d) is invalid", current_state);
+
+       // TODO: Implement business logic
+
+       SLOG(LOG_DEBUG, TAG_TTSC, "[SUCCESS] Unset service state changed cb");
+       return TTS_ERROR_NONE;
+}

diff --git a/include/tts.h b/include/tts.h
index c421661e564c7bdc605bbfacaec98c404e640a4c..80e690ca9928b75c0fadadb46cfd92ef51e8d254 100644 (file)
--- a/include/tts.h
+++ b/include/tts.h
@@ -85,6 +85,17 @@ typedef enum {
 } tts_state_e;
 
 
+/**
+ * @brief Enumeration for service state.
+ * @since_tizen 7.0
+*/
+typedef enum {
+       TTS_SERVICE_STATE_READY = 0, /**< 'Ready' state */
+       TTS_SERVICE_STATE_SYNTHESIZING, /**< 'Synthesizing' state */
+       TTS_SERVICE_STATE_PLAYING /**< 'Playing' state */
+} tts_service_state_e;
+
+
 /**
  * @brief Definition for automatic speaking speed.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
@@ -242,6 +253,21 @@ typedef void (*tts_engine_changed_cb)(tts_h tts, const char* engine_id, const ch
 */
 typedef void (*tts_screen_reader_changed_cb)(tts_h tts, bool is_on, void* user_data);
 
+
+/**
+ * @brief Called when the state of TTS service is changed.
+ * @since_tizen 7.0
+ * @remarks The @a tts handle should not be destroyed in the callback.
+ * @param[in] tts The TTS handle, the same handle for which the callback was set.
+ * @param[in] previous The previous state of TTS service
+ * @param[in] current The current state of TTS service
+ * @param[in] user_data The user data passed from the callback registration function
+ * @pre An application registers this callback using tts_set_service_state_changed_cb() to detect changing state of TTS service.
+ * @see tts_set_service_state_changed_cb()
+ * @see tts_unset_service_state_changed_cb()
+*/
+typedef void (*tts_service_state_changed_cb)(tts_h tts, tts_service_state_e previous, tts_service_state_e current, void* user_data);
+
 /**
  * @brief Creates a handle for TTS.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
@@ -548,6 +574,25 @@ int tts_get_speed_range(tts_h tts, int* min, int* normal, int* max);
 int tts_get_error_message(tts_h tts, char** err_msg);
 
 
+/**
+ * @brief Gets the current state of TTS service.
+ * @since_tizen 7.0
+ * @param[in] tts The TTS handle
+ * @param[out] service_state The current state of TTS service
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #TTS_ERROR_NONE Successful
+ * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
+ * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #TTS_ERROR_INVALID_STATE Invalid state
+ * @pre The TTS state should be one of: #TTS_STATE_READY, #TTS_STATE_PLAYING, #TTS_STATE_PAUSED.
+ * @see tts_play()
+ * @see tts_stop()
+ * @see tts_pause()
+*/
+int tts_get_service_state(tts_h tts, tts_service_state_e* service_state);
+
+
 /**
  * @brief Checks whether screen reader is turned on or not.
  * @since_tizen 6.5
@@ -934,6 +979,39 @@ int tts_set_screen_reader_changed_cb(tts_h tts, tts_screen_reader_changed_cb cal
 */
 int tts_unset_screen_reader_changed_cb(tts_h tts);
 
+/**
+ * @brief Sets a callback function to be called when the TTS service state changes.
+ * @since_tizen 7.0
+ * @param[in] tts The TTS handle
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #TTS_ERROR_NONE Successful
+ * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
+ * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #TTS_ERROR_INVALID_STATE Invalid state
+ * @pre The TTS state should be #TTS_STATE_CREATED.
+ * @see tts_service_state_changed_cb()
+ * @see tts_unset_service_state_changed_cb()
+*/
+int tts_set_service_state_changed_cb(tts_h tts, tts_service_state_changed_cb callback, void* user_data);
+
+/**
+ * @brief Unsets the callback function.
+ * @since_tizen 7.0
+ * @param[in] tts The TTS handle
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ * @retval #TTS_ERROR_NONE Successful
+ * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
+ * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #TTS_ERROR_INVALID_STATE Invalid state
+ * @pre The TTS state should be #TTS_STATE_CREATED.
+ * @see tts_set_service_state_changed_cb()
+*/
+int tts_unset_service_state_changed_cb(tts_h tts);
+
 #ifdef __cplusplus
 }
 #endif