Add apis for setting/unsetting engine changed callbacks

Change-Id: Ied85272238bc0fd2240f536089c314b8eeacb1c9
Signed-off-by: sooyeon.kim <sooyeon.kim@samsung.com>

diff --git a/include/tts.h b/include/tts.h
index 71f99fb..acabc69 100644 (file)
--- a/include/tts.h
+++ b/include/tts.h
@@ -11,7 +11,7 @@
  * distributed under the License is distributed on an AS IS BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
- * limitations under the License. 
+ * limitations under the License.
  */
 
 
@@ -33,7 +33,7 @@
 extern "C" {
 #endif
 
-/** 
+/**
  * @brief Enumeration for error code.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
@@ -51,11 +51,11 @@ typedef enum {
        TTS_ERROR_ENGINE_NOT_FOUND      = TIZEN_ERROR_TTS | 0x03,       /**< No available engine */
        TTS_ERROR_OPERATION_FAILED      = TIZEN_ERROR_TTS | 0x04,       /**< Operation failed */
        TTS_ERROR_AUDIO_POLICY_BLOCKED  = TIZEN_ERROR_TTS | 0x05,       /**< Audio policy blocked */
-       TTS_ERROR_NOT_SUPPORTED_FEATURE = TIZEN_ERROR_TTS | 0x06,       /**< Not supported feature of current engine*/
-       TTS_ERROR_SERVICE_RESET         = TIZEN_ERROR_TTS | 0x07        /**< Service reset */
+       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 */
+       TTS_ERROR_SERVICE_RESET         = TIZEN_ERROR_TTS | 0x07        /**< Service reset @if MOBILE (Since 3.0) @elseif WEARABLE (Since 2.3.2) @endif */
 } tts_error_e;
 
-/** 
+/**
  * @brief Enumeration for TTS mode.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
@@ -65,7 +65,7 @@ typedef enum {
        TTS_MODE_SCREEN_READER  = 2     /**< Accessibiliity mode */
 } tts_mode_e;
 
-/** 
+/**
  * @brief Enumerations for state.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
@@ -76,37 +76,37 @@ typedef enum {
        TTS_STATE_PAUSED        = 3     /**< 'PAUSED' state*/
 } tts_state_e;
 
-/** 
+/**
  * @brief Definitions for automatic speaking speed.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
 #define TTS_SPEED_AUTO         0
 
-/** 
+/**
  * @brief Definitions for automatic voice type.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
 #define TTS_VOICE_TYPE_AUTO    0
 
-/** 
+/**
  * @brief Definitions for male voice type.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
 #define TTS_VOICE_TYPE_MALE    1
 
-/** 
+/**
  * @brief Definitions for female voice type.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
 #define TTS_VOICE_TYPE_FEMALE  2
 
-/** 
+/**
  * @brief Definitions for child voice type.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
 #define TTS_VOICE_TYPE_CHILD   3
 
-/** 
+/**
  * @brief The TTS handle.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 */
