2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FLclTimeZone.h
20 * @brief This is the header file for the %TimeZone class.
21 * @see Tizen::Locales::Locale
23 * This header file contains the declarations of the %TimeZone class.
26 #ifndef _FLCL_TIME_ZONE_H_
27 #define _FLCL_TIME_ZONE_H_
29 #include <FBaseString.h>
30 #include <FBaseDateTime.h>
31 #include <FLclTimeRule.h>
33 namespace Tizen { namespace Locales
38 * @brief This class represents the time zones.
42 * @final This class is not intended for extension.
44 * The %TimeZone class represents a time zone offset and figures out Daylight Saving Time (DST).
46 * The form of time zone ID is "Area/Location". However, the specialized time zone IDs have the different form.@n
48 * The IDs are defined in <a href="http://www.iana.org/time-zones" target="_blank">Time Zone Database</a>. @n
50 * The supported time zone list depends on the device. Therefore, it must be checked by using LocaleManager::GetAvailableTimeZonesN().
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.
60 using namespace Tizen::Locales;
63 MyClass::MyTimeZone(void)
65 // Gets the system time zone.
66 LocaleManager localeManager;
67 localeManager.Construct();
69 TimeZone timeZone = localeManager.GetSystemTimeZone();
71 String timeZoneId = timeZone.GetId();
72 int rawOffset = timeZone.GetRawOffset();
73 int dstSavings = timeZone.GetDstSavings();
75 // Gets the special time zone.
77 Tizen::Locales::TimeZone::GetTimeZone(L"Europe/Zurich", timeZone2);
83 class _OSP_EXPORT_ TimeZone
84 : public Tizen::Base::Object
88 * This is the default constructor for this class.
96 * This is the destructor for this class. @n
97 * This destructor overrides Tizen::Base::Object::~Object().
101 virtual ~TimeZone(void);
105 * This is the copy constructor for the %TimeZone class. @n
106 * It initializes an instance of %TimeZone with the values of the specified instance of %TimeZone.
107 * Copying of objects using this copy constructor is allowed.
111 * @param[in] otherTimeZone An instance of %TimeZone
113 TimeZone(const TimeZone& otherTimeZone);
116 * Assigns the value of the specified instance to the current instance of %TimeZone. @n
117 * Copying of objects using this copy assignment operator is allowed.
121 * @return A reference value of the current instance
122 * @param[in] otherTimeZone An instance of %TimeZone
125 TimeZone& operator =(const TimeZone& otherTimeZone);
128 * Initializes this instance of %TimeZone with the specified raw GMT offset and the ID of the time zone without including DST.
132 * @param[in] rawOffset The base time zone offset to GMT in minutes
133 * @param[in] id The time zone ID
134 * @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">here</a>. @n
135 * However, the supported time zone list depends on the device. Therefore, it must be checked before using this method.
136 * @see LocaleManager::GetAvailableTimeZonesN()
138 TimeZone(int rawOffset, const Tizen::Base::String& id);
141 * Initializes this instance of %TimeZone with the specified raw GMT offset,
142 * the ID of the time zone, the rules for starting/ending DST, and the DST offset.
146 * @param[in] rawOffset The base time zone offset to GMT in minutes
147 * @param[in] id The time zone ID
148 * @param[in] startRule The DST starting rule
149 * @param[in] endRule The DST end rule
150 * @param[in] dstOffset The amount of time in minutes saved during DST
151 * @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">here</a>. @n
152 * However, the supported time zone list depends on the device. Therefore, it must be checked before using this method.
153 * @see LocaleManager::GetAvailableTimeZonesN()
155 TimeZone(int rawOffset, const Tizen::Base::String& id,
156 const TimeRule& startRule, const TimeRule& endRule, int dstOffset);
159 * Checks whether the specified instance of %TimeZone equals the value of the current instance.
163 * @return @c true if the two instances are equal, @n
165 * @param[in] otherTimeZone An instance of %TimeZone
167 bool operator ==(const TimeZone& otherTimeZone) const;
170 * Checks whether the %TimeZone instance is equal to the current instance.
174 * @return @c true if the two instances are not equal, @n
176 * @param[in] otherTimeZone An instance of %TimeZone
178 bool operator !=(const TimeZone& otherTimeZone) const;
181 * Compares the value of the specified instance to that of the current instance.
185 * @return @c true if the value of the specified instance is equal to that of the current instance, @n
187 * @param[in] obj The object to compare with the current instance
189 virtual bool Equals(const Tizen::Base::Object& obj) const;
192 * Gets the hash value of the current instance.
196 * @return The hash value of the current instance
198 virtual int GetHashCode(void) const;
205 * @param[in] dstSavings The amount of time in minutes @n
206 * The time is advanced with respect to the standard time when the DST rules are in effect.
208 void SetDstSavings(int dstSavings);
211 * Sets the DST starting and end rule.
215 * @return An error code
216 * @param[in] startRule The DST starting rule
217 * @param[in] endRule The DST end rule
218 * @param[in] dstSavings The DST offset in minutes
219 * @exception E_SUCCESS The method is successful.
220 * @exception E_OUT_OF_RANGE The specified @c dstSavings is less than 24 hours.
222 result SetDstRules(const TimeRule& startRule, const TimeRule& endRule, int dstSavings = 60);
225 * Sets the DST end rule.
229 * @param[in] endRule The DST end rule
231 void SetDstEndingRule(const TimeRule& endRule);
234 * Sets the DST starting rule.
238 * @param[in] startRule The DST starting rule
240 void SetDstStartingRule(const TimeRule& startRule);
243 * Sets the difference in minutes between the local standard time and GMT,
244 * without including DST (that is, raw offset).
248 * @param[in] rawOffset The difference in minutes between the local standard time and GMT, without including DST
250 void SetRawOffset(int rawOffset);
253 * Sets the DST starting year.
257 * @param[in] year The DST starting year
259 void SetDstStartingYear(int year);
262 * Sets the ID of the time zone.
266 * @param[in] id The ID of the time zone
268 void SetId(const Tizen::Base::String& id);
271 * Converts the Coordinated Universal Time (UTC) time to the standard time.
275 * @return The standard time
276 * @param[in] utcTime The UTC time
278 Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime);
281 * Converts the UTC time to the wall time.
285 * @return The wall time
286 * @param[in] utcTime The UTC time
288 Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime);
291 * Converts the standard time to the UTC time.
295 * @return The UTC time
296 * @param[in] standardTime The standard time
298 Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime);
301 * Converts the wall time to the UTC time.
305 * @return The UTC time
306 * @param[in] wallTime The wall time
308 Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime);
311 * Gets the amount of time in minutes to be added to the local standard time to get the local wall time.
315 * @return The amount of time in minutes
318 int GetDstSavings(void) const;
321 * Gets the starting year of the DST.
325 * @return The starting year of the DST set by the SetDstStartingYear() method, @n
326 * else @c 0 if the starting year of the DST is undefined
327 * @see SetDstStartingYear()
329 int GetDstStartingYear(void) const;
332 * Gets the raw and GMT offset for the specified instance of Tizen::Base::DateTime in the current time zone.
335 * @brief <i> [Compatibility] </i>
339 * @compatibility This method has compatibility issues with OSP compatibile applications. @n
340 * For more information, see @ref CompTimeZoneGetOffsetPage "here".
343 * @return An error code
344 * @param[in] date An instance of Tizen::Base::DateTime
345 * @param[in] local Set to @c true if the date is in local wall time @n
346 * else @c false if it is in GMT time
347 * @param[out] rawOffset The time zone's raw offset in minutes
348 * @param[out] dstOffset The offset to add to @c rawOffset to obtain the total offset between the local and GMT time @n
349 * If DST is not in effect, it is zero.
350 * @exception E_SUCCESS The method is successful.
351 * @exception E_INVALID_ARG The specified @c date is invalid.
352 * @remarks Local millisecond = GMT milliseconds + rawOffset(in milliseconds) + dstOffset(in milliseconds).
353 * All computations are performed in Gregorian calendar.
355 result GetOffset(const Tizen::Base::DateTime& date, bool local, int& rawOffset, int& dstOffset) const;
358 * Gets the difference in minutes between the local standard time and GMT, taking into consideration both the raw offset and the effect of DST.
361 * @brief <i> [Compatibility] </i>
365 * @compatibility This method has compatibility issues with OSP compatibile applications. @n
366 * For more information, see @ref CompTimeZoneGetOffsetPage "here".
369 * @return An error code
370 * @param[in] ticks The time ticks value @n
371 * The value can be either GMT time or local wall time.
372 * @param[out] offset The offset between the local standard time and GMT, taking into consideration DST
373 * @exception E_SUCCESS The method is successful.
374 * @exception E_INVALID_ARG The specified @c ticks is invalid.
376 result GetOffset(long long ticks, int& offset) const;
380 * @page CompTimeZoneGetOffsetPage Compatibility for GetOffset()
381 * @section CompTimeZoneGetOffsetIssueSection Issues
382 * Implementation of this method in OSP compatible applications has the following issue: @n
383 * -# The method returns E_OUT_OF_RANGE if an argument is invalid.
385 * @section CompTimeZoneGetOffsetSolutionSection Resolutions
386 * This issue has been resolved in Tizen.
387 * @par When working in Tizen:
388 * -# The method returns E_INVALID_ARG if an argument is invalid.
393 * Gets the difference in minutes between the local standard time and GMT, without including DST (that is, raw offset).
397 * @return The raw offset
400 int GetRawOffset(void) const;
403 * Gets the ID of the time zone.
407 * @return The ID of the time zone
409 Tizen::Base::String GetId(void) const;
412 * Gets the DST starting rule.
416 * @return A pointer to the DST start rule, @n
417 * else a @c null pointer if the DST start rule is undefined
419 const TimeRule* GetDstStartingRule(void) const;
422 * Gets the DST end rule.
426 * @return A pointer to the DST end rule, @n
427 * else a @c null pointer if the DST end rule is undefined
429 const TimeRule* GetDstEndingRule(void) const;
432 * Checks whether the current instance of %TimeZone uses DST.
436 * @return @c true if the current instance uses DST, @n
439 bool IsDstUsed(void) const;
442 * Gets the GMT time zone. @n
443 * The GMT time zone has a raw offset of @c 0 and does not use DST.
447 * @return The GMT time zone
449 static TimeZone GetGmtTimeZone(void);
452 * Gets the time zone instance from the given ID.
455 * @brief <i> [Compatibility] </i>
459 * @compatibility This method has compatibility issues with OSP compatibile applications. @n
460 * For more information, see @ref CompTimeZoneGetTimeZonePage "here".
463 * @return An error code
464 * @param[in] id The time zone ID
465 * @param[out] timeZone The time zone for the given ID
466 * @exception E_SUCCESS The method is successful.
467 * @exception E_INVALID_ARG The specified @c id is invalid.
468 * @remarks The %TimeZone instance for the specified @c id does not contain the DST information.
469 * The supported time zone list depends on the device. Therefore, it should be checked before using this method.
470 * @see LocaleManager::GetAvailableTimeZonesN()
472 static result GetTimeZone(const Tizen::Base::String& id, Tizen::Locales::TimeZone& timeZone);
475 * Gets the %TimeZone instance from the specified ID and UTC time.
478 * @brief <i> [Compatibility] </i>
482 * @compatibility This method has compatibility issues with OSP compatibile applications. @n
483 * For more information, see @ref CompTimeZoneGetTimeZonePage "here".
486 * @return An error code
487 * @param[in] id The time zone ID
488 * @param[in] utcTime The UTC time
489 * @param[out] timeZone The time zone for the specified ID and UTC time
490 * @exception E_SUCCESS The method is successful.
491 * @exception E_INVALID_ARG The specified @c id is invalid.
492 * @remarks The %TimeZone instance for the specified ID and UTC time contains the DST information.
493 * The supported time zone list depends on the device. Therefore, it should be checked before using this method.
494 * @see LocaleManager::GetAvailableTimeZonesN()
496 static result GetTimeZone(const Tizen::Base::String& id, const Tizen::Base::DateTime& utcTime, Tizen::Locales::TimeZone& timeZone);
500 * @page CompTimeZoneGetTimeZonePage Compatibility for GetTimeZone()
501 * @section CompTimeZoneGetTimeZoneIssueSection Issues
502 * Implementation of this method in OSP compatible applications has the following issue: @n
503 * -# The method returns E_UNSUPPORTED_OPERATION if the time zone ID is invalid.
505 * @section CompTimeZoneGetTimeZoneSolutionSection Resolutions
506 * This issue has been resolved in Tizen.
507 * @par When working in Tizen:
508 * -# The method returns E_INVALID_ARG if the time zone ID is invalid.
513 * Converts the UTC time to the standard time.
517 * @return The standard time
518 * @param[in] utcTime The UTC time
519 * @param[in] rawOffset The time zone's raw offset in minutes
521 static Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime, int rawOffset);
524 * Converts the standard time to the UTC time.
528 * @return The UTC time
529 * @param[in] standardTime The standard time
530 * @param[in] rawOffset The time zone's raw offset in minutes
532 static Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime, int rawOffset);
535 * Converts the UTC time to the wall time.
539 * @return The wall time
540 * @param[in] utcTime The UTC time
541 * @param[in] rawOffset The time zone's raw offset in minutes
542 * @param[in] dstOffset The amount of time in minutes saved during DST
544 static Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime, int rawOffset, int dstOffset);
547 * Converts the wall time to the UTC time.
551 * @return The UTC time
552 * @param[in] wallTime The wall time
553 * @param[in] rawOffset The time zone's raw offset in minutes
554 * @param[in] dstOffset The amount of time in minutes saved during DST
556 static Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime, int rawOffset, int dstOffset);
560 friend class _TimeZoneImpl;
561 class _TimeZoneImpl* __pTimeZoneImpl;
563 friend class _LocaleData;
567 #endif // _FLCL_TIME_ZONE_H_