inc/FLclTimeZone.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17
  18 /**
  19  * @file                FLclTimeZone.h
  20  * @brief               This is the header file for the %TimeZone class.
  21  * @see                 Tizen::Locales::Locale
  22  *
  23  * This header file contains the declarations of the %TimeZone class.
  24  */
  25
  26 #ifndef _FLCL_TIME_ZONE_H_
  27 #define _FLCL_TIME_ZONE_H_
  28
  29 #include <FBaseString.h>
  30 #include <FBaseDateTime.h>
  31 #include <FLclTimeRule.h>
  32
  33 namespace Tizen { namespace Locales
  34 {
  35
  36 /**
  37  * @class               TimeZone
  38  * @brief               This class represents the time zones.
  39  *
  40  * @since               2.0
  41  *
  42  * @final       This class is not intended for extension.
  43  *
  44  * The %TimeZone class represents a time zone offset and figures out Daylight Saving Time (DST).
  45  *
  46  * The form of time zone ID is "Area/Location". However, the specialized time zone IDs have the different form.@n
  47  *
  48  * The IDs are defined in <a href="http://www.iana.org/time-zones" target="_blank">Time Zone Database</a>. @n
  49  *
  50  * The supported time zone list depends on the device. Therefore, it must be checked by using LocaleManager::GetAvailableTimeZonesN().
  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 <FLocales.h>
  59
  60 using namespace Tizen::Locales;
  61
  62 void
  63 MyClass::MyTimeZone(void)
  64 {
  65         // Gets the system time zone.
  66         LocaleManager localeManager;
  67         localeManager.Construct();
  68
  69         TimeZone timeZone = localeManager.GetSystemTimeZone();
  70
  71         String timeZoneId = timeZone.GetId();
  72         int rawOffset = timeZone.GetRawOffset();
  73         int dstSavings = timeZone.GetDstSavings();
  74
  75         // Gets the special time zone.
  76         TimeZone timeZone2;
  77         Tizen::Locales::TimeZone::GetTimeZone(L"Europe/Zurich", timeZone2);
  78 }
  79 @endcode
  80  *
  81  */
  82
  83 class _OSP_EXPORT_ TimeZone
  84         : public Tizen::Base::Object
  85 {
  86 public:
  87         /**
  88          * This is the default constructor for this class.
  89          *
  90          * @since               2.0
  91          */
  92         TimeZone(void);
  93
  94
  95         /**
  96          * This is the destructor for this class. @n
  97          * This destructor overrides Tizen::Base::Object::~Object().
  98          *
  99          * @since               2.0
 100          */
 101         virtual ~TimeZone(void);
 102
 103
 104         /**
 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.
 108          *
 109          * @since                       2.0
 110          *
 111          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 112          */
 113         TimeZone(const TimeZone& otherTimeZone);
 114
 115         /**
 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.
 118          *
 119          * @since                       2.0
 120          *
 121          * @return                      A reference value of the current instance
 122          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 123          *
 124          */
 125         TimeZone& operator =(const TimeZone& otherTimeZone);
 126
 127         /**
 128          * Initializes this instance of %TimeZone with the specified raw GMT offset and the ID of the time zone without including DST.
 129          *
 130          * @since                       2.0
 131          *
 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()
 137          */
 138         TimeZone(int rawOffset, const Tizen::Base::String& id);
 139
 140         /**
 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.
 143          *
 144          * @since                       2.0
 145          *
 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()
 154          */
 155         TimeZone(int rawOffset, const Tizen::Base::String& id,
 156                 const TimeRule& startRule, const TimeRule& endRule, int dstOffset);
 157
 158         /**
 159          * Checks whether the specified instance of %TimeZone equals the value of the current instance.
 160          *
 161          * @since                       2.0
 162          *
 163          * @return                      @c true if the two instances are equal, @n
 164          *                                      else @c false
 165          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 166          */
 167         bool operator ==(const TimeZone& otherTimeZone) const;
 168
 169         /**
 170          * Checks whether the %TimeZone instance is equal to the current instance.
 171          *
 172          * @since                       2.0
 173          *
 174          * @return                      @c true if the two instances are not equal, @n
 175          *                                      else @c false
 176          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 177          */
 178         bool operator !=(const TimeZone& otherTimeZone) const;
 179
 180         /**
 181         * Compares the value of the specified instance to that of the current instance.
 182         *
 183         * @since                        2.0
 184         *
 185         * @return                       @c true if the value of the specified instance is equal to that of the current instance, @n
 186         *                                         else @c false
 187         * @param[in]            obj The object to compare with the current instance
 188         */
 189         virtual bool Equals(const Tizen::Base::Object& obj) const;
 190
 191         /**
 192         * Gets the hash value of the current instance.
 193         *
 194         * @since                        2.0
 195         *
 196         * @return                       The hash value of the current instance
 197         */
 198         virtual int GetHashCode(void) const;
 199
 200         /**
 201         * Sets the DST time.
 202         *
 203         * @since                        2.0
 204         *
 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.
 207         */
 208         void SetDstSavings(int dstSavings);
 209
 210         /**
 211          * Sets the DST starting and end rule.
 212          *
 213          * @since                       2.0
 214          *
 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.
 221          */
 222         result SetDstRules(const TimeRule& startRule, const TimeRule& endRule, int dstSavings = 60);
 223
 224         /**
 225          * Sets the DST end rule.
 226          *
 227          * @since                       2.0
 228          *
 229          * @param[in]           endRule                                                 The DST end rule
 230          */
 231         void SetDstEndingRule(const TimeRule& endRule);
 232
 233         /**
 234          * Sets the DST starting rule.
 235          *
 236          * @since                       2.0
 237          *
 238          * @param[in]           startRule                                               The DST starting rule
 239          */
 240         void SetDstStartingRule(const TimeRule& startRule);
 241
 242         /**
 243          * Sets the difference in minutes between the local standard time and GMT,
 244          * without including DST (that is, raw offset).
 245          *
 246          * @since                       2.0
 247          *
 248          * @param[in]           rawOffset                                               The difference in minutes between the local standard time and GMT, without including DST
 249          */
 250         void SetRawOffset(int rawOffset);
 251
 252         /**
 253          * Sets the DST starting year.
 254          *
 255          * @since                       2.0
 256          *
 257          * @param[in]           year                                                    The DST starting year
 258          */
 259         void SetDstStartingYear(int year);
 260
 261         /**
 262          * Sets the ID of the time zone.
 263          *
 264          * @since                       2.0
 265          *
 266          * @param[in]           id                                                              The ID of the time zone
 267          */
 268         void SetId(const Tizen::Base::String& id);
 269
 270         /**
 271          * Converts the Coordinated Universal Time (UTC) time to the standard time.
 272          *
 273          * @since                               2.0
 274          *
 275          * @return                      The standard time
 276          * @param[in]           utcTime                                                 The UTC time
 277          */
 278         Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime);
 279
 280         /**
 281          * Converts the UTC time to the wall time.
 282          *
 283          * @since                       2.0
 284          *
 285          * @return                      The wall time
 286          * @param[in]           utcTime                                                 The UTC time
 287          */
 288         Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime);
 289
 290         /**
 291          * Converts the standard time to the UTC time.
 292          *
 293          * @since                       2.0
 294          *
 295          * @return                      The UTC time
 296          * @param[in]           standardTime                                    The standard time
 297          */
 298         Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime);
 299
 300         /**
 301          * Converts the wall time to the UTC time.
 302          *
 303          * @since                               2.0
 304          *
 305          * @return                      The UTC time
 306          * @param[in]           wallTime                                                The wall time
 307          */
 308         Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime);
 309
 310         /**
 311          * Gets the amount of time in minutes to be added to the local standard time to get the local wall time.
 312          *
 313          * @since                       2.0
 314          *
 315          * @return                      The amount of time in minutes
 316          *
 317          */
 318         int GetDstSavings(void) const;
 319
 320         /**
 321          * Gets the starting year of the DST.
 322          *
 323          * @since                       2.0
 324          *
 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()
 328          */
 329         int GetDstStartingYear(void) const;
 330
 331         /**
 332          * Gets the raw and GMT offset for the specified instance of Tizen::Base::DateTime in the current time zone.
 333          *
 334          * @if OSPCOMPAT
 335          * @brief                               <i> [Compatibility] </i>
 336          * @endif
 337          * @since                       2.0
 338          * @if OSPCOMPAT
 339          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
 340          *                              For more information, see @ref CompTimeZoneGetOffsetPage "here".
 341          * @endif
 342          *
 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.
 354          */
 355         result GetOffset(const Tizen::Base::DateTime& date, bool local, int& rawOffset, int& dstOffset) const;
 356
 357         /**
 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.
 359          *
 360          * @if OSPCOMPAT
 361          * @brief                               <i> [Compatibility] </i>
 362          * @endif
 363          * @since                       2.0
 364          * @if OSPCOMPAT
 365          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
 366          *                              For more information, see @ref CompTimeZoneGetOffsetPage "here".
 367          * @endif
 368          *
 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.
 375          */
 376         result GetOffset(long long ticks, int& offset) const;
 377
 378         /**
 379          * @if OSPCOMPAT
 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.
 384          *
 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.
 389          * @endif
 390         */
 391
 392         /**
 393          * Gets the difference in minutes between the local standard time and GMT, without including DST (that is, raw offset).
 394          *
 395          * @since                       2.0
 396          *
 397          * @return                      The raw offset
 398          *
 399          */
 400         int GetRawOffset(void) const;
 401
 402         /**
 403          * Gets the ID of the time zone.
 404          *
 405          * @since                       2.0
 406          *
 407          * @return                      The ID of the time zone
 408          */
 409         Tizen::Base::String GetId(void) const;
 410
 411         /**
 412          * Gets the DST starting rule.
 413          *
 414          * @since                       2.0
 415          *
 416          * @return                      A pointer to the DST start rule, @n
 417          *                                      else a @c null pointer if the DST start rule is undefined
 418          */
 419         const TimeRule* GetDstStartingRule(void) const;
 420
 421         /**
 422          * Gets the DST end rule.
 423          *
 424          * @since                       2.0
 425          *
 426          * @return                      A pointer to the DST end rule, @n
 427          *                                      else a @c null pointer if the DST end rule is undefined
 428          */
 429         const TimeRule* GetDstEndingRule(void) const;
 430
 431         /**
 432          * Checks whether the current instance of %TimeZone uses DST.
 433          *
 434          * @since                       2.0
 435          *
 436          * @return                      @c true if the current instance uses DST, @n
 437          *                                      else @c false
 438          */
 439         bool IsDstUsed(void) const;
 440
 441         /**
 442          * Gets the GMT time zone. @n
 443          * The GMT time zone has a raw offset of @c 0 and does not use DST.
 444          *
 445          * @since               2.0
 446          *
 447          * @return              The GMT time zone
 448          */
 449         static TimeZone GetGmtTimeZone(void);
 450
 451         /**
 452          * Gets the time zone instance from the given ID.
 453          *
 454          * @if OSPCOMPAT
 455          * @brief                               <i> [Compatibility] </i>
 456          * @endif
 457          * @since                       2.0
 458          * @if OSPCOMPAT
 459          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
 460          *                              For more information, see @ref CompTimeZoneGetTimeZonePage "here".
 461          * @endif
 462          *
 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()
 471          */
 472         static result GetTimeZone(const Tizen::Base::String& id, Tizen::Locales::TimeZone& timeZone);
 473
 474         /**
 475          * Gets the %TimeZone instance from the specified ID and UTC time.
 476          *
 477          * @if OSPCOMPAT
 478          * @brief                               <i> [Compatibility] </i>
 479          * @endif
 480          * @since                       2.0
 481          * @if OSPCOMPAT
 482          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
 483          *                              For more information, see @ref CompTimeZoneGetTimeZonePage "here".
 484          * @endif
 485          *
 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()
 495          */
 496         static result GetTimeZone(const Tizen::Base::String& id, const Tizen::Base::DateTime& utcTime, Tizen::Locales::TimeZone& timeZone);
 497
 498         /**
 499          * @if OSPCOMPAT
 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.
 504          *
 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.
 509          * @endif
 510         */
 511
 512         /**
 513          * Converts the UTC time to the standard time.
 514          *
 515          * @since               2.0
 516          *
 517          * @return      The standard time
 518          * @param[in]   utcTime                 The UTC time
 519          * @param[in]   rawOffset               The time zone's raw offset in minutes
 520          */
 521         static Tizen::Base::DateTime UtcTimeToStandardTime(const Tizen::Base::DateTime& utcTime, int rawOffset);
 522
 523         /**
 524          * Converts the standard time to the UTC time.
 525          *
 526          * @since               2.0
 527          *
 528          * @return      The UTC time
 529          * @param[in]   standardTime            The standard time
 530          * @param[in]   rawOffset               The time zone's raw offset in minutes
 531          */
 532         static Tizen::Base::DateTime StandardTimeToUtcTime(const Tizen::Base::DateTime& standardTime, int rawOffset);
 533
 534         /**
 535          * Converts the UTC time to the wall time.
 536          *
 537          * @since               2.0
 538          *
 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
 543          */
 544         static Tizen::Base::DateTime UtcTimeToWallTime(const Tizen::Base::DateTime& utcTime, int rawOffset, int dstOffset);
 545
 546         /**
 547          * Converts the wall time to the UTC time.
 548          *
 549          * @since               2.0
 550          *
 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
 555          */
 556         static Tizen::Base::DateTime WallTimeToUtcTime(const Tizen::Base::DateTime& wallTime, int rawOffset, int dstOffset);
 557
 558 private:
 559
 560         friend class _TimeZoneImpl;
 561         class _TimeZoneImpl* __pTimeZoneImpl;
 562
 563         friend class _LocaleData;
 564 }; // TimeZone
 565
 566 }} // Tizen::Locales
 567 #endif // _FLCL_TIME_ZONE_H_