2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
4 // Licensed under the Apache License, Version 2.0 (the License);
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
8 // http://www.apache.org/licenses/LICENSE-2.0
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
18 * @file FLclTimeZone.h
19 * @brief This is the header file for the %TimeZone class.
20 * @see Tizen::Locales::Locale
22 * This header file contains the declarations of the %TimeZone class.
25 #ifndef _FLCL_TIME_ZONE_H_
26 #define _FLCL_TIME_ZONE_H_
28 #include <FBaseString.h>
29 #include <FBaseDateTime.h>
30 #include <FLclTimeRule.h>
32 namespace Tizen { namespace Locales
37 * @brief This class represents the time zones.
41 * @final This class is not intended for extension.
43 * The %TimeZone class represents the time zones and offers methods for time zone offset and Daylight Saving Time (DST).
44 * The time zone ID format is "Area/Location". @n
45 * However, the specialized time zone IDs have a different format, such as CST6CDT, EST5EDT and so on. @n
47 * For more information on IDs, see <a href="http://www.iana.org/time-zones" target="_blank">Time Zone Database</a>. @n
49 * The supported time zone list depends on the device. Therefore, you must call LocaleManager::GetAvailableTimeZonesN() to get
50 * the supported time zones.
52 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/time_zone.htm">Time Zones</a>.
54 * The following example demonstrates how to use the %TimeZone class.
62 using namespace Tizen::Locales;
65 MyClass::MyTimeZone(void)
67 // Gets the system time zone.
68 LocaleManager localeManager;
69 localeManager.Construct();
71 TimeZone timeZone = localeManager.GetSystemTimeZone();
73 String timeZoneId = timeZone.GetId();
74 int rawOffset = timeZone.GetRawOffset();
75 int dstSavings = timeZone.GetDstSavings();
77 // Gets the special time zone.
80 Tizen::System::SystemTime::GetCurrentTime(utcTime);
81 Tizen::Locales::TimeZone::GetTimeZone(L"Europe/Zurich", utcTime, timeZone2);
87 class _OSP_EXPORT_ TimeZone
88 : public Tizen::Base::Object
92 * This is the default constructor for this class.
100 * This is the destructor for this class. @n
101 * This destructor overrides Tizen::Base::Object::~Object().
105 virtual ~TimeZone(void);
109 * This is the copy constructor for the %TimeZone class. @n
110 * It initializes an instance of %TimeZone with the values of the specified instance of %TimeZone.
111 * Copying of objects using this copy constructor is allowed.
115 * @param[in] otherTimeZone An instance of %TimeZone
117 TimeZone(const TimeZone& otherTimeZone);
120 * Assigns the value of the specified instance to the current instance of %TimeZone. @n
121 * Copying of objects using this copy assignment operator is allowed.
125 * @return A reference value of the current instance
126 * @param[in] otherTimeZone An instance of %TimeZone
129 TimeZone& operator =(const TimeZone& otherTimeZone);
132 * Initializes this instance of %TimeZone with the specified raw GMT offset and the ID of the time zone without including DST.
136 * @param[in] rawOffset The base time zone offset to GMT in minutes
137 * @param[in] id The time zone ID
138 * @remarks The format of time zone @c id is "Area/Location". @n
139 * For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">here</a>. @n
140 * However, the supported time zone list depends on the device. Therefore, you must call
141 * LocaleManager::GetAvailableTimeZonesN() to get the supported time zones.
143 TimeZone(int rawOffset, const Tizen::Base::String& id);
146 * Initializes this instance of %TimeZone with the specified raw GMT offset,
147 * the time zone ID, the rules for starting/ending DST, and the DST offset.
151 * @param[in] rawOffset The base time zone offset to GMT in minutes
152 * @param[in] id The time zone ID
153 * @param[in] startRule The DST starting rule
154 * @param[in] endRule The DST end rule
155 * @param[in] dstOffset The amount of time in minutes saved during DST
156 * @remarks The form of time zone @c id is "Area/Location". @n
157 * For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">here</a>. @n
158 * However, the supported time zone list depends on the device. Therefore, you must call
159 * LocaleManager::GetAvailableTimeZonesN() to get the supported time zones.
161 TimeZone(int rawOffset, const Tizen::Base::String& id,
162 const TimeRule& startRule, const TimeRule& endRule, int dstOffset);
165 * Checks whether the specified %TimeZone instance is equal to the current instance.
169 * @return @c true if the two instances are equal, @n
171 * @param[in] otherTimeZone An instance of %TimeZone
173 bool operator ==(const TimeZone& otherTimeZone) const;
176 * Checks whether the specified %TimeZone instance is equal to the current instance.
180 * @return @c true if the two instances are not equal, @n
182 * @param[in] otherTimeZone An instance of %TimeZone
184 bool operator !=(const TimeZone& otherTimeZone) const;
187 * Compares the value of the specified instance to that of the current instance.
191 * @return @c true if the value of the specified instance is equal to that of the current instance, @n
193 * @param[in] obj The object to compare with the current instance
195 virtual bool Equals(const Tizen::Base::Object& obj) const;
198 * Gets the hash value of the current instance.
202 * @return The hash value of the current instance
204 virtual int GetHashCode(void) const;
211 * @param[in] dstSavings The amount of time in minutes @n
212 * The time is advanced with respect to the standard time when the DST rules are in effect.
214 void SetDstSavings(int dstSavings);
217 * Sets the DST starting and end rule.
221 * @return An error code
222 * @param[in] startRule The DST starting rule
223 * @param[in] endRule The DST end rule
224 * @param[in] dstSavings The DST offset in minutes
225 * @exception E_SUCCESS The method is successful.
226 * @exception E_OUT_OF_RANGE The specified @c dstSavings is less than 24 hours.
228 result SetDstRules(const TimeRule& startRule, const TimeRule& endRule, int dstSavings = 60);
231 * Sets the DST end rule.
235 * @param[in] endRule The DST end rule
237 void SetDstEndingRule(const TimeRule& endRule);
240 * Sets the DST starting rule.
244 * @param[in] startRule The DST starting rule
246 void SetDstStartingRule(const TimeRule& startRule);
249 * Sets the difference in minutes between the local standard time and GMT,
250 * without including DST (that is, raw offset).
254 * @param[in] rawOffset The difference in minutes between the local standard time and GMT, without including DST
256 void SetRawOffset(int rawOffset);
259 * Sets the DST starting year.
263 * @param[in] year The DST starting year
265 void SetDstStartingYear(int year);
268 * Sets the ID of the time zone.
272 * @param[in] id The ID of the time zone
274 void SetId(const Tizen::Base::String& id);
277 * Converts the Coordinated Universal Time (UTC) time to the standard time.
281 * @return The standard time
282 * @param[in] utcTime The UTC time
284 Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime);
287 * Converts the UTC time to the wall time.
291 * @return The wall time
292 * @param[in] utcTime The UTC time
294 Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime);
297 * Converts the standard time to the UTC time.
301 * @return The UTC time
302 * @param[in] standardTime The standard time
304 Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime);
307 * Converts the wall time to the UTC time.
311 * @return The UTC time
312 * @param[in] wallTime The wall time
314 Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime);
317 * Gets the amount of time in minutes to be added to the local standard time to get the local wall time.
321 * @return The amount of time in minutes
324 int GetDstSavings(void) const;
327 * Gets the starting year of the DST.
331 * @return The starting year of the DST set by the SetDstStartingYear() method, @n
332 * else @c 0 if the starting year of the DST is undefined
333 * @see SetDstStartingYear()
335 int GetDstStartingYear(void) const;
338 * Gets the raw and GMT offset for the specified instance of Tizen::Base::DateTime in the current time zone.
341 * @brief <i> [Compatibility] </i>
345 * @compatibility This method has compatibility issues with OSP compatible applications. @n
346 * For more information, see @ref CompTimeZoneGetOffsetPage "here".
349 * @return An error code
350 * @param[in] date An instance of Tizen::Base::DateTime
351 * @param[in] local Set to @c true if the date is in local wall time @n
352 * else @c false if it is in GMT time
353 * @param[out] rawOffset The time zone's raw offset in minutes
354 * @param[out] dstOffset The offset to add to @c rawOffset to obtain the total offset between the local and GMT time @n
355 * If DST is not in effect, it is zero.
356 * @exception E_SUCCESS The method is successful.
357 * @exception E_INVALID_ARG The specified @c date is invalid.
358 * @remarks Local millisecond = GMT milliseconds + rawOffset(in milliseconds) + dstOffset(in milliseconds). @n
359 * All computations are performed in Gregorian calendar.
361 result GetOffset(const Tizen::Base::DateTime& date, bool local, int& rawOffset, int& dstOffset) const;
364 * Gets the difference in minutes between the local standard time and GMT, taking into consideration both the raw offset
365 * and the effect of DST.
368 * @brief <i> [Compatibility] </i>
372 * @compatibility This method has compatibility issues with OSP compatible applications. @n
373 * For more information, see @ref CompTimeZoneGetOffsetPage "here".
376 * @return An error code
377 * @param[in] ticks The time ticks value @n
378 * The value is GMT time from starting day (Jan 1, 1.).
379 * @param[out] offset The offset between the local standard time and GMT, taking into consideration DST
380 * @exception E_SUCCESS The method is successful.
381 * @exception E_INVALID_ARG The specified @c ticks is invalid.
382 * @see Base::DateTime::GetTicks()
384 result GetOffset(long long ticks, int& offset) const;
388 * @page CompTimeZoneGetOffsetPage Compatibility for GetOffset()
389 * @section CompTimeZoneGetOffsetIssueSection Issues
390 * Implementation of this method in OSP compatible applications has the following issue: @n
391 * -# The method returns @c E_OUT_OF_RANGE if an argument is invalid.
393 * @section CompTimeZoneGetOffsetSolutionSection Resolutions
394 * This issue has been resolved in Tizen.
395 * @par When working in Tizen:
396 * -# The method returns @c E_INVALID_ARG if an argument is invalid.
401 * Gets the difference in minutes between the local standard time and GMT, without including DST (that is, raw offset).
405 * @return The raw offset
408 int GetRawOffset(void) const;
411 * Gets the time zone ID.
415 * @return The time zone ID
417 Tizen::Base::String GetId(void) const;
420 * Gets the DST starting rule.
424 * @return A pointer to the DST start rule, @n
425 * else a @c null pointer if the DST start rule is undefined
427 const TimeRule* GetDstStartingRule(void) const;
430 * Gets the DST end rule.
434 * @return A pointer to the DST end rule, @n
435 * else a @c null pointer if the DST end rule is undefined
437 const TimeRule* GetDstEndingRule(void) const;
440 * Checks whether the current instance of %TimeZone uses DST.
444 * @return @c true if the current instance uses DST, @n
447 bool IsDstUsed(void) const;
450 * Gets the GMT time zone. @n
451 * The GMT time zone has a raw offset of @c 0 and does not use DST.
455 * @return The GMT time zone
457 static TimeZone GetGmtTimeZone(void);
460 * Gets the time zone instance for the specified ID.
463 * @brief <i> [Compatibility] </i>
467 * @compatibility This method has compatibility issues with OSP compatible applications. @n
468 * For more information, see @ref CompTimeZoneGetTimeZonePage "here".
471 * @return An error code
472 * @param[in] id The time zone ID
473 * @param[out] timeZone The time zone for the specified ID
474 * @exception E_SUCCESS The method is successful.
475 * @exception E_INVALID_ARG The specified @c id is invalid.
476 * @remarks The %TimeZone instance for the specified @c id does not contain the DST information.@n
477 * The supported time zone list depends on the device. Therefore, you must call
478 * LocaleManager::GetAvailableTimeZonesN() to get the supported time zones.
480 static result GetTimeZone(const Tizen::Base::String& id, Tizen::Locales::TimeZone& timeZone);
483 * Gets a %TimeZone instance from the specified ID and UTC time.
486 * @brief <i> [Compatibility] </i>
490 * @compatibility This method has compatibility issues with OSP compatible applications. @n
491 * For more information, see @ref CompTimeZoneGetTimeZonePage "here".
494 * @return An error code
495 * @param[in] id The time zone ID
496 * @param[in] utcTime The UTC time
497 * @param[out] timeZone The time zone for the specified ID and UTC time
498 * @exception E_SUCCESS The method is successful.
499 * @exception E_INVALID_ARG The specified @c id is invalid.
500 * @remarks The %TimeZone instance for the specified ID and UTC time contains the DST information. @n
501 * The supported time zone list depends on the device. Therefore, you must call
502 * LocaleManager::GetAvailableTimeZonesN() to get the supported time zones.
504 static result GetTimeZone(const Tizen::Base::String& id, const Tizen::Base::DateTime& utcTime, Tizen::Locales::TimeZone& timeZone);
508 * @page CompTimeZoneGetTimeZonePage Compatibility for GetTimeZone()
509 * @section CompTimeZoneGetTimeZoneIssueSection Issues
510 * Implementation of this method in OSP compatible applications has the following issue: @n
511 * -# The method returns @c E_UNSUPPORTED_OPERATION if the time zone ID is invalid.
513 * @section CompTimeZoneGetTimeZoneSolutionSection Resolutions
514 * This issue has been resolved in Tizen.
515 * @par When working in Tizen:
516 * -# The method returns @c E_INVALID_ARG if the time zone ID is invalid.
521 * Converts the UTC time to the standard time.
525 * @return The standard time
526 * @param[in] utcTime The UTC time
527 * @param[in] rawOffset The time zone's raw offset in minutes
529 static Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime, int rawOffset);
532 * Converts the standard time to the UTC time.
536 * @return The UTC time
537 * @param[in] standardTime The standard time
538 * @param[in] rawOffset The time zone's raw offset in minutes
540 static Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime, int rawOffset);
543 * Converts the UTC time to the wall time.
547 * @return The wall time
548 * @param[in] utcTime The UTC time
549 * @param[in] rawOffset The time zone's raw offset in minutes
550 * @param[in] dstOffset The amount of time in minutes saved during DST
552 static Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime, int rawOffset, int dstOffset);
555 * Converts the wall time to the UTC time.
559 * @return The UTC time
560 * @param[in] wallTime The wall time
561 * @param[in] rawOffset The time zone's raw offset in minutes
562 * @param[in] dstOffset The amount of time in minutes saved during DST
564 static Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime, int rawOffset, int dstOffset);
568 friend class _TimeZoneImpl;
569 class _TimeZoneImpl* __pTimeZoneImpl;
571 friend class _LocaleData;
575 #endif // _FLCL_TIME_ZONE_H_