inc/FLclTimeZone.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   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
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  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.
  15 //
  16
  17 /**
  18  * @file                FLclTimeZone.h
  19  * @brief               This is the header file for the %TimeZone class.
  20  * @see                 Tizen::Locales::Locale
  21  *
  22  * This header file contains the declarations of the %TimeZone class.
  23  */
  24
  25 #ifndef _FLCL_TIME_ZONE_H_
  26 #define _FLCL_TIME_ZONE_H_
  27
  28 #include <FBaseString.h>
  29 #include <FBaseDateTime.h>
  30 #include <FLclTimeRule.h>
  31
  32 namespace Tizen { namespace Locales
  33 {
  34
  35 /**
  36  * @class               TimeZone
  37  * @brief               This class represents the time zones.
  38  *
  39  * @since               2.0
  40  *
  41  * @final       This class is not intended for extension.
  42  *
  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
  46  *
  47  * For more information on IDs, see <a href="http://www.iana.org/time-zones" target="_blank">Time Zone Database</a>. @n
  48  *
  49  * The supported time zone list depends on the device. Therefore, you must call LocaleManager::GetAvailableTimeZonesN() to get
  50  * the supported time zones.
  51  *
  52  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/time_zone.htm">Time Zones</a>.
  53  *
  54  * The following example demonstrates how to use the %TimeZone class.
  55  *
  56 @code
  57
  58 #include <FBase.h>
  59 #include <FSystem.h>
  60 #include <FLocales.h>
  61
  62 using namespace Tizen::Locales;
  63
  64 void
  65 MyClass::MyTimeZone(void)
  66 {
  67         // Gets the system time zone.
  68         LocaleManager localeManager;
  69         localeManager.Construct();
  70
  71         TimeZone timeZone = localeManager.GetSystemTimeZone();
  72
  73         String timeZoneId = timeZone.GetId();
  74         int rawOffset = timeZone.GetRawOffset();
  75         int dstSavings = timeZone.GetDstSavings();
  76
  77         // Gets the special time zone.
  78         DateTime utcTime;
  79         TimeZone timeZone2;
  80         Tizen::System::SystemTime::GetCurrentTime(utcTime);
  81         Tizen::Locales::TimeZone::GetTimeZone(L"Europe/Zurich", utcTime, timeZone2);
  82 }
  83 @endcode
  84  *
  85  */
  86
  87 class _OSP_EXPORT_ TimeZone
  88         : public Tizen::Base::Object
  89 {
  90 public:
  91         /**
  92          * This is the default constructor for this class.
  93          *
  94          * @since               2.0
  95          */
  96         TimeZone(void);
  97
  98
  99         /**
 100          * This is the destructor for this class. @n
 101          * This destructor overrides Tizen::Base::Object::~Object().
 102          *
 103          * @since               2.0
 104          */
 105         virtual ~TimeZone(void);
 106
 107
 108         /**
 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.
 112          *
 113          * @since                       2.0
 114          *
 115          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 116          */
 117         TimeZone(const TimeZone& otherTimeZone);
 118
 119         /**
 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.
 122          *
 123          * @since                       2.0
 124          *
 125          * @return                      A reference value of the current instance
 126          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 127          *
 128          */
 129         TimeZone& operator =(const TimeZone& otherTimeZone);
 130
 131         /**
 132          * Initializes this instance of %TimeZone with the specified raw GMT offset and the ID of the time zone without including DST.
 133          *
 134          * @since                       2.0
 135          *
 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.
 142          */
 143         TimeZone(int rawOffset, const Tizen::Base::String& id);
 144
 145         /**
 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.
 148          *
 149          * @since                       2.0
 150          *
 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.
 160          */
 161         TimeZone(int rawOffset, const Tizen::Base::String& id,
 162                 const TimeRule& startRule, const TimeRule& endRule, int dstOffset);
 163
 164         /**
 165          * Checks whether the specified %TimeZone instance is equal to the current instance.
 166          *
 167          * @since                       2.0
 168          *
 169          * @return                      @c true if the two instances are equal, @n
 170          *                                      else @c false
 171          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 172          */
 173         bool operator ==(const TimeZone& otherTimeZone) const;
 174
 175         /**
 176          * Checks whether the specified %TimeZone instance is equal to the current instance.
 177          *
 178          * @since                       2.0
 179          *
 180          * @return                      @c true if the two instances are not equal, @n
 181          *                                      else @c false
 182          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 183          */
 184         bool operator !=(const TimeZone& otherTimeZone) const;
 185
 186         /**
 187         * Compares the value of the specified instance to that of the current instance.
 188         *
 189         * @since                        2.0
 190         *
 191         * @return                       @c true if the value of the specified instance is equal to that of the current instance, @n
 192         *                                       else @c false
 193         * @param[in]            obj             The object to compare with the current instance
 194         */
 195         virtual bool Equals(const Tizen::Base::Object& obj) const;
 196
 197         /**
 198         * Gets the hash value of the current instance.
 199         *
 200         * @since                        2.0
 201         *
 202         * @return                       The hash value of the current instance
 203         */
 204         virtual int GetHashCode(void) const;
 205
 206         /**
 207         * Sets the DST time.
 208         *
 209         * @since                        2.0
 210         *
 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.
 213         */
 214         void SetDstSavings(int dstSavings);
 215
 216         /**
 217          * Sets the DST starting and end rule.
 218          *
 219          * @since                       2.0
 220          *
 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.
 227          */
 228         result SetDstRules(const TimeRule& startRule, const TimeRule& endRule, int dstSavings = 60);
 229
 230         /**
 231          * Sets the DST end rule.
 232          *
 233          * @since                       2.0
 234          *
 235          * @param[in]           endRule                                                 The DST end rule
 236          */
 237         void SetDstEndingRule(const TimeRule& endRule);
 238
 239         /**
 240          * Sets the DST starting rule.
 241          *
 242          * @since                       2.0
 243          *
 244          * @param[in]           startRule                                               The DST starting rule
 245          */
 246         void SetDstStartingRule(const TimeRule& startRule);
 247
 248         /**
 249          * Sets the difference in minutes between the local standard time and GMT,
 250          * without including DST (that is, raw offset).
 251          *
 252          * @since                       2.0
 253          *
 254          * @param[in]           rawOffset                                               The difference in minutes between the local standard time and GMT, without including DST
 255          */
 256         void SetRawOffset(int rawOffset);
 257
 258         /**
 259          * Sets the DST starting year.
 260          *
 261          * @since                       2.0
 262          *
 263          * @param[in]           year                                                    The DST starting year
 264          */
 265         void SetDstStartingYear(int year);
 266
 267         /**
 268          * Sets the ID of the time zone.
 269          *
 270          * @since                       2.0
 271          *
 272          * @param[in]           id                                                              The ID of the time zone
 273          */
 274         void SetId(const Tizen::Base::String& id);
 275
 276         /**
 277          * Converts the Coordinated Universal Time (UTC) time to the standard time.
 278          *
 279          * @since                       2.0
 280          *
 281          * @return                      The standard time
 282          * @param[in]           utcTime                                                 The UTC time
 283          */
 284         Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime);
 285
 286         /**
 287          * Converts the UTC time to the wall time.
 288          *
 289          * @since                       2.0
 290          *
 291          * @return                      The wall time
 292          * @param[in]           utcTime                                                 The UTC time
 293          */
 294         Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime);
 295
 296         /**
 297          * Converts the standard time to the UTC time.
 298          *
 299          * @since                       2.0
 300          *
 301          * @return                      The UTC time
 302          * @param[in]           standardTime                                    The standard time
 303          */
 304         Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime);
 305
 306         /**
 307          * Converts the wall time to the UTC time.
 308          *
 309          * @since                       2.0
 310          *
 311          * @return                      The UTC time
 312          * @param[in]           wallTime                                                The wall time
 313          */
 314         Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime);
 315
 316         /**
 317          * Gets the amount of time in minutes to be added to the local standard time to get the local wall time.
 318          *
 319          * @since                       2.0
 320          *
 321          * @return                      The amount of time in minutes
 322          *
 323          */
 324         int GetDstSavings(void) const;
 325
 326         /**
 327          * Gets the starting year of the DST.
 328          *
 329          * @since                       2.0
 330          *
 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()
 334          */
 335         int GetDstStartingYear(void) const;
 336
 337         /**
 338          * Gets the raw and GMT offset for the specified instance of Tizen::Base::DateTime in the current time zone.
 339          *
 340          * @if OSPCOMPAT
 341          * @brief                       <i> [Compatibility] </i>
 342          * @endif
 343          * @since                       2.0
 344          * @if OSPCOMPAT
 345          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 346          *                                      For more information, see @ref CompTimeZoneGetOffsetPage "here".
 347          * @endif
 348          *
 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.
 360          */
 361         result GetOffset(const Tizen::Base::DateTime& date, bool local, int& rawOffset, int& dstOffset) const;
 362
 363         /**
 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.
 366          *
 367          * @if OSPCOMPAT
 368          * @brief                       <i> [Compatibility] </i>
 369          * @endif
 370          * @since                       2.0
 371          * @if OSPCOMPAT
 372          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 373          *                                      For more information, see @ref CompTimeZoneGetOffsetPage "here".
 374          * @endif
 375          *
 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()
 383          */
 384         result GetOffset(long long ticks, int& offset) const;
 385
 386         /**
 387          * @if OSPCOMPAT
 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.
 392          *
 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.
 397          * @endif
 398          */
 399
 400         /**
 401          * Gets the difference in minutes between the local standard time and GMT, without including DST (that is, raw offset).
 402          *
 403          * @since                       2.0
 404          *
 405          * @return                      The raw offset
 406          *
 407          */
 408         int GetRawOffset(void) const;
 409
 410         /**
 411          * Gets the time zone ID.
 412          *
 413          * @since                       2.0
 414          *
 415          * @return                      The time zone ID
 416          */
 417         Tizen::Base::String GetId(void) const;
 418
 419         /**
 420          * Gets the DST starting rule.
 421          *
 422          * @since                       2.0
 423          *
 424          * @return                      A pointer to the DST start rule, @n
 425          *                                      else a @c null pointer if the DST start rule is undefined
 426          */
 427         const TimeRule* GetDstStartingRule(void) const;
 428
 429         /**
 430          * Gets the DST end rule.
 431          *
 432          * @since                       2.0
 433          *
 434          * @return                      A pointer to the DST end rule, @n
 435          *                                      else a @c null pointer if the DST end rule is undefined
 436          */
 437         const TimeRule* GetDstEndingRule(void) const;
 438
 439         /**
 440          * Checks whether the current instance of %TimeZone uses DST.
 441          *
 442          * @since                       2.0
 443          *
 444          * @return                      @c true if the current instance uses DST, @n
 445          *                                      else @c false
 446          */
 447         bool IsDstUsed(void) const;
 448
 449         /**
 450          * Gets the GMT time zone. @n
 451          * The GMT time zone has a raw offset of @c 0 and does not use DST.
 452          *
 453          * @since               2.0
 454          *
 455          * @return              The GMT time zone
 456          */
 457         static TimeZone GetGmtTimeZone(void);
 458
 459         /**
 460          * Gets the time zone instance for the specified ID.
 461          *
 462          * @if OSPCOMPAT
 463          * @brief                       <i> [Compatibility] </i>
 464          * @endif
 465          * @since                       2.0
 466          * @if OSPCOMPAT
 467          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 468          *                                      For more information, see @ref CompTimeZoneGetTimeZonePage "here".
 469          * @endif
 470          *
 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.
 479          */
 480         static result GetTimeZone(const Tizen::Base::String& id, Tizen::Locales::TimeZone& timeZone);
 481
 482         /**
 483          * Gets a %TimeZone instance from the specified ID and UTC time.
 484          *
 485          * @if OSPCOMPAT
 486          * @brief                       <i> [Compatibility] </i>
 487          * @endif
 488          * @since                       2.0
 489          * @if OSPCOMPAT
 490          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 491          *                                      For more information, see @ref CompTimeZoneGetTimeZonePage "here".
 492          * @endif
 493          *
 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.
 503          */
 504         static result GetTimeZone(const Tizen::Base::String& id, const Tizen::Base::DateTime& utcTime, Tizen::Locales::TimeZone& timeZone);
 505
 506         /**
 507          * @if OSPCOMPAT
 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.
 512          *
 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.
 517          * @endif
 518          */
 519
 520         /**
 521          * Converts the UTC time to the standard time.
 522          *
 523          * @since               2.0
 524          *
 525          * @return      The standard time
 526          * @param[in]   utcTime                 The UTC time
 527          * @param[in]   rawOffset               The time zone's raw offset in minutes
 528          */
 529         static Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime, int rawOffset);
 530
 531         /**
 532          * Converts the standard time to the UTC time.
 533          *
 534          * @since               2.0
 535          *
 536          * @return      The UTC time
 537          * @param[in]   standardTime    The standard time
 538          * @param[in]   rawOffset               The time zone's raw offset in minutes
 539          */
 540         static Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime, int rawOffset);
 541
 542         /**
 543          * Converts the UTC time to the wall time.
 544          *
 545          * @since               2.0
 546          *
 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
 551          */
 552         static Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime, int rawOffset, int dstOffset);
 553
 554         /**
 555          * Converts the wall time to the UTC time.
 556          *
 557          * @since               2.0
 558          *
 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
 563          */
 564         static Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime, int rawOffset, int dstOffset);
 565
 566 private:
 567
 568         friend class _TimeZoneImpl;
 569         class _TimeZoneImpl* __pTimeZoneImpl;
 570
 571         friend class _LocaleData;
 572 }; // TimeZone
 573
 574 }} // Tizen::Locales
 575 #endif // _FLCL_TIME_ZONE_H_