//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
* @since 2.0
*
* The %Timer class can activate the timer and notify the listeners.
+ * It supports relative time and provides both repeatable and non-repeatable timer.
+ * Because Timer is handled by event-driven way, when the main loop gets blocked, even if the time is expired, the listener cannot get notified.
* Once the target goes into sleep mode, Timer does not work properly because the main loop gets stopped.
* You can use Alarm on behalf of Timer for sleep mode.
* For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/base/timer.htm">Timer</a>.
* @since 2.0
*
* @return An error code
- * @param[in] listener The event listener
- * @exception E_SUCCESS The method is successful.
+ * @param[in] listener The event listener
+ * @exception E_SUCCESS The method is successful.
* @exception E_OUT_OF_MEMORY The memory is insufficient.
* @exception E_SYSTEM A system error has occurred.
*/
/**
* Starts the timer.
*
- * @if OSPCOMPACT
+ * @if OSPCOMPAT
* @brief <i> [Compatibility] </i>
* @endif
*
* @since 2.0
*
- * @if OSPCOMPACT
- * @compatibility This method has compatibility issues with Tizen API versions @b prior @b to @b 2.1. @n
+ * @if OSPCOMPAT
+ * @compatibility This method has compatibility issues with %Tizen API versions @b prior @b to @b 2.1. @n
* For more information, see @ref CompTimerStartPage "here".
* @endif
*
- * @return An error code
+ * @return An error code
* @param[in] timeout A timeout interval in milliseconds
- * @exception E_SUCCESS The method is successful.
+ * @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified input parameter is invalid.
+ * @exception E_INVALID_STATE The timer is in an invalid state for start.
* @exception E_SYSTEM A system error has occurred.
- * @remarks Once it has been started, it cannot be started again until it expires. @n
- * You must cancel it if you want to re-start the timer.
- * @see Cancel()
+ * @remarks Once the timer has been started, it cannot be started again until expired.
+ * @see Cancel()
*/
result Start(int timeout);
/**
* @page CompTimerStartPage Compatibility for Start(int timeout)
* @section CompTimerStartPageIssueSection Issues
- * Implementation of this method in Tizen API versions prior to 2.1 has the following issue: @n
+ * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
* -# The method returns E_INVALID_ARG if timeout is equal to zero.
*
* @section CompTimerStartPageSolutionSection Resolutions
- * The issue mentioned above is resolved in Tizen API version 2.1, and it is recommended to use Tizen API version 2.1 or above.
+ * The issue mentioned above is resolved in %Tizen API version 2.1, and it is recommended to use %Tizen API version 2.1 or above.
* -# In case of zero, Timer sets timeout to the best-effort minimum interval without returning E_INVALID_ARG.
*/
/**
* Starts the timer. @n
- * The timer is expired repeatedly until it is canceled.
+ * The timer is expired repeatedly until canceled.
*
* @since 2.0
*
- * @return An error code
+ * @return An error code
* @param[in] interval A timeout interval in milliseconds
* @exception E_SUCCESS The method is successful.
* @exception E_INVALID_ARG The specified input parameter is invalid.
+ * @exception E_INVALID_STATE The timer is in an invalid state for start.
* @exception E_SYSTEM A system error has occurred.
- * @remarks To stop timer expiration or restart a timer, the timer must be canceled.
- * @see Cancel()
+ * @remarks To stop timer expiration or restart a timer, the timer must be canceled.
+ * @see Cancel()
*/
result StartAsRepeatable(int interval);
*
* @since 2.0
*
- * @return An error code
- * @exception E_SUCCESS The method is successful.
+ * @return An error code
+ * @exception E_SUCCESS The method is successful.
* @exception E_SYSTEM A system error has occurred.
- * @remarks The timer cannot be canceled if it is not started.
+ * @remarks The started timer can be canceled when it does not get expired. If the timer was already expired, this method also returns E_SUCCESS which affects the same manner when canceled normally.
*/
result Cancel(void);