* 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.
*/
extern "C" {
#endif
-/**
+/**
* @brief Enumeration for error code.
* @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
*/
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
*/
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
*/
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
*/
*/
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);
/**
/**
* @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
* @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.
*
/**
* @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
/**
* @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
/**
* @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
*/
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
}
projects / platform / core / uifw / tts.git / commitdiff