1 tz.h |
1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __TIMEZONE_H__ |
|
17 #define __TIMEZONE_H__ |
|
18 |
|
19 #include <e32base.h> |
|
20 #include <s32std.h> |
|
21 #include <tzdefines.h> |
|
22 #include <tzupdate.h> |
|
23 |
|
24 class CTzChangeNotifier; |
|
25 class CTzRules; |
|
26 class CTzRuleHolder; |
|
27 |
|
28 //------------------------------------------------------------------------- |
|
29 /** |
|
30 Encapsulates a time zone identifier. |
|
31 |
|
32 The identifier may be either a name or a number. |
|
33 @publishedAll |
|
34 @released |
|
35 @since 9.1 |
|
36 */ |
|
37 class CTzId : public CBase |
|
38 { |
|
39 public: |
|
40 |
|
41 IMPORT_C ~CTzId(); |
|
42 |
|
43 /** |
|
44 @internalComponent |
|
45 */ |
|
46 IMPORT_C CTzId* CloneL() const; |
|
47 |
|
48 IMPORT_C static CTzId* NewL(TUint aNumericId); |
|
49 |
|
50 IMPORT_C static CTzId* NewL(const TDesC8& aNameIdentity); |
|
51 |
|
52 /** |
|
53 @internalComponent |
|
54 */ |
|
55 IMPORT_C static CTzId* NewL(RReadStream& aStream); |
|
56 |
|
57 /** |
|
58 @internalComponent |
|
59 */ |
|
60 IMPORT_C void SetId(TUint aNumericId); |
|
61 |
|
62 /** |
|
63 @internalComponent |
|
64 */ |
|
65 IMPORT_C void SetIdL(const TDesC8& aNameIdentity); |
|
66 |
|
67 /** |
|
68 @internalComponent |
|
69 */ |
|
70 IMPORT_C void InternalizeL(RReadStream& aStream); |
|
71 |
|
72 /** |
|
73 @internalComponent |
|
74 */ |
|
75 IMPORT_C void ExternalizeL(RWriteStream& aStream) const; |
|
76 |
|
77 IMPORT_C const TDesC8& TimeZoneNameID() const; |
|
78 |
|
79 IMPORT_C TUint TimeZoneNumericID() const; |
|
80 |
|
81 IMPORT_C TBool operator==(const CTzId& aTZId) const; |
|
82 |
|
83 inline TBool operator!=(const CTzId& aTZId) const; |
|
84 |
|
85 public: |
|
86 static CTzId* NewL(TUint aReferenceId, const TDesC8& aZoneIdentity); |
|
87 void SetIdL(TUint aNumRefId, const TDesC8& aZoneIdentity); |
|
88 |
|
89 private: |
|
90 void ConstructL(const TDesC8& aZoneIdentity); |
|
91 CTzId(); |
|
92 CTzId(TUint aNumericId); |
|
93 |
|
94 private: |
|
95 HBufC8* iZoneId; |
|
96 TUint32 iReferenceId; |
|
97 }; |
|
98 |
|
99 |
|
100 /** |
|
101 The client interface to the time zone server. |
|
102 |
|
103 This class performs two basic functions: |
|
104 1. Converts between UTC time and local time. |
|
105 2. Sets the current local time zone. |
|
106 |
|
107 NOTE: The presence of a time zone server will alter the behaviour of the |
|
108 time zone related function calls User::SetUTCOffset() and |
|
109 User::SetUTCTimeAndOffset(). The time zone server is shutdown when the |
|
110 last session (RTz) is closed. Therefore, to maintain consistent time related behaviour, |
|
111 licensees may want to keep a system level time zone server session open at all times. |
|
112 |
|
113 @see User |
|
114 |
|
115 Exceptional cases occur when a user requests conversion |
|
116 for a non-existent local time or a double local time. |
|
117 |
|
118 Non-existent local times occur when the local time |
|
119 changes from winter to summer for DST. |
|
120 |
|
121 For example, 01:59 local time is non-existent on the day of a change to BST |
|
122 in Europe/London since the time changes directly from 12:59:59 to 2:00. |
|
123 |
|
124 A double local time occurs when the local time changes from |
|
125 summer to winter. |
|
126 |
|
127 For example, if the time changes at 02:00 AM BST to 01:00 AM GMT |
|
128 then local times between 01:00 and 01:59 occur twice. |
|
129 |
|
130 The conversion applies the DST offset if the local time value is double and applies |
|
131 the standard UTC offset if the local time does not exists. |
|
132 |
|
133 This decision makes the conversion process asymmetrical around |
|
134 the discontinuity in the local time when there is a DST change. |
|
135 |
|
136 An example conversion from a double local time to UTC and |
|
137 from UTC to a double local time is: |
|
138 |
|
139 01:59 AM BST => 00:59 AM UTC |
|
140 01:59 AM UTC => 01:59 AM GMT |
|
141 |
|
142 An example conversion from a non-existent local time to UTC |
|
143 and from UTC to local time is: |
|
144 |
|
145 01:59 AM GMT => 01:59 AM UTC |
|
146 01:59 AM UTC => 02:59 AM BST |
|
147 |
|
148 |
|
149 @publishedAll |
|
150 @released |
|
151 @since 9.1 |
|
152 */ |
|
153 class RTz : public RSessionBase |
|
154 { |
|
155 public: |
|
156 /** |
|
157 These enumerators are to describe different modes of the automatic |
|
158 DST event handling. |
|
159 |
|
160 These are used both as arguments for the API SetAutoUpdateBehaviorL, |
|
161 and as notifications for the publish and subscribe. |
|
162 */ |
|
163 enum TTzAutoDSTUpdateModes |
|
164 { |
|
165 /** No auto update notification when a DST event occurs. */ |
|
166 ETZAutoDSTUpdateOff = 0, |
|
167 |
|
168 /** Automatic time update will occur and the client app will be notified. */ |
|
169 ETZAutoDSTUpdateOn, |
|
170 |
|
171 /** Client app needs to confirm that the time should be updated whenever a DST event occurs. */ |
|
172 ETZAutoDSTNotificationOnly, |
|
173 }; |
|
174 |
|
175 enum TTzChanges |
|
176 { |
|
177 /** Used for notifying that the timezone database has changed.*/ |
|
178 ETZDatabaseChanged = 1, |
|
179 /** Used for notifying that the system timezone database has changed.*/ |
|
180 ETZSystemTimeZoneChanged, |
|
181 /** Used for notifying that the DST rule has changed. */ |
|
182 ETZDSTRuleChanged, |
|
183 /** Used for notifying that an automatic time update has taken place. */ |
|
184 ETZAutomaticTimeUpdate |
|
185 }; |
|
186 |
|
187 enum TPanic |
|
188 { |
|
189 /** This panic indicates that the time zone server has not been found.*/ |
|
190 EPanicServerNotFound = 1, |
|
191 /** This panic indicates that the server has died.*/ |
|
192 EPanicServerDead, |
|
193 /** This panic indicates that the time zone ID is not set.*/ |
|
194 EPanicTimeZoneNameIdNotSet, |
|
195 /** This panic indicates that an out of range index was accessed.*/ |
|
196 EPanicRulesIndexOutofRange, |
|
197 /** This panic indicates that there are no rules present for this time zone.*/ |
|
198 EPanicTimeNotCoveredByRules, |
|
199 /** This panic indicates that the time zone rules are unusable.*/ |
|
200 EPanicBadTimeZoneRules, |
|
201 /** This panic indicates that an unsupported time reference has been accessed.*/ |
|
202 EPanicUnsupportedTimeReference, |
|
203 /** This panic indicates that the time zone ID is not supported.*/ |
|
204 EPanicUnsupportedTimeZoneNoId, |
|
205 /** This panic indicates that a request for notification is already pending from the client.*/ |
|
206 EPanicNotificationRequestPending, |
|
207 /** This panic indicates that an incorrect data has been sent to the server.*/ |
|
208 EPanicInvalidArgument |
|
209 }; |
|
210 |
|
211 /** |
|
212 @internalComponent |
|
213 */ |
|
214 IMPORT_C static void Panic(TPanic aPanic); |
|
215 |
|
216 /** |
|
217 @internalTechnology |
|
218 */ |
|
219 IMPORT_C CTzId* GetTimeZoneIdL() const; |
|
220 |
|
221 /** |
|
222 @internalTechnology |
|
223 */ |
|
224 IMPORT_C void SetTimeZoneL(CTzId& aZone) const; |
|
225 |
|
226 IMPORT_C void Close(); |
|
227 |
|
228 IMPORT_C TInt Connect(); |
|
229 |
|
230 IMPORT_C ~RTz(); |
|
231 |
|
232 IMPORT_C RTz(); |
|
233 |
|
234 IMPORT_C TInt ConvertToLocalTime(TTime& aTime) const; |
|
235 |
|
236 IMPORT_C TInt ConvertToLocalTime(TTime& aTime, const CTzId& aZone) const; |
|
237 |
|
238 IMPORT_C TInt ConvertToUniversalTime(TTime& aTime) const; |
|
239 |
|
240 IMPORT_C TInt ConvertToUniversalTime(TTime& aTime, const CTzId& aZone) const; |
|
241 |
|
242 IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray<TInt>& aTzNumericIds, RArray<TInt>& aOffsets) const; |
|
243 |
|
244 IMPORT_C TInt AutoUpdateSettingL(); |
|
245 |
|
246 IMPORT_C void SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes aUpdateEnabled); |
|
247 |
|
248 // Methods for setting the system time. |
|
249 IMPORT_C TInt SetHomeTime(const TTime& aLocalTime) const; |
|
250 |
|
251 IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone) const; |
|
252 |
|
253 IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone, const TTime& aUTCTime) const; |
|
254 |
|
255 // Get Encoded Rules for Current Local Time Zone |
|
256 IMPORT_C CTzRules* GetTimeZoneRulesL(const TTime& aStartTime, const TTime& aEndTime, TTzTimeReference aTimeRef) const; |
|
257 |
|
258 IMPORT_C CTzRules* GetTimeZoneRulesL(const CTzId& aZone, const TTime& aStartTime, const TTime& aEndTime, TTzTimeReference aTimeRef) const; |
|
259 |
|
260 void RegisterTzChangeNotifier(TRequestStatus& aStatus) const; |
|
261 TInt CancelRequestForNotice() const; |
|
262 TVersion Version() const; |
|
263 |
|
264 IMPORT_C void NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange& aChange) const; |
|
265 |
|
266 IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset); |
|
267 |
|
268 IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset, TBool aPersistInCenRep); |
|
269 |
|
270 IMPORT_C void __dbgClearCacheL(TBool aRestartCaching); |
|
271 |
|
272 TBool StartCachingL(); |
|
273 TUint16 CurrentCachedTzId(); |
|
274 |
|
275 private: |
|
276 static TInt StartServer(); |
|
277 TInt DoConnect(); |
|
278 void doConvertL(const CTzId& aZone, TTime& aTime, |
|
279 TTzTimeReference aTimerRef) const; |
|
280 void doConvertL(TTime& aTime, |
|
281 TTzTimeReference aTimerRef) const; |
|
282 private: |
|
283 CTzRuleHolder* iRulesHolder; |
|
284 }; |
|
285 |
|
286 /** |
|
287 Encapsulates a TTime and a TTzTimeReference. |
|
288 Use, for example, for iCalendar's DTSTART. |
|
289 |
|
290 @publishedAll |
|
291 @released |
|
292 */ |
|
293 class TTimeWithReference |
|
294 { |
|
295 public: |
|
296 static inline TTimeWithReference Max(); |
|
297 inline TTimeWithReference(); |
|
298 inline TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference); |
|
299 inline TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference); |
|
300 inline bool operator==(const TTimeWithReference& aTime) const; |
|
301 inline bool operator!=(const TTimeWithReference& aTime) const; |
|
302 |
|
303 TTime iTime; |
|
304 TTzTimeReference iTimeReference; |
|
305 }; |
|
306 |
|
307 /** Inequality operator. |
|
308 |
|
309 @param aTZId The time zone ID to compare with this one. |
|
310 @return True if the two IDs are different. False if they are the same. |
|
311 */ |
|
312 inline TBool CTzId::operator!=(const CTzId& aTZId) const |
|
313 { |
|
314 return (!operator==(aTZId)); |
|
315 } |
|
316 |
|
317 ////////////////////////////////// |
|
318 // TTimeWithReference |
|
319 ////////////////////////////////// |
|
320 inline TTimeWithReference TTimeWithReference::Max() |
|
321 { |
|
322 return TTimeWithReference( |
|
323 TDateTime(9999,EDecember,30,23,59,59,0), |
|
324 ETzUtcTimeReference); |
|
325 } |
|
326 |
|
327 inline TTimeWithReference::TTimeWithReference() |
|
328 : iTime(0), iTimeReference(ETzUtcTimeReference) |
|
329 { |
|
330 } |
|
331 inline TTimeWithReference::TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference) |
|
332 : iTime(aTime), iTimeReference(aTimeReference) |
|
333 { |
|
334 } |
|
335 inline TTimeWithReference::TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference) |
|
336 : iTime(aTime), iTimeReference(aTimeReference) |
|
337 { |
|
338 } |
|
339 inline bool TTimeWithReference::operator==(const TTimeWithReference& aTime) const |
|
340 { |
|
341 return(aTime.iTime == iTime && aTime.iTimeReference == iTimeReference); |
|
342 } |
|
343 inline bool TTimeWithReference::operator!=(const TTimeWithReference& aTime) const |
|
344 { |
|
345 return(!(*this == aTime)); |
|
346 } |
|
347 #endif |