|
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 "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.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 |
|
20 #include <e32base.h> |
|
21 #include <s32std.h> |
|
22 #include <s32strm.h> |
|
23 #include <tzdefines.h> |
|
24 #include <tzid.h> |
|
25 #include <tzupdate.h> |
|
26 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
27 #include <tzlocalizedcityrecord.h> //This should be be included as it is internalTechnology. |
|
28 #include <tzlocalizedtimezonerecord.h> // Same as above and probably should not be exported to the epoc include |
|
29 #endif |
|
30 |
|
31 |
|
32 // Forward class references. |
|
33 class CTzRules; |
|
34 class CTzRuleHolder; |
|
35 class CTzLocalizedCityRecord; |
|
36 #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS // This can be forward declared i.e. it should not be included as it is internal. |
|
37 class CTzLocalizedTimeZoneRecord; |
|
38 #endif |
|
39 |
|
40 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
41 /** |
|
42 The CTzUserNames class is used to encapsulate the names for a user-defined |
|
43 time zone. |
|
44 |
|
45 When creating an instance of this class the client can specify the following |
|
46 names: |
|
47 |
|
48 - Long standard time name, for example "Mountain Standard Time" |
|
49 - Short standard time name, for example "MST" |
|
50 - Long daylight saving time name, for example "Mountain Daylight Time" |
|
51 - Short daylight saving time name, for example "MDT" |
|
52 - City name, for example "Shiprock" |
|
53 - Region name, for example "America" |
|
54 |
|
55 The client can also read these names. |
|
56 |
|
57 @publishedPartner |
|
58 @released |
|
59 */ |
|
60 class CTzUserNames : public CBase |
|
61 { |
|
62 public: |
|
63 IMPORT_C static CTzUserNames* NewL(const TDesC& aStandardName, |
|
64 const TDesC& aShortStandardName, const TDesC& aDaylightSaveName, |
|
65 const TDesC& aShortDaylightSaveName, const TDesC& aCityName, |
|
66 const TDesC& aRegionName); |
|
67 IMPORT_C static CTzUserNames* NewLC(const TDesC& aStandardName, |
|
68 const TDesC& aShortStandardName, const TDesC& aDayLightSaveName, |
|
69 const TDesC& aShortDaylightSaveName, const TDesC& aCityName, |
|
70 const TDesC& aRegionName); |
|
71 IMPORT_C ~CTzUserNames(); |
|
72 |
|
73 IMPORT_C const TDesC& StandardName() const; |
|
74 IMPORT_C const TDesC& ShortStandardName() const; |
|
75 IMPORT_C const TDesC& DaylightSaveName() const; |
|
76 IMPORT_C const TDesC& ShortDaylightSaveName() const; |
|
77 IMPORT_C const TDesC& CityName() const; |
|
78 IMPORT_C const TDesC& RegionName() const; |
|
79 |
|
80 IMPORT_C static CTzUserNames* NewL(RReadStream& aStream); |
|
81 IMPORT_C void ExternalizeL(RWriteStream& aStream) const; |
|
82 IMPORT_C void InternalizeL(RReadStream& aStream); |
|
83 IMPORT_C TInt SizeOfObject() const; |
|
84 |
|
85 private: |
|
86 CTzUserNames(); |
|
87 void ConstructL(const TDesC& aStandardName, const TDesC& aShortStandardName, |
|
88 const TDesC& aDayLightSaveName, const TDesC& aShortDayLightSaveName, |
|
89 const TDesC& aCityName, const TDesC& aRegionName); |
|
90 |
|
91 private: |
|
92 HBufC* iStandardName; |
|
93 HBufC* iShortStandardName; |
|
94 HBufC* iDaylightName; |
|
95 HBufC* iShortDaylightName; |
|
96 HBufC* iCityName; |
|
97 HBufC* iRegionName; |
|
98 }; |
|
99 #else |
|
100 class CTzUserNames; |
|
101 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS |
|
102 /** |
|
103 The client interface to the time zone server. |
|
104 |
|
105 This class performs two basic functions: |
|
106 |
|
107 1. Converts between UTC time and local time. |
|
108 2. Sets the current local time zone. |
|
109 |
|
110 NOTE: The presence of a time zone server will alter the behaviour of the |
|
111 time zone related function calls User::SetUTCOffset() and |
|
112 User::SetUTCTimeAndOffset(). The time zone server is shutdown when the last |
|
113 session (RTz) is closed. Therefore, to maintain consistent time related |
|
114 behaviour, licensees may want to keep a system level time zone server session |
|
115 open at all times. |
|
116 |
|
117 Exceptional cases occur when a user requests conversion for a non-existent local |
|
118 time or a double local time. |
|
119 |
|
120 Non-existent local times occur when the local time changes from winter to summer |
|
121 for DST. |
|
122 |
|
123 For example, 01:59 local time is non-existent on the day of a change to BST in |
|
124 Europe/London since the time changes directly from 12:59:59 to 2:00. |
|
125 |
|
126 A double local time occurs when the local time changes from summer to winter. |
|
127 |
|
128 For example, if the time changes at 02:00 AM BST to 01:00 AM GMT then local |
|
129 times between 01:00 and 01:59 occur twice. |
|
130 |
|
131 The conversion applies the DST offset if the local time value is double and |
|
132 applies the standard UTC offset if the local time does not exists. |
|
133 |
|
134 This decision makes the conversion process asymmetrical around the discontinuity |
|
135 in the local time when there is a DST change. |
|
136 |
|
137 An example conversion from a double local time to UTC and from UTC to a double |
|
138 local time is: |
|
139 |
|
140 01:59 AM BST => 00:59 AM UTC |
|
141 01:59 AM UTC => 01:59 AM GMT |
|
142 |
|
143 An example conversion from a non-existent local time to UTC |
|
144 and from UTC to local time is: |
|
145 |
|
146 01:59 AM GMT => 01:59 AM UTC |
|
147 01:59 AM UTC => 02:59 AM BST |
|
148 |
|
149 @publishedAll |
|
150 @released |
|
151 @since 9.1 |
|
152 */ |
|
153 class RTz : public RSessionBase |
|
154 { |
|
155 public: |
|
156 /** |
|
157 Automatic DST update mode. |
|
158 */ |
|
159 enum TTzAutoDSTUpdateModes |
|
160 { |
|
161 /** No auto update notification when a DST event occurs. */ |
|
162 ETZAutoDSTUpdateOff = 0, |
|
163 |
|
164 /** Automatic time update will occur and the client app will be |
|
165 notified. */ |
|
166 ETZAutoDSTUpdateOn, |
|
167 |
|
168 /** Client app needs to confirm that the time should be updated whenever |
|
169 a DST event occurs. */ |
|
170 ETZAutoDSTNotificationOnly, |
|
171 }; |
|
172 |
|
173 /** |
|
174 Time zone server change events. |
|
175 */ |
|
176 enum TTzChanges |
|
177 { |
|
178 /** Used for notifying that the timezone database has changed.*/ |
|
179 ETZDatabaseChanged = 1, |
|
180 /** Used for notifying that the system timezone has changed.*/ |
|
181 ETZSystemTimeZoneChanged, |
|
182 /** Used for notifying that the DST rule has changed. */ |
|
183 ETZDSTRuleChanged, |
|
184 /** Used for notifying that an automatic time update has taken place. */ |
|
185 ETZAutomaticTimeUpdate, |
|
186 /** Used for notifying that a change in localization resources has taken |
|
187 place. */ |
|
188 ETZLocalizationDataChanged |
|
189 }; |
|
190 |
|
191 /** |
|
192 Time zone server panic codes. |
|
193 */ |
|
194 enum TPanic |
|
195 { |
|
196 /** This panic indicates that the time zone server has not been found.*/ |
|
197 EPanicServerNotFound = 1, |
|
198 /** This panic indicates that the server has died.*/ |
|
199 EPanicServerDead, |
|
200 /** This panic indicates that the time zone ID is not set.*/ |
|
201 EPanicTimeZoneNameIdNotSet, |
|
202 /** This panic indicates that an out of range index was accessed.*/ |
|
203 EPanicRulesIndexOutofRange, |
|
204 /** This panic indicates that there are no rules present for this time |
|
205 zone.*/ |
|
206 EPanicTimeNotCoveredByRules, |
|
207 /** This panic indicates that the time zone rules are unusable.*/ |
|
208 EPanicBadTimeZoneRules, |
|
209 /** This panic indicates that an unsupported time reference has been |
|
210 accessed.*/ |
|
211 EPanicUnsupportedTimeReference, |
|
212 /** This panic indicates that the time zone ID is not supported.*/ |
|
213 EPanicUnsupportedTimeZoneNoId, |
|
214 /** This panic indicates that a request for notification is already |
|
215 pending from the client.*/ |
|
216 EPanicNotificationRequestPending, |
|
217 /** This panic indicates that an incorrect data has been sent to the |
|
218 server.*/ |
|
219 EPanicInvalidArgument, |
|
220 /** This panic indicates that a table in the user-defined time zone |
|
221 database has not conformed to the declared schema. */ |
|
222 EPanicBadSchema |
|
223 }; |
|
224 |
|
225 /** |
|
226 The software install observer plugin can distinguish between changes to the |
|
227 resource files or the rules database. This enumeration indicates the filter |
|
228 index that is used for the resource files and rules database filters. |
|
229 This enum should not be used externally. |
|
230 */ |
|
231 enum TSWIObserverFilterIndex |
|
232 { |
|
233 /** The index of the Tz private directory filter. */ |
|
234 EFilterTzPrivate=0, |
|
235 /** The index of the resources filter. */ |
|
236 EFilterResourceTimezonelocalization |
|
237 }; |
|
238 |
|
239 public: |
|
240 /** |
|
241 This should not be used externally. |
|
242 */ |
|
243 IMPORT_C static void Panic(TPanic aPanic); |
|
244 |
|
245 /** |
|
246 This should not be used externally. |
|
247 */ |
|
248 IMPORT_C CTzId* GetTimeZoneIdL() const; |
|
249 |
|
250 /** |
|
251 This should not be used externally. |
|
252 */ |
|
253 IMPORT_C void SetTimeZoneL(CTzId& aZone) const; |
|
254 |
|
255 IMPORT_C void Close(); |
|
256 IMPORT_C TInt Connect(); |
|
257 |
|
258 IMPORT_C ~RTz(); |
|
259 IMPORT_C RTz(); |
|
260 |
|
261 IMPORT_C TInt ConvertToLocalTime(TTime& aTime) const; |
|
262 IMPORT_C TInt ConvertToLocalTime(TTime& aTime, const CTzId& aZone) const; |
|
263 IMPORT_C TInt ConvertToUniversalTime(TTime& aTime) const; |
|
264 IMPORT_C TInt ConvertToUniversalTime(TTime& aTime, const CTzId& aZone) const; |
|
265 |
|
266 IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray<TInt>& aTzNumericIds, |
|
267 RArray<TInt>& aOffsets) const; |
|
268 |
|
269 IMPORT_C TInt AutoUpdateSettingL(); |
|
270 IMPORT_C void SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes aUpdateEnabled); |
|
271 |
|
272 // Methods for setting the system time. |
|
273 IMPORT_C TInt SetHomeTime(const TTime& aLocalTime) const; |
|
274 |
|
275 IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone) const; |
|
276 IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone, const TTime& aUTCTime) const; |
|
277 |
|
278 // Get Encoded Rules for Current Local Time Zone |
|
279 IMPORT_C CTzRules* GetTimeZoneRulesL(const TTime& aStartTime, |
|
280 const TTime& aEndTime, TTzTimeReference aTimeRef) const; |
|
281 IMPORT_C CTzRules* GetTimeZoneRulesL(const CTzId& aZone, |
|
282 const TTime& aStartTime, const TTime& aEndTime, |
|
283 TTzTimeReference aTimeRef) const; |
|
284 |
|
285 void RegisterTzChangeNotifier(TRequestStatus& aStatus) const; |
|
286 TInt CancelRequestForNotice() const; |
|
287 TVersion Version() const; |
|
288 |
|
289 IMPORT_C void NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange& |
|
290 aChange) const; |
|
291 |
|
292 IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, |
|
293 const TInt aUTCOffset); |
|
294 IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, |
|
295 const TInt aUTCOffset, TBool aPersistInCenRep); |
|
296 |
|
297 IMPORT_C void LocalizationReadCitiesL(RPointerArray<CTzLocalizedCityRecord>& |
|
298 aCities); |
|
299 IMPORT_C void LocalizationReadCitiesL(RPointerArray<CTzLocalizedCityRecord>& |
|
300 aCities, TInt aTimeZoneId); |
|
301 IMPORT_C void LocalizationReadCitiesInGroupL(RPointerArray<CTzLocalizedCityRecord>& |
|
302 aCities, TUint8 aGroupId); |
|
303 IMPORT_C CTzLocalizedTimeZoneRecord* LocalizationReadFrequentlyUsedZoneL( |
|
304 TInt aFrequentlyUsedZone); |
|
305 IMPORT_C CTzLocalizedCityRecord* LocalizationReadCachedTimeZoneCityL( |
|
306 TInt aFrequentlyUsedZone); |
|
307 IMPORT_C void LocalizationCloseDbL(); |
|
308 IMPORT_C void LocalizationOpenDbL(); |
|
309 IMPORT_C void LocalizationWriteCityL(const TDesC& aCityName, TInt aCityTzId, |
|
310 TUint8 aCityGroupId, TUint aCityTzResourceId); |
|
311 IMPORT_C void LocalizationDeleteCityL(const TDesC& aCityName, |
|
312 TInt aCityTzId); |
|
313 IMPORT_C void LocalizationWriteFrequentlyUsedZoneL(const CTzLocalizedTimeZoneRecord& |
|
314 aTimeZone, const CTzLocalizedCityRecord& aCity, |
|
315 TInt aFrequentlyUsedZone); |
|
316 IMPORT_C void LocalizationWriteAllFrequentlyUsedZonesL(const RPointerArray<CTzLocalizedTimeZoneRecord>& aTimeZones, |
|
317 const RPointerArray<CTzLocalizedCityRecord>& aCities); |
|
318 |
|
319 // Debug only methods. |
|
320 IMPORT_C void SwiObsBeginL(); |
|
321 IMPORT_C void SwiObsFileChangedL(TSWIObserverFilterIndex aType); |
|
322 IMPORT_C void SwiObsEndL(); |
|
323 |
|
324 // Debug only methods. |
|
325 IMPORT_C void __dbgClearCacheL(TBool aRestartCaching); |
|
326 IMPORT_C TInt __dbgRequestAllocatedCellsL(TInt aHeapSizeInBytes); |
|
327 IMPORT_C void __dbgSetHeapFailL(RAllocator::TAllocFail aType, TInt aRate); |
|
328 IMPORT_C void __dbgResetHeapL(); |
|
329 |
|
330 TBool StartCachingL(); |
|
331 TUint16 CurrentCachedTzId(); |
|
332 |
|
333 // User-defined time zone access. |
|
334 CTzId* CreateUserTimeZoneL(const CTzRules& aTzUserRules, const CTzUserNames& aTzUserNames); |
|
335 CTzUserNames* GetUserTimeZoneNamesL(const CTzId& aTzId) const; |
|
336 void UpdateUserTimeZoneL(const CTzId& aTzId, const CTzRules& aTzUserRules, const CTzUserNames& aTzUserNames); |
|
337 void DeleteUserTimeZoneL(const CTzId& aTzId); |
|
338 void GetUserTimeZoneIdsL(RPointerArray<CTzId>& aTzIds) const; |
|
339 |
|
340 private: |
|
341 static TInt StartServer(); |
|
342 TInt DoConnect(); |
|
343 void doConvertL(const CTzId& aZone, TTime& aTime, |
|
344 TTzTimeReference aTimerRef) const; |
|
345 void doConvertL(TTime& aTime, |
|
346 TTzTimeReference aTimerRef) const; |
|
347 |
|
348 |
|
349 |
|
350 private: |
|
351 CTzRuleHolder* iRulesHolder; |
|
352 }; |
|
353 |
|
354 |
|
355 /** |
|
356 Encapsulates a TTime and a TTzTimeReference. |
|
357 |
|
358 @publishedAll |
|
359 @released |
|
360 */ |
|
361 class TTimeWithReference |
|
362 { |
|
363 public: |
|
364 static inline TTimeWithReference Max(); |
|
365 |
|
366 inline TTimeWithReference(); |
|
367 inline TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference); |
|
368 inline TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference); |
|
369 |
|
370 inline bool operator==(const TTimeWithReference& aTime) const; |
|
371 inline bool operator!=(const TTimeWithReference& aTime) const; |
|
372 |
|
373 TTime iTime; |
|
374 TTzTimeReference iTimeReference; |
|
375 }; |
|
376 |
|
377 |
|
378 inline TTimeWithReference TTimeWithReference::Max() |
|
379 { |
|
380 return TTimeWithReference( |
|
381 TDateTime(9999,EDecember,30,23,59,59,0), |
|
382 ETzUtcTimeReference); |
|
383 } |
|
384 |
|
385 |
|
386 inline TTimeWithReference::TTimeWithReference() |
|
387 : iTime(0), iTimeReference(ETzUtcTimeReference) |
|
388 { |
|
389 } |
|
390 |
|
391 |
|
392 inline TTimeWithReference::TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference) |
|
393 : iTime(aTime), iTimeReference(aTimeReference) |
|
394 { |
|
395 } |
|
396 |
|
397 |
|
398 inline TTimeWithReference::TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference) |
|
399 : iTime(aTime), iTimeReference(aTimeReference) |
|
400 { |
|
401 } |
|
402 |
|
403 |
|
404 inline bool TTimeWithReference::operator==(const TTimeWithReference& aTime) const |
|
405 { |
|
406 return(aTime.iTime == iTime && aTime.iTimeReference == iTimeReference); |
|
407 } |
|
408 |
|
409 |
|
410 inline bool TTimeWithReference::operator!=(const TTimeWithReference& aTime) const |
|
411 { |
|
412 return(!(*this == aTime)); |
|
413 } |
|
414 |
|
415 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
416 /** |
|
417 The CTzUserData class allows the client to create, read, update or delete |
|
418 user-defined time zones. |
|
419 |
|
420 A user-defined time zone is comprised of time zone rules (encapsulated in a |
|
421 CTzRules object) and time zone names (encapsulated in a CTzUserNames object). |
|
422 |
|
423 A time zone identifier (encapsulated in a CTzId object) is used to uniquely |
|
424 identify a user-defined time zone. |
|
425 |
|
426 The CTzUserData class also allows the time zone identifiers for all existing |
|
427 user-defined time zones to be determined. |
|
428 |
|
429 @publishedPartner |
|
430 @released |
|
431 */ |
|
432 class CTzUserData : public CBase |
|
433 { |
|
434 public: |
|
435 IMPORT_C static CTzUserData* NewL(RTz& aTzServer); |
|
436 IMPORT_C ~CTzUserData(); |
|
437 |
|
438 IMPORT_C CTzId* CreateL(const CTzRules& aTzUserRules, const CTzUserNames& |
|
439 aTzUserNames); |
|
440 IMPORT_C CTzRules* ReadRulesL(const CTzId& aTzId) const; |
|
441 IMPORT_C CTzUserNames* ReadNamesL(const CTzId& aTzId) const; |
|
442 IMPORT_C void UpdateL(const CTzId& aTzId, const CTzRules& aTzUserRules, |
|
443 const CTzUserNames& aTzUserNames); |
|
444 IMPORT_C void DeleteL(const CTzId& aTzId); |
|
445 IMPORT_C void GetTzIdsL(RPointerArray<CTzId>& aTzIds) const; |
|
446 |
|
447 private: |
|
448 CTzUserData(RTz& aTzServer); |
|
449 |
|
450 private: |
|
451 RTz& iTzServer; |
|
452 }; |
|
453 |
|
454 #endif // SYMBIAN_ENABLE_SPLIT_HEADERS |
|
455 |
|
456 #endif |