@@ -214,6 +214,20 @@ typedef bool(*tts_supported_voice_cb)(tts_h tts, const char* language, int voice
 */
 typedef void (*tts_default_voice_changed_cb)(tts_h tts, const char* previous_language, int previous_voice_type,
                                const char* current_language, int current_voice_type, void* user_data);
+/**
+ * @brief Called when the engine is changed.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ *
+ * @param[in] tts The TTS handle
+ * @param[in] engine_id Engine id
+ * @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)
+ * @param[in] voice_type The default voice type
+ * @param[in] need_credential The necessity of credential
+ * @param[in] user_data The user data passed from the callback registration function
+ *
+ * @see tts_set_engine_changed_cb()
+*/
+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);
 
 
 /**
@@ -295,8 +309,13 @@ int tts_get_mode(tts_h tts, tts_mode_e* mode);
 
 /**
  * @brief Sets the app credential.
- * @since_tizen 3.0
- * @privlevel public
+ * @details Using this API, the application can set a credential.
+ *  The credential is a key to verify the authorization about using the engine.
+ *  If the application sets the credential, it will be able to use functions of the engine entirely.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ *
+ * @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.
+ *  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.
  *
  * @param[in] tts The TTS handle
  * @param[in] credential The app credential
@@ -305,6 +324,7 @@ int tts_get_mode(tts_h tts, tts_mode_e* mode);
  * @retval #TTS_ERROR_NONE Success
  * @retval #TTS_ERROR_INVALID_STATE Invalid state
  * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
  *
  * @pre The state should be #TTS_STATE_CREATED or #TTS_STATE_READY.
  *
@@ -395,7 +415,14 @@ int tts_get_default_voice(tts_h tts, char** language, int* voice_type);
 
 /**
  * @brief Sets the private data to tts engine.
- * @since_tizen 3.0
+ * @details The private data is the setting parameter for applying keys provided by the engine.
+ *     Using this API, the application can set the private data and use the corresponding key of the engine.
+ *     For example, if the engine provides 'girl's voice' as a voice type, the application can set the private data as the following. \n
+ *     int ret = tts_set_private_data(tts_h, "voice_type", "GIRL");
+ *
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ *
+ * @remarks If the engine is replaced with the other engine, the key may be ignored.
  *
  * @param[in] tts The TTS handle
  * @param[in] key The field name of private data
@@ -417,13 +444,16 @@ int tts_set_private_data(tts_h tts, const char* key, const char* data);
 
 /**
  * @brief Gets the private data from tts engine.
- * @since_tizen 3.0
+ * @details The private data is the information provided by the engine.
+ *     Using this API, the application can get the private data which corresponds to the key from the engine.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  *
- * @remarks data must be released using free() when it is no longer required.
+ * @remarks The @a data must be released using free() when it is no longer required.
+ *     If the engine is replaced with the other engine, the key may be ignored.
  *
  * @param[in] tts The TTS handle
  * @param[in] key The field name of private data
- * @param[out] data The data
+ * @param[out] data The data field of private data
  *
  * @return 0 on success, otherwise a negative error value
  * @retval #TTS_ERROR_NONE Successful
@@ -500,10 +530,10 @@ int tts_get_speed_range(tts_h tts, int* min, int* normal, int* max);
 
 /**
  * @brief Gets the current error message.
- * @since_tizen 3.0
- * @privlevel public
- * @remarks This function should be called during an tts error callback. If not, the error as operation failure will be returned. \n
- * If the function succeeds, @a err_msg must be released using free() when it is no longer required.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ *
+ * @remarks This function should be called from a tts error callback. Calling in any other context will result in an Operation failed error. \n
+ *     A successful call will allocate @a err_msg, which must be released by calling free() when it is no longer required.
  *
  * @param[in] tts The TTS handle
  * @param[out] err_msg The current error message
@@ -815,6 +845,45 @@ int tts_set_default_voice_changed_cb(tts_h tts, tts_default_voice_changed_cb cal
 */
 int tts_unset_default_voice_changed_cb(tts_h tts);
 
+ /**
+ * @brief Registers a callback function to detect the engine change.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ *
+ * @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 0 on success, otherwise a negative error value
+ * @retval #TTS_ERROR_NONE Successful
+ * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #TTS_ERROR_INVALID_STATE Invalid state
+ * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
+ *
+ * @pre The state should be #TTS_STATE_CREATED.
+ *
+ * @see tts_engine_changed_cb()
+ * @see tts_unset_engine_changed_cb()
+*/
+int tts_set_engine_changed_cb(tts_h tts, tts_engine_changed_cb callback, void* user_data);
+
+/**
+ * @brief Unregisters the callback function.
+ * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
+ *
+ * @param[in] tts The TTS handle
+ *
+ * @return 0 on success, otherwise a negative error value
+ * @retval #TTS_ERROR_NONE Successful
+ * @retval #TTS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #TTS_ERROR_INVALID_STATE Invalid state
+ * @retval #TTS_ERROR_NOT_SUPPORTED TTS NOT supported
+ *
+ * @pre The state should be #TTS_STATE_CREATED.
+ *
+ * @see tts_set_engine_changed_cb()
+*/
+int tts_unset_engine_changed_cb(tts_h tts);
+
 
 #ifdef __cplusplus
 }