//
-// Open Service Platform
// Copyright (c) 2012 Samsung Electronics Co., Ltd.
//
// Licensed under the Apache License, Version 2.0 (the License);
*
* @final This class is not intended for extension.
*
- * The %TimeZone class represents a time zone offset and figures out Daylight Saving Time (DST).
+ * The %TimeZone class represents the time zones and offers methods for time zone offset and Daylight Saving Time (DST).
+ * The time zone ID format is "Area/Location". @n
+ * However, the specialized time zone IDs have a different format, such as CST6CDT, EST5EDT and so on. @n
*
- * The form of time zone ID is "Area/Location". @n
+ * For more information on IDs, see <a href="http://www.iana.org/time-zones" target="_blank">Time Zone Database</a>. @n
*
- * However, the specialized time zone IDs have the different form, such as CST6CDT, EST5EDT and so on. @n
- *
- * For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">Time Zone Database</a>. @n
- *
- * The supported time zone list depends on the device. Therefore, it must be checked by using LocaleManager::GetAvailableTimeZonesN().
+ * The supported time zone list depends on the device. Therefore, you must call LocaleManager::GetAvailableTimeZonesN() to get
+ * the supported time zones.
*
* For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/time_zone.htm">Time Zones</a>.
*
*
* @param[in] rawOffset The base time zone offset to GMT in minutes
* @param[in] id The time zone ID
- * @remarks The form of time zone @c id is "Area/Location". @n For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">here</a>. @n
- * However, the supported time zone list depends on the device. Therefore, it must be checked before using this method.
- * @see LocaleManager::GetAvailableTimeZonesN()
+ * @remarks The format of time zone @c id is "Area/Location". @n
+ * For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">here</a>. @n
+ * However, the supported time zone list depends on the device. Therefore, you must call
+ * LocaleManager::GetAvailableTimeZonesN() to get the supported time zones.
*/
TimeZone(int rawOffset, const Tizen::Base::String& id);
/**
* Initializes this instance of %TimeZone with the specified raw GMT offset,
- * the ID of the time zone, the rules for starting/ending DST, and the DST offset.
+ * the time zone ID, the rules for starting/ending DST, and the DST offset.
*
* @since 2.0
*
* @param[in] startRule The DST starting rule
* @param[in] endRule The DST end rule
* @param[in] dstOffset The amount of time in minutes saved during DST
- * @remarks The form of time zone @c id is "Area/Location". @n For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">here</a>. @n
- * However, the supported time zone list depends on the device. Therefore, it must be checked before using this method.
- * @see LocaleManager::GetAvailableTimeZonesN()
+ * @remarks The form of time zone @c id is "Area/Location". @n
+ * For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">here</a>. @n
+ * However, the supported time zone list depends on the device. Therefore, you must call
+ * LocaleManager::GetAvailableTimeZonesN() to get the supported time zones.
*/
TimeZone(int rawOffset, const Tizen::Base::String& id,
const TimeRule& startRule, const TimeRule& endRule, int dstOffset);
/**
- * Checks whether the specified instance of %TimeZone equals the value of the current instance.
+ * Checks whether the specified %TimeZone instance is equal to the current instance.
*
* @since 2.0
*
bool operator ==(const TimeZone& otherTimeZone) const;
/**
- * Checks whether the %TimeZone instance is equal to the current instance.
+ * Checks whether the specified %TimeZone instance is equal to the current instance.
*
* @since 2.0
*
* @since 2.0
*
* @return @c true if the value of the specified instance is equal to that of the current instance, @n
- * else @c false
- * @param[in] obj The object to compare with the current instance
+ * else @c false
+ * @param[in] obj The object to compare with the current instance
*/
virtual bool Equals(const Tizen::Base::Object& obj) const;
/**
* Converts the Coordinated Universal Time (UTC) time to the standard time.
*
- * @since 2.0
+ * @since 2.0
*
* @return The standard time
* @param[in] utcTime The UTC time
/**
* Converts the wall time to the UTC time.
*
- * @since 2.0
+ * @since 2.0
*
* @return The UTC time
* @param[in] wallTime The wall time
/**
* Gets the raw and GMT offset for the specified instance of Tizen::Base::DateTime in the current time zone.
*
- * @if OSPCOMPAT
- * @brief <i> [Compatibility] </i>
+ * @if OSPCOMPAT
+ * @brief <i> [Compatibility] </i>
* @endif
* @since 2.0
* @if OSPCOMPAT
- * @compatibility This method has compatibility issues with OSP compatible applications. @n
- * For more information, see @ref CompTimeZoneGetOffsetPage "here".
+ * @compatibility This method has compatibility issues with OSP compatible applications. @n
+ * For more information, see @ref CompTimeZoneGetOffsetPage "here".
* @endif
*
* @return An error code
* @param[out] dstOffset The offset to add to @c rawOffset to obtain the total offset between the local and GMT time @n
* If DST is not in effect, it is zero.
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c date is invalid.
- * @remarks Local millisecond = GMT milliseconds + rawOffset(in milliseconds) + dstOffset(in milliseconds).
- * All computations are performed in Gregorian calendar.
+ * @exception E_INVALID_ARG The specified @c date is invalid.
+ * @remarks Local millisecond = GMT milliseconds + rawOffset(in milliseconds) + dstOffset(in milliseconds). @n
+ * All computations are performed in Gregorian calendar.
*/
result GetOffset(const Tizen::Base::DateTime& date, bool local, int& rawOffset, int& dstOffset) const;
/**
- * Gets the difference in minutes between the local standard time and GMT, taking into consideration both the raw offset and the effect of DST.
+ * Gets the difference in minutes between the local standard time and GMT, taking into consideration both the raw offset
+ * and the effect of DST.
*
* @if OSPCOMPAT
- * @brief <i> [Compatibility] </i>
+ * @brief <i> [Compatibility] </i>
* @endif
* @since 2.0
* @if OSPCOMPAT
- * @compatibility This method has compatibility issues with OSP compatible applications. @n
- * For more information, see @ref CompTimeZoneGetOffsetPage "here".
+ * @compatibility This method has compatibility issues with OSP compatible applications. @n
+ * For more information, see @ref CompTimeZoneGetOffsetPage "here".
* @endif
*
* @return An error code
* @param[in] ticks The time ticks value @n
- * The value is GMT time.
+ * The value is GMT time from starting day (Jan 1, 1.).
* @param[out] offset The offset between the local standard time and GMT, taking into consideration DST
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c ticks is invalid.
+ * @exception E_INVALID_ARG The specified @c ticks is invalid.
+ * @see Base::DateTime::GetTicks()
*/
result GetOffset(long long ticks, int& offset) const;
- /**
+ /**
* @if OSPCOMPAT
- * @page CompTimeZoneGetOffsetPage Compatibility for GetOffset()
- * @section CompTimeZoneGetOffsetIssueSection Issues
- * Implementation of this method in OSP compatible applications has the following issue: @n
- * -# The method returns E_OUT_OF_RANGE if an argument is invalid.
- *
- * @section CompTimeZoneGetOffsetSolutionSection Resolutions
- * This issue has been resolved in Tizen.
- * @par When working in Tizen:
- * -# The method returns E_INVALID_ARG if an argument is invalid.
+ * @page CompTimeZoneGetOffsetPage Compatibility for GetOffset()
+ * @section CompTimeZoneGetOffsetIssueSection Issues
+ * Implementation of this method in OSP compatible applications has the following issue: @n
+ * -# The method returns @c E_OUT_OF_RANGE if an argument is invalid.
+ *
+ * @section CompTimeZoneGetOffsetSolutionSection Resolutions
+ * This issue has been resolved in Tizen.
+ * @par When working in Tizen:
+ * -# The method returns @c E_INVALID_ARG if an argument is invalid.
* @endif
- */
+ */
/**
* Gets the difference in minutes between the local standard time and GMT, without including DST (that is, raw offset).
int GetRawOffset(void) const;
/**
- * Gets the ID of the time zone.
+ * Gets the time zone ID.
*
* @since 2.0
*
- * @return The ID of the time zone
+ * @return The time zone ID
*/
Tizen::Base::String GetId(void) const;
static TimeZone GetGmtTimeZone(void);
/**
- * Gets the time zone instance from the given ID.
+ * Gets the time zone instance for the specified ID.
*
* @if OSPCOMPAT
- * @brief <i> [Compatibility] </i>
+ * @brief <i> [Compatibility] </i>
* @endif
* @since 2.0
* @if OSPCOMPAT
- * @compatibility This method has compatibility issues with OSP compatible applications. @n
- * For more information, see @ref CompTimeZoneGetTimeZonePage "here".
+ * @compatibility This method has compatibility issues with OSP compatible applications. @n
+ * For more information, see @ref CompTimeZoneGetTimeZonePage "here".
* @endif
*
* @return An error code
* @param[in] id The time zone ID
- * @param[out] timeZone The time zone for the given ID
+ * @param[out] timeZone The time zone for the specified ID
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c id is invalid.
- * @remarks The %TimeZone instance for the specified @c id does not contain the DST information.
- * The supported time zone list depends on the device. Therefore, it should be checked before using this method.
- * @see LocaleManager::GetAvailableTimeZonesN()
+ * @exception E_INVALID_ARG The specified @c id is invalid.
+ * @remarks The %TimeZone instance for the specified @c id does not contain the DST information.@n
+ * The supported time zone list depends on the device. Therefore, you must call
+ * LocaleManager::GetAvailableTimeZonesN() to get the supported time zones.
*/
static result GetTimeZone(const Tizen::Base::String& id, Tizen::Locales::TimeZone& timeZone);
/**
- * Gets the %TimeZone instance from the specified ID and UTC time.
+ * Gets a %TimeZone instance from the specified ID and UTC time.
*
* @if OSPCOMPAT
- * @brief <i> [Compatibility] </i>
+ * @brief <i> [Compatibility] </i>
* @endif
* @since 2.0
* @if OSPCOMPAT
- * @compatibility This method has compatibility issues with OSP compatible applications. @n
- * For more information, see @ref CompTimeZoneGetTimeZonePage "here".
+ * @compatibility This method has compatibility issues with OSP compatible applications. @n
+ * For more information, see @ref CompTimeZoneGetTimeZonePage "here".
* @endif
*
* @return An error code
* @param[in] utcTime The UTC time
* @param[out] timeZone The time zone for the specified ID and UTC time
* @exception E_SUCCESS The method is successful.
- * @exception E_INVALID_ARG The specified @c id is invalid.
- * @remarks The %TimeZone instance for the specified ID and UTC time contains the DST information.
- * The supported time zone list depends on the device. Therefore, it should be checked before using this method.
- * @see LocaleManager::GetAvailableTimeZonesN()
+ * @exception E_INVALID_ARG The specified @c id is invalid.
+ * @remarks The %TimeZone instance for the specified ID and UTC time contains the DST information. @n
+ * The supported time zone list depends on the device. Therefore, you must call
+ * LocaleManager::GetAvailableTimeZonesN() to get the supported time zones.
*/
static result GetTimeZone(const Tizen::Base::String& id, const Tizen::Base::DateTime& utcTime, Tizen::Locales::TimeZone& timeZone);
- /**
+ /**
* @if OSPCOMPAT
- * @page CompTimeZoneGetTimeZonePage Compatibility for GetTimeZone()
- * @section CompTimeZoneGetTimeZoneIssueSection Issues
- * Implementation of this method in OSP compatible applications has the following issue: @n
- * -# The method returns E_UNSUPPORTED_OPERATION if the time zone ID is invalid.
- *
- * @section CompTimeZoneGetTimeZoneSolutionSection Resolutions
- * This issue has been resolved in Tizen.
+ * @page CompTimeZoneGetTimeZonePage Compatibility for GetTimeZone()
+ * @section CompTimeZoneGetTimeZoneIssueSection Issues
+ * Implementation of this method in OSP compatible applications has the following issue: @n
+ * -# The method returns @c E_UNSUPPORTED_OPERATION if the time zone ID is invalid.
+ *
+ * @section CompTimeZoneGetTimeZoneSolutionSection Resolutions
+ * This issue has been resolved in Tizen.
* @par When working in Tizen:
- * -# The method returns E_INVALID_ARG if the time zone ID is invalid.
+ * -# The method returns @c E_INVALID_ARG if the time zone ID is invalid.
* @endif
- */
+ */
/**
* Converts the UTC time to the standard time.
* @since 2.0
*
* @return The UTC time
- * @param[in] standardTime The standard time
+ * @param[in] standardTime The standard time
* @param[in] rawOffset The time zone's raw offset in minutes
*/
static Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime, int rawOffset);
* @since 2.0
*
* @return The wall time
- * @param[in] utcTime The UTC time
+ * @param[in] utcTime The UTC time
* @param[in] rawOffset The time zone's raw offset in minutes
* @param[in] dstOffset The amount of time in minutes saved during DST
*/
* @since 2.0
*
* @return The UTC time
- * @param[in] wallTime The wall time
+ * @param[in] wallTime The wall time
* @param[in] rawOffset The time zone's raw offset in minutes
* @param[in] dstOffset The amount of time in minutes saved during DST
*/