Update doxygen of TimeZone.
[platform/framework/native/appfw.git] / 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_