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 a time zone offset and figures out Daylight Saving Time (DST).
  44  *
  45  * The form of time zone ID is "Area/Location". @n
  46  *
  47  * However, the specialized time zone IDs have the different form, such as CST6CDT, EST5EDT and so on. @n
  48  *
  49  * For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">Time Zone Database</a>. @n
  50  *
  51  * The supported time zone list depends on the device. Therefore, it must be checked by using LocaleManager::GetAvailableTimeZonesN().
  52  *
  53  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/time_zone.htm">Time Zones</a>.
  54  *
  55  * The following example demonstrates how to use the %TimeZone class.
  56  *
  57 @code
  58
  59 #include <FBase.h>
  60 #include <FSystem.h>
  61 #include <FLocales.h>
  62
  63 using namespace Tizen::Locales;
  64
  65 void
  66 MyClass::MyTimeZone(void)
  67 {
  68         // Gets the system time zone.
  69         LocaleManager localeManager;
  70         localeManager.Construct();
  71
  72         TimeZone timeZone = localeManager.GetSystemTimeZone();
  73
  74         String timeZoneId = timeZone.GetId();
  75         int rawOffset = timeZone.GetRawOffset();
  76         int dstSavings = timeZone.GetDstSavings();
  77
  78         // Gets the special time zone.
  79         DateTime utcTime;
  80         TimeZone timeZone2;
  81         Tizen::System::SystemTime::GetCurrentTime(utcTime);
  82         Tizen::Locales::TimeZone::GetTimeZone(L"Europe/Zurich", utcTime, timeZone2);
  83 }
  84 @endcode
  85  *
  86  */
  87
  88 class _OSP_EXPORT_ TimeZone
  89         : public Tizen::Base::Object
  90 {
  91 public:
  92         /**
  93          * This is the default constructor for this class.
  94          *
  95          * @since               2.0
  96          */
  97         TimeZone(void);
  98
  99
 100         /**
 101          * This is the destructor for this class. @n
 102          * This destructor overrides Tizen::Base::Object::~Object().
 103          *
 104          * @since               2.0
 105          */
 106         virtual ~TimeZone(void);
 107
 108
 109         /**
 110          * This is the copy constructor for the %TimeZone class. @n
 111          * It initializes an instance of %TimeZone with the values of the specified instance of %TimeZone.
 112          * Copying of objects using this copy constructor is allowed.
 113          *
 114          * @since                       2.0
 115          *
 116          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 117          */
 118         TimeZone(const TimeZone& otherTimeZone);
 119
 120         /**
 121          * Assigns the value of the specified instance to the current instance of %TimeZone. @n
 122          * Copying of objects using this copy assignment operator is allowed.
 123          *
 124          * @since                       2.0
 125          *
 126          * @return                      A reference value of the current instance
 127          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 128          *
 129          */
 130         TimeZone& operator =(const TimeZone& otherTimeZone);
 131
 132         /**
 133          * Initializes this instance of %TimeZone with the specified raw GMT offset and the ID of the time zone without including DST.
 134          *
 135          * @since                       2.0
 136          *
 137          * @param[in]           rawOffset                                               The base time zone offset to GMT in minutes
 138          * @param[in]           id                                                              The time zone ID
 139          * @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
 140          *                                      However, the supported time zone list depends on the device. Therefore, it must be checked before using this method.
 141          * @see                         LocaleManager::GetAvailableTimeZonesN()
 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 ID of the time zone, 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 For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">here</a>. @n
 157          *                                      However, the supported time zone list depends on the device. Therefore, it must be checked before using this method.
 158          * @see                         LocaleManager::GetAvailableTimeZonesN()
 159          */
 160         TimeZone(int rawOffset, const Tizen::Base::String& id,
 161                 const TimeRule& startRule, const TimeRule& endRule, int dstOffset);
 162
 163         /**
 164          * Checks whether the specified instance of %TimeZone equals the value of the current instance.
 165          *
 166          * @since                       2.0
 167          *
 168          * @return                      @c true if the two instances are equal, @n
 169          *                                      else @c false
 170          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 171          */
 172         bool operator ==(const TimeZone& otherTimeZone) const;
 173
 174         /**
 175          * Checks whether the %TimeZone instance is equal to the current instance.
 176          *
 177          * @since                       2.0
 178          *
 179          * @return                      @c true if the two instances are not equal, @n
 180          *                                      else @c false
 181          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 182          */
 183         bool operator !=(const TimeZone& otherTimeZone) const;
 184
 185         /**
 186         * Compares the value of the specified instance to that of the current instance.
 187         *
 188         * @since                        2.0
 189         *
 190         * @return                       @c true if the value of the specified instance is equal to that of the current instance, @n
 191         *                                         else @c false
 192         * @param[in]            obj The object to compare with the current instance
 193         */
 194         virtual bool Equals(const Tizen::Base::Object& obj) const;
 195
 196         /**
 197         * Gets the hash value of the current instance.
 198         *
 199         * @since                        2.0
 200         *
 201         * @return                       The hash value of the current instance
 202         */
 203         virtual int GetHashCode(void) const;
 204
 205         /**
 206         * Sets the DST time.
 207         *
 208         * @since                        2.0
 209         *
 210         * @param[in]            dstSavings                                              The amount of time in minutes @n
 211         *                                                                                                       The time is advanced with respect to the standard time when the DST rules are in effect.
 212         */
 213         void SetDstSavings(int dstSavings);
 214
 215         /**
 216          * Sets the DST starting and end rule.
 217          *
 218          * @since                       2.0
 219          *
 220          * @return                      An error code
 221          * @param[in]           startRule                                               The DST starting rule
 222          * @param[in]           endRule                                                 The DST end rule
 223          * @param[in]           dstSavings                                              The DST offset in minutes
 224          * @exception           E_SUCCESS                                               The method is successful.
 225          * @exception           E_OUT_OF_RANGE                                  The specified @c dstSavings is less than 24 hours.
 226          */
 227         result SetDstRules(const TimeRule& startRule, const TimeRule& endRule, int dstSavings = 60);
 228
 229         /**
 230          * Sets the DST end rule.
 231          *
 232          * @since                       2.0
 233          *
 234          * @param[in]           endRule                                                 The DST end rule
 235          */
 236         void SetDstEndingRule(const TimeRule& endRule);
 237
 238         /**
 239          * Sets the DST starting rule.
 240          *
 241          * @since                       2.0
 242          *
 243          * @param[in]           startRule                                               The DST starting rule
 244          */
 245         void SetDstStartingRule(const TimeRule& startRule);
 246
 247         /**
 248          * Sets the difference in minutes between the local standard time and GMT,
 249          * without including DST (that is, raw offset).
 250          *
 251          * @since                       2.0
 252          *
 253          * @param[in]           rawOffset                                               The difference in minutes between the local standard time and GMT, without including DST
 254          */
 255         void SetRawOffset(int rawOffset);
 256
 257         /**
 258          * Sets the DST starting year.
 259          *
 260          * @since                       2.0
 261          *
 262          * @param[in]           year                                                    The DST starting year
 263          */
 264         void SetDstStartingYear(int year);
 265
 266         /**
 267          * Sets the ID of the time zone.
 268          *
 269          * @since                       2.0
 270          *
 271          * @param[in]           id                                                              The ID of the time zone
 272          */
 273         void SetId(const Tizen::Base::String& id);
 274
 275         /**
 276          * Converts the Coordinated Universal Time (UTC) time to the standard time.
 277          *
 278          * @since                               2.0
 279          *
 280          * @return                      The standard time
 281          * @param[in]           utcTime                                                 The UTC time
 282          */
 283         Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime);
 284
 285         /**
 286          * Converts the UTC time to the wall time.
 287          *
 288          * @since                       2.0
 289          *
 290          * @return                      The wall time
 291          * @param[in]           utcTime                                                 The UTC time
 292          */
 293         Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime);
 294
 295         /**
 296          * Converts the standard time to the UTC time.
 297          *
 298          * @since                       2.0
 299          *
 300          * @return                      The UTC time
 301          * @param[in]           standardTime                                    The standard time
 302          */
 303         Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime);
 304
 305         /**
 306          * Converts the wall time to the UTC time.
 307          *
 308          * @since                               2.0
 309          *
 310          * @return                      The UTC time
 311          * @param[in]           wallTime                                                The wall time
 312          */
 313         Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime);
 314
 315         /**
 316          * Gets the amount of time in minutes to be added to the local standard time to get the local wall time.
 317          *
 318          * @since                       2.0
 319          *
 320          * @return                      The amount of time in minutes
 321          *
 322          */
 323         int GetDstSavings(void) const;
 324
 325         /**
 326          * Gets the starting year of the DST.
 327          *
 328          * @since                       2.0
 329          *
 330          * @return                      The starting year of the DST set by the SetDstStartingYear() method, @n
 331          *                                      else @c 0 if the starting year of the DST is undefined
 332          * @see                         SetDstStartingYear()
 333          */
 334         int GetDstStartingYear(void) const;
 335
 336         /**
 337          * Gets the raw and GMT offset for the specified instance of Tizen::Base::DateTime in the current time zone.
 338          *
 339          * @if OSPCOMPAT
 340          * @brief                               <i> [Compatibility] </i>
 341          * @endif
 342          * @since                       2.0
 343          * @if OSPCOMPAT
 344          * @compatibility     This method has compatibility issues with OSP compatible applications. @n
 345          *                              For more information, see @ref CompTimeZoneGetOffsetPage "here".
 346          * @endif
 347          *
 348          * @return                      An error code
 349          * @param[in]           date                                            An instance of Tizen::Base::DateTime
 350          * @param[in]           local                                           Set to @c true if the date is in local wall time @n
 351          *                                                                                              else @c false if it is in GMT time
 352          * @param[out]          rawOffset                                       The time zone's raw offset in minutes
 353          * @param[out]          dstOffset                                       The offset to add to @c rawOffset to obtain the total offset between the local and GMT time @n
 354          *                                                                                              If DST is not in effect, it is zero.
 355          * @exception           E_SUCCESS                                       The method is successful.
 356          * @exception           E_INVALID_ARG                                   The specified @c date is invalid.
 357          * @remarks                     Local millisecond = GMT milliseconds + rawOffset(in milliseconds) + dstOffset(in milliseconds).
 358          *                                      All computations are performed in Gregorian calendar.
 359          */
 360         result GetOffset(const Tizen::Base::DateTime& date, bool local, int& rawOffset, int& dstOffset) const;
 361
 362         /**
 363          * Gets the difference in minutes between the local standard time and GMT, taking into consideration both the raw offset and the effect of DST.
 364          *
 365          * @if OSPCOMPAT
 366          * @brief                               <i> [Compatibility] </i>
 367          * @endif
 368          * @since                       2.0
 369          * @if OSPCOMPAT
 370          * @compatibility     This method has compatibility issues with OSP compatible applications. @n
 371          *                              For more information, see @ref CompTimeZoneGetOffsetPage "here".
 372          * @endif
 373          *
 374          * @return                      An error code
 375          * @param[in]           ticks                                           The time ticks value @n
 376          *                                                                                              The value is GMT time from starting day (Jan 1, 1.).
 377          * @param[out]          offset                                          The offset between the local standard time and GMT, taking into consideration DST
 378          * @exception           E_SUCCESS                                       The method is successful.
 379          * @exception           E_INVALID_ARG                                   The specified @c ticks is invalid.
 380          * @see                 Base::DateTime::GetTicks(), System::SystemTime::GetTicks()
 381          */
 382         result GetOffset(long long ticks, int& offset) const;
 383
 384         /**
 385          * @if OSPCOMPAT
 386          * @page                    CompTimeZoneGetOffsetPage Compatibility for GetOffset()
 387          * @section                   CompTimeZoneGetOffsetIssueSection Issues
 388          * Implementation of this method in OSP compatible applications has the following issue: @n
 389          * -# The method returns E_OUT_OF_RANGE if an argument is invalid.
 390          *
 391          * @section                 CompTimeZoneGetOffsetSolutionSection Resolutions
 392          * This issue has been resolved in Tizen.
 393          * @par When working in Tizen:
 394          * -# The method returns E_INVALID_ARG if an argument is invalid.
 395          * @endif
 396         */
 397
 398         /**
 399          * Gets the difference in minutes between the local standard time and GMT, without including DST (that is, raw offset).
 400          *
 401          * @since                       2.0
 402          *
 403          * @return                      The raw offset
 404          *
 405          */
 406         int GetRawOffset(void) const;
 407
 408         /**
 409          * Gets the ID of the time zone.
 410          *
 411          * @since                       2.0
 412          *
 413          * @return                      The ID of the time zone
 414          */
 415         Tizen::Base::String GetId(void) const;
 416
 417         /**
 418          * Gets the DST starting rule.
 419          *
 420          * @since                       2.0
 421          *
 422          * @return                      A pointer to the DST start rule, @n
 423          *                                      else a @c null pointer if the DST start rule is undefined
 424          */
 425         const TimeRule* GetDstStartingRule(void) const;
 426
 427         /**
 428          * Gets the DST end rule.
 429          *
 430          * @since                       2.0
 431          *
 432          * @return                      A pointer to the DST end rule, @n
 433          *                                      else a @c null pointer if the DST end rule is undefined
 434          */
 435         const TimeRule* GetDstEndingRule(void) const;
 436
 437         /**
 438          * Checks whether the current instance of %TimeZone uses DST.
 439          *
 440          * @since                       2.0
 441          *
 442          * @return                      @c true if the current instance uses DST, @n
 443          *                                      else @c false
 444          */
 445         bool IsDstUsed(void) const;
 446
 447         /**
 448          * Gets the GMT time zone. @n
 449          * The GMT time zone has a raw offset of @c 0 and does not use DST.
 450          *
 451          * @since               2.0
 452          *
 453          * @return              The GMT time zone
 454          */
 455         static TimeZone GetGmtTimeZone(void);
 456
 457         /**
 458          * Gets the time zone instance from the given ID.
 459          *
 460          * @if OSPCOMPAT
 461          * @brief                               <i> [Compatibility] </i>
 462          * @endif
 463          * @since                       2.0
 464          * @if OSPCOMPAT
 465          * @compatibility     This method has compatibility issues with OSP compatible applications. @n
 466          *                              For more information, see @ref CompTimeZoneGetTimeZonePage "here".
 467          * @endif
 468          *
 469          * @return                      An error code
 470          * @param[in]           id                              The time zone ID
 471          * @param[out]          timeZone                The time zone for the given ID
 472          * @exception           E_SUCCESS               The method is successful.
 473          * @exception           E_INVALID_ARG           The specified @c id is invalid.
 474          * @remarks                     The %TimeZone instance for the specified @c id does not contain the DST information.
 475          *                                      The supported time zone list depends on the device. Therefore, it should be checked before using this method.
 476          * @see                         LocaleManager::GetAvailableTimeZonesN()
 477          */
 478         static result GetTimeZone(const Tizen::Base::String& id, Tizen::Locales::TimeZone& timeZone);
 479
 480         /**
 481          * Gets the %TimeZone instance from the specified ID and UTC time.
 482          *
 483          * @if OSPCOMPAT
 484          * @brief                               <i> [Compatibility] </i>
 485          * @endif
 486          * @since                       2.0
 487          * @if OSPCOMPAT
 488          * @compatibility     This method has compatibility issues with OSP compatible applications. @n
 489          *                              For more information, see @ref CompTimeZoneGetTimeZonePage "here".
 490          * @endif
 491          *
 492          * @return                      An error code
 493          * @param[in]           id                              The time zone ID
 494          * @param[in]           utcTime                 The UTC time
 495          * @param[out]          timeZone                The time zone for the specified ID and UTC time
 496          * @exception           E_SUCCESS               The method is successful.
 497          * @exception           E_INVALID_ARG           The specified @c id is invalid.
 498          * @remarks                     The %TimeZone instance for the specified ID and UTC time contains the DST information.
 499          *                                      The supported time zone list depends on the device. Therefore, it should be checked before using this method.
 500          * @see                         LocaleManager::GetAvailableTimeZonesN()
 501          */
 502         static result GetTimeZone(const Tizen::Base::String& id, const Tizen::Base::DateTime& utcTime, Tizen::Locales::TimeZone& timeZone);
 503
 504         /**
 505          * @if OSPCOMPAT
 506          * @page                    CompTimeZoneGetTimeZonePage Compatibility for GetTimeZone()
 507          * @section                   CompTimeZoneGetTimeZoneIssueSection Issues
 508          * Implementation of this method in OSP compatible applications has the following issue: @n
 509          * -# The method returns E_UNSUPPORTED_OPERATION if the time zone ID is invalid.
 510          *
 511          * @section                 CompTimeZoneGetTimeZoneSolutionSection Resolutions
 512          * This issue has been resolved in Tizen.
 513          * @par When working in Tizen:
 514          * -# The method returns E_INVALID_ARG if the time zone ID is invalid.
 515          * @endif
 516         */
 517
 518         /**
 519          * Converts the UTC time to the standard time.
 520          *
 521          * @since               2.0
 522          *
 523          * @return      The standard time
 524          * @param[in]   utcTime                 The UTC time
 525          * @param[in]   rawOffset               The time zone's raw offset in minutes
 526          */
 527         static Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime, int rawOffset);
 528
 529         /**
 530          * Converts the standard time to the UTC time.
 531          *
 532          * @since               2.0
 533          *
 534          * @return      The UTC time
 535          * @param[in]   standardTime            The standard time
 536          * @param[in]   rawOffset               The time zone's raw offset in minutes
 537          */
 538         static Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime, int rawOffset);
 539
 540         /**
 541          * Converts the UTC time to the wall time.
 542          *
 543          * @since               2.0
 544          *
 545          * @return      The wall time
 546          * @param[in]   utcTime             The UTC time
 547          * @param[in]   rawOffset               The time zone's raw offset in minutes
 548          * @param[in]   dstOffset               The amount of time in minutes saved during DST
 549          */
 550         static Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime, int rawOffset, int dstOffset);
 551
 552         /**
 553          * Converts the wall time to the UTC time.
 554          *
 555          * @since               2.0
 556          *
 557          * @return      The UTC time
 558          * @param[in]   wallTime                        The wall time
 559          * @param[in]   rawOffset               The time zone's raw offset in minutes
 560          * @param[in]   dstOffset               The amount of time in minutes saved during DST
 561          */
 562         static Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime, int rawOffset, int dstOffset);
 563
 564 private:
 565
 566         friend class _TimeZoneImpl;
 567         class _TimeZoneImpl* __pTimeZoneImpl;
 568
 569         friend class _LocaleData;
 570 }; // TimeZone
 571
 572 }} // Tizen::Locales
 573 #endif // _FLCL_TIME_ZONE_H_