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". @n
  47  *
  48  * However, the specialized time zone IDs have the different form, such as CST6CDT, EST5EDT and so on. @n
  49  *
  50  * For more information on IDs, refer <a href="http://www.iana.org/time-zones" target="_blank">Time Zone Database</a>. @n
  51  *
  52  * The supported time zone list depends on the device. Therefore, it must be checked by using LocaleManager::GetAvailableTimeZonesN().
  53  *
  54  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/locales/time_zone.htm">Time Zones</a>.
  55  *
  56  * The following example demonstrates how to use the %TimeZone class.
  57  *
  58 @code
  59
  60 #include <FBase.h>
  61 #include <FSystem.h>
  62 #include <FLocales.h>
  63
  64 using namespace Tizen::Locales;
  65
  66 void
  67 MyClass::MyTimeZone(void)
  68 {
  69         // Gets the system time zone.
  70         LocaleManager localeManager;
  71         localeManager.Construct();
  72
  73         TimeZone timeZone = localeManager.GetSystemTimeZone();
  74
  75         String timeZoneId = timeZone.GetId();
  76         int rawOffset = timeZone.GetRawOffset();
  77         int dstSavings = timeZone.GetDstSavings();
  78
  79         // Gets the special time zone.
  80         DateTime utcTime;
  81         TimeZone timeZone2;
  82         Tizen::System::SystemTime::GetCurrentTime(utcTime);
  83         Tizen::Locales::TimeZone::GetTimeZone(L"Europe/Zurich", utcTime, timeZone2);
  84 }
  85 @endcode
  86  *
  87  */
  88
  89 class _OSP_EXPORT_ TimeZone
  90         : public Tizen::Base::Object
  91 {
  92 public:
  93         /**
  94          * This is the default constructor for this class.
  95          *
  96          * @since               2.0
  97          */
  98         TimeZone(void);
  99
 100
 101         /**
 102          * This is the destructor for this class. @n
 103          * This destructor overrides Tizen::Base::Object::~Object().
 104          *
 105          * @since               2.0
 106          */
 107         virtual ~TimeZone(void);
 108
 109
 110         /**
 111          * This is the copy constructor for the %TimeZone class. @n
 112          * It initializes an instance of %TimeZone with the values of the specified instance of %TimeZone.
 113          * Copying of objects using this copy constructor is allowed.
 114          *
 115          * @since                       2.0
 116          *
 117          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 118          */
 119         TimeZone(const TimeZone& otherTimeZone);
 120
 121         /**
 122          * Assigns the value of the specified instance to the current instance of %TimeZone. @n
 123          * Copying of objects using this copy assignment operator is allowed.
 124          *
 125          * @since                       2.0
 126          *
 127          * @return                      A reference value of the current instance
 128          * @param[in]           otherTimeZone                                   An instance of %TimeZone
 129          *
 130          */
 131         TimeZone& operator =(const TimeZone& otherTimeZone);
 132
 133         /**
 134          * Initializes this instance of %TimeZone with the specified raw GMT offset and the ID of the time zone without including DST.
 135          *
 136          * @since                       2.0
 137          *
 138          * @param[in]           rawOffset                                               The base time zone offset to GMT in minutes
 139          * @param[in]           id                                                              The time zone ID
 140          * @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
 141          *                                      However, the supported time zone list depends on the device. Therefore, it must be checked before using this method.
 142          * @see                         LocaleManager::GetAvailableTimeZonesN()
 143          */
 144         TimeZone(int rawOffset, const Tizen::Base::String& id);
 145
 146         /**
 147          * Initializes this instance of %TimeZone with the specified raw GMT offset,
 148          * the ID of the time zone, the rules for starting/ending DST, and the DST offset.
 149          *
 150          * @since                       2.0
 151          *
 152          * @param[in]           rawOffset                                               The base time zone offset to GMT in minutes
 153          * @param[in]           id                                                              The time zone ID
 154          * @param[in]           startRule                                               The DST starting rule
 155          * @param[in]           endRule                                                 The DST end rule
 156          * @param[in]           dstOffset                                               The amount of time in minutes saved during DST
 157          * @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
 158          *                                      However, the supported time zone list depends on the device. Therefore, it must be checked before using this method.
 159          * @see                         LocaleManager::GetAvailableTimeZonesN()
 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 instance of %TimeZone equals the value of 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 %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 compatibile 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).
 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 and the effect of DST.
 365          *
 366          * @if OSPCOMPAT
 367          * @brief                               <i> [Compatibility] </i>
 368          * @endif
 369          * @since                       2.0
 370          * @if OSPCOMPAT
 371          * @compatibility     This method has compatibility issues with OSP compatibile applications. @n
 372          *                              For more information, see @ref CompTimeZoneGetOffsetPage "here".
 373          * @endif
 374          *
 375          * @return                      An error code
 376          * @param[in]           ticks                                           The time ticks value @n
 377          *                                                                                              The value is GMT time.
 378          * @param[out]          offset                                          The offset between the local standard time and GMT, taking into consideration DST
 379          * @exception           E_SUCCESS                                       The method is successful.
 380          * @exception           E_INVALID_ARG                                   The specified @c ticks is invalid.
 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 compatibile 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 compatibile 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_