|
1 // Copyright (c) 2004-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 __TzLocalizer_H__ |
|
17 #define __TzLocalizer_H__ |
|
18 |
|
19 #include <e32base.h> |
|
20 #include <tz.h> |
|
21 #include <tzlocalizationdatatypes.h> |
|
22 |
|
23 class CTzLocalizationResourceReader; |
|
24 class CTzLocalizationUserDataReader; |
|
25 |
|
26 const TInt KTzCityNotInGroupId = 0; |
|
27 /** |
|
28 Retrieves localized time zone information based on a time zone identifier. |
|
29 |
|
30 Time zone information is available in the following forms: |
|
31 |
|
32 - Standard time name, for example "Greenwich Mean Time" |
|
33 - Short standard time name, for instance "GMT" |
|
34 - Daylight saving time name, for instance "British Summer Time" |
|
35 - Short daylight saving time name, for instance "BST" |
|
36 |
|
37 This information is encapsulated in a CTzLocalizedTimeZone object. |
|
38 |
|
39 A collection of localized cities for a specific time zone is returned as a |
|
40 CTzLocalizedCityArray object. An individual localized city is returned as a |
|
41 CTzLocalizedCity object. |
|
42 |
|
43 A collection of localized city groups for a specific time zone is returned as a |
|
44 CTzLocalizedCityGroupArray. An individual localized city group is returned as a |
|
45 CTzLocalizedCityGroup object. |
|
46 |
|
47 New non-localized cities can be added to an existing time zone. A new city may |
|
48 also be added to a city group, but a city may only be a member of one city |
|
49 group. |
|
50 |
|
51 User-defined time zone names can also be retrieved through this class, |
|
52 encapsulated as follows: |
|
53 |
|
54 - In a CTzLocalizedTimeZone object for long/short standard time and long/short |
|
55 daylight saving time user-defined time zone names. |
|
56 - In a CTzLocalizedCityArray object or CTzLocalizedCity object for user-defined |
|
57 time zone city names. |
|
58 - In a CTzLocalizedCityGroupArray object or CTzLocalizedCityGroup object for |
|
59 user-defined time zone region names. |
|
60 |
|
61 All user-defined time zones names’ use the same city group identifier of |
|
62 KTzCityNotInGroupId to indicate that they do not belong to a specific group. |
|
63 |
|
64 For methods that return a single city or single city group, if the given group |
|
65 identifier is KTzCityNotInGroupId the methods leave with KErrArgument since it |
|
66 is not possible to determine which region name should be used to identify the |
|
67 single city group. |
|
68 |
|
69 For methods that return an array of cities or city groups, if the given group |
|
70 identifier is KTzCityNotInGroupId the methods shall return all user-defined city |
|
71 names or region names. |
|
72 |
|
73 The array object forms can contain a combination of system time zone |
|
74 localization information and user-defined time zone names. The client can |
|
75 control the combination of data using the SetDataSource() method. |
|
76 |
|
77 @publishedAll |
|
78 @released |
|
79 */ |
|
80 class CTzLocalizer : public CBase |
|
81 { |
|
82 public: |
|
83 /** Panic reasons for the time zone localization component. */ |
|
84 enum TTzLocalizerPanics |
|
85 { |
|
86 /** The time zone server was not found. */ |
|
87 ETzLocalizerPanicTimeZoneServerNotFound, |
|
88 /** A resource file was not found. */ |
|
89 ETzLocalizerPanicResourceFileNotFound |
|
90 }; |
|
91 |
|
92 /** Used to specify the sort order of localized time zone information. */ |
|
93 enum TTzSortOrder |
|
94 { |
|
95 /** Unsorted. This is the fastest way to get localized data. */ |
|
96 ETzUnsorted, |
|
97 /** Sort by UTC offset starting with the lowest. */ |
|
98 ETzUTCAscending, |
|
99 /** Sort by UTC offset starting with the highest. */ |
|
100 ETzUTCDescending, |
|
101 /** Sort by name (city name/group name/standard time zone name), from A-Z. */ |
|
102 ETzAlphaNameAscending, |
|
103 /** Sort by name (city name/group name/standard time zone name), from Z-A. */ |
|
104 ETzAlphaNameDescending, |
|
105 /** Sort by standard name from A-Z. */ |
|
106 ETzAlphaStandardNameAscending, |
|
107 /** Sort by daylight savings name from A-Z. */ |
|
108 ETzAlphaDaylightNameAscending, |
|
109 /** Sort by short standard name from A-Z. */ |
|
110 ETzAlphaShortStandardNameAscending, |
|
111 /** Sort by short daylight savings name from A-Z. */ |
|
112 ETzAlphaShortDaylightNameAscending, |
|
113 /** Sort by standard name from Z-A. */ |
|
114 ETzAlphaStandardNameDescending, |
|
115 /** Sort by daylight savings name from Z-A. */ |
|
116 ETzAlphaDaylightNameDescending, |
|
117 /** Sort by short standard name from Z-A. */ |
|
118 ETzAlphaShortStandardNameDescending, |
|
119 /** Sort by short daylight savings name from Z-A. */ |
|
120 ETzAlphaShortDaylightNameDescending |
|
121 }; |
|
122 |
|
123 /** |
|
124 This enumeration indicates the data source(s) to use for CTzLocalizer |
|
125 methods that return a combination of system time zone localization |
|
126 information and user-defined time zone names. The enumeration values |
|
127 are bit flags which can be combined using the logical OR operator. |
|
128 */ |
|
129 enum TTzLocalizerDataSource |
|
130 { |
|
131 /** Use system time zone localization information. */ |
|
132 ETzDataSourceSystem = 0x1, |
|
133 /** Use non-localized user time zone names. */ |
|
134 ETzDataSourceUser = 0x2 |
|
135 }; |
|
136 |
|
137 public: |
|
138 //Construction / Destruction |
|
139 IMPORT_C static CTzLocalizer* NewL(); |
|
140 IMPORT_C static CTzLocalizer* NewLC(); |
|
141 IMPORT_C ~CTzLocalizer(); |
|
142 |
|
143 private: |
|
144 CTzLocalizer(); |
|
145 void ConstructL(); |
|
146 TBool DbNeedsUpdatingL() const; |
|
147 void UpgradeDbVersionL(); |
|
148 void FetchCityToUpgradeL(CTzLocalizedTimeZoneArray& aTimeZoneArray, CTzLocalizedCityArray& aCityArray, CTzLocalizedTimeZone::TTzFrequentlyUsedZone aCachedZone); |
|
149 void RecreateDbL(); |
|
150 |
|
151 public: |
|
152 //Time zones |
|
153 IMPORT_C CTzLocalizedTimeZone* GetLocalizedTimeZoneL(TInt aTimeZoneId) const; |
|
154 IMPORT_C CTzLocalizedTimeZone* GetLocalizedTimeZoneL(const CTzLocalizedCity& aCity) const; |
|
155 IMPORT_C CTzLocalizedTimeZoneArray* GetAllTimeZonesL(const TTzSortOrder aSortOrder = ETzUnsorted); |
|
156 |
|
157 IMPORT_C void SetTimeZoneL(TInt aTimeZoneId); |
|
158 |
|
159 //City Management |
|
160 IMPORT_C CTzLocalizedCity* GetDefaultCityL(TInt aTimeZoneId) const; |
|
161 IMPORT_C CTzLocalizedCity* GetDefaultCityL(const CTzLocalizedCity& aCity) const; |
|
162 IMPORT_C CTzLocalizedCity* GetDefaultCityL(const CTzLocalizedTimeZone& aTimeZone) const; |
|
163 |
|
164 IMPORT_C CTzLocalizedCityArray* GetCitiesL(const TTzSortOrder aSortOrder = ETzUnsorted); |
|
165 IMPORT_C CTzLocalizedCityArray* GetCitiesL(TInt aTimeZoneId,const TTzSortOrder aSortOrder = ETzUnsorted); |
|
166 IMPORT_C CTzLocalizedCityArray* GetCitiesL(const CTzLocalizedTimeZone& aTimeZone,const TTzSortOrder aSortOrder = ETzUnsorted); |
|
167 IMPORT_C CTzLocalizedCityArray* GetCitiesL(const CTzLocalizedCity& aCity,const TTzSortOrder aSortOrder = ETzUnsorted); |
|
168 |
|
169 IMPORT_C CTzLocalizedCity* AddCityL(TInt aTimeZoneId,const TDesC& aCityName, TInt aGroupId = 0); |
|
170 IMPORT_C void RemoveCityL(CTzLocalizedCity* aCity); |
|
171 |
|
172 //City Groups |
|
173 IMPORT_C CTzLocalizedCityGroupArray* GetAllCityGroupsL(const TTzSortOrder aSortOrder = ETzUnsorted) const; |
|
174 IMPORT_C CTzLocalizedCityGroup* GetCityGroupL(TInt aGroupId) const; |
|
175 IMPORT_C CTzLocalizedCityGroup* GetCityGroupL(const CTzLocalizedCity& aCity) const ; |
|
176 |
|
177 IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(TInt aGroupId,const TTzSortOrder aSortOrder = ETzUnsorted); |
|
178 IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(const CTzLocalizedCity& aCity,const TTzSortOrder aSortOrder = ETzUnsorted); |
|
179 IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(const CTzLocalizedCityGroup& aCityGroup,const TTzSortOrder aSortOrder = ETzUnsorted); |
|
180 |
|
181 //Frequently Used Zones |
|
182 IMPORT_C CTzLocalizedTimeZone* GetFrequentlyUsedZoneL(const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); |
|
183 IMPORT_C CTzLocalizedCity* GetFrequentlyUsedZoneCityL(const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); |
|
184 IMPORT_C void SetFrequentlyUsedZoneL(TInt aTimeZoneId,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); |
|
185 IMPORT_C void SetFrequentlyUsedZoneL(const CTzLocalizedTimeZone& aTimeZone,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); |
|
186 IMPORT_C void SetFrequentlyUsedZoneL(const CTzLocalizedCity& aCity,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); |
|
187 |
|
188 //Find functions |
|
189 IMPORT_C CTzLocalizedCity* FindCityByNameL(const TDesC& aCityName, const TInt aTimeZoneId = 0); |
|
190 IMPORT_C CTzLocalizedTimeZone* FindTimeZoneByNameL(const TDesC& aTimeZoneName); |
|
191 IMPORT_C CTzLocalizedCityGroup* FindCityGroupByNameL(const TDesC& aCityGroupName); |
|
192 |
|
193 IMPORT_C TBool CheckLanguage(); |
|
194 |
|
195 //Cities and Time Zones with a specified UTC offset |
|
196 IMPORT_C CTzLocalizedCityArray* GetCitiesWithUTCOffsetL(TInt aUTCOffsetInMinutes, const TTzSortOrder aSortOrder = ETzUnsorted); |
|
197 IMPORT_C CTzLocalizedTimeZoneArray* GetTimeZonesWithUTCOffsetL(TInt aUTCOffsetInMinutes, const TTzSortOrder aSortOrder = ETzUnsorted); |
|
198 |
|
199 IMPORT_C void SetDataSource(TUint aDataSource); |
|
200 |
|
201 private: |
|
202 TBool PrepareFrequentlyUsedZonesL(); |
|
203 void UpdateFrequentlyUsedZonesL(); |
|
204 CTzLocalizedTimeZone* GetFrequentlyUsedDefaultZoneL(CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFreqUsedZone); |
|
205 TUint32 GetFrequentlyUsedDefaultZoneCenRepKeyL(CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFreqUsedZone); |
|
206 void GetCitiesL(CTzLocalizedCityArray& aCities, const TTzLocalizedId& aLocalizedId, |
|
207 TBool aUseDataSource, const TTzSortOrder aSortOrder = ETzUnsorted); |
|
208 TLinearOrder<CTzLocalizedCity> CitySortOrderL(const TTzSortOrder aSortOrder); |
|
209 TLinearOrder<CTzLocalizedTimeZone> TimeZoneSortOrderL(const TTzSortOrder aSortOrder); |
|
210 template <class T> void PrepareForUTCSortL(T& aArray); |
|
211 TInt GetTimeZoneIdFromTzServerL(); |
|
212 void DoSetTimeZoneL(TInt aTimeZoneId); |
|
213 void ChangeHomeTimeZoneL(TInt aNewId); |
|
214 TBool FindCityAndSetCityIndexL(CTzLocalizedCity& aLocalizedCity, TTzLocalizerDataSource aDataSource); |
|
215 TBool IsOperateOnUserDbL(TInt aTimeZoneId, TBool aUseDataSource) const; |
|
216 void ReadCitiesL(CTzLocalizedCityArray& aCityArray, TInt aTimeZoneId, TBool aUseDataSource) const; |
|
217 CTzLocalizedCity* ReadDefaultCityL(TInt aTimeZoneId, TBool aUseDataSource) const; |
|
218 void WriteAllFrequentlyUsedZonesL(const CTzLocalizedTimeZoneArray& aTimeZones, const CTzLocalizedCityArray& aCities); |
|
219 void SetFrequentlyUsedZoneL(const CTzLocalizedTimeZone& aTimeZone, const CTzLocalizedCity& aCity, |
|
220 const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); |
|
221 CTzLocalizedTimeZone* GetLocalizedTimeZoneL(TInt aTimeZoneId, TBool aUseDataSource) const; |
|
222 CTzLocalizedTimeZone* GetLocalizedTimeZoneL(const CTzLocalizedCity& aCity, TBool aUseDataSource) const; |
|
223 static void PopulateCityArrayL(const RPointerArray<CTzLocalizedCityRecord>& aCityRecords, |
|
224 CTzLocalizedCityArray& aCities); |
|
225 static CTzLocalizedTimeZoneRecord* CreateTimeZoneRecordL(const CTzLocalizedTimeZone& aTimeZone); |
|
226 static CTzLocalizedTimeZoneRecord* CreateTimeZoneRecordLC(const CTzLocalizedTimeZone& aTimeZone); |
|
227 static CTzLocalizedCityRecord* CreateCityRecordL(const CTzLocalizedCity& aCity); |
|
228 static CTzLocalizedCityRecord* CreateCityRecordLC(const CTzLocalizedCity& aCity); |
|
229 static CTzLocalizedTimeZone* CreateTimeZoneL(const CTzLocalizedTimeZoneRecord& aTimeZoneRecord); |
|
230 static CTzLocalizedCity* CreateCityL(const CTzLocalizedCityRecord& aCityRecord); |
|
231 static void CleanupTimeZonePointerArray(TAny* aArray); |
|
232 static void CleanupCityPointerArray(TAny* aArray); |
|
233 |
|
234 private: |
|
235 CTzLocalizationResourceReader* iStaticDataReader; |
|
236 CTzLocalizationUserDataReader* iUserDataReader; |
|
237 |
|
238 TLanguage iLanguage; |
|
239 TUint iDataSource; |
|
240 RTz iTzSession; |
|
241 }; |
|
242 |
|
243 #endif//__TzLocalizer_H__ |