diff -r 000000000000 -r 2e3d3ce01487 tzservices/tzloc/inc/TzLocalizer.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tzservices/tzloc/inc/TzLocalizer.h Tue Feb 02 10:12:00 2010 +0200 @@ -0,0 +1,243 @@ +// Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +#ifndef __TzLocalizer_H__ +#define __TzLocalizer_H__ + +#include +#include +#include + +class CTzLocalizationResourceReader; +class CTzLocalizationUserDataReader; + +const TInt KTzCityNotInGroupId = 0; +/** +Retrieves localized time zone information based on a time zone identifier. + +Time zone information is available in the following forms: + +- Standard time name, for example "Greenwich Mean Time" +- Short standard time name, for instance "GMT" +- Daylight saving time name, for instance "British Summer Time" +- Short daylight saving time name, for instance "BST" + +This information is encapsulated in a CTzLocalizedTimeZone object. + +A collection of localized cities for a specific time zone is returned as a +CTzLocalizedCityArray object. An individual localized city is returned as a +CTzLocalizedCity object. + +A collection of localized city groups for a specific time zone is returned as a +CTzLocalizedCityGroupArray. An individual localized city group is returned as a +CTzLocalizedCityGroup object. + +New non-localized cities can be added to an existing time zone. A new city may +also be added to a city group, but a city may only be a member of one city +group. + +User-defined time zone names can also be retrieved through this class, +encapsulated as follows: + +- In a CTzLocalizedTimeZone object for long/short standard time and long/short +daylight saving time user-defined time zone names. +- In a CTzLocalizedCityArray object or CTzLocalizedCity object for user-defined +time zone city names. +- In a CTzLocalizedCityGroupArray object or CTzLocalizedCityGroup object for +user-defined time zone region names. + +All user-defined time zones names’ use the same city group identifier of +KTzCityNotInGroupId to indicate that they do not belong to a specific group. + +For methods that return a single city or single city group, if the given group +identifier is KTzCityNotInGroupId the methods leave with KErrArgument since it +is not possible to determine which region name should be used to identify the +single city group. + +For methods that return an array of cities or city groups, if the given group +identifier is KTzCityNotInGroupId the methods shall return all user-defined city +names or region names. + +The array object forms can contain a combination of system time zone +localization information and user-defined time zone names. The client can +control the combination of data using the SetDataSource() method. + +@publishedAll +@released +*/ +class CTzLocalizer : public CBase + { + public: + /** Panic reasons for the time zone localization component. */ + enum TTzLocalizerPanics + { + /** The time zone server was not found. */ + ETzLocalizerPanicTimeZoneServerNotFound, + /** A resource file was not found. */ + ETzLocalizerPanicResourceFileNotFound + }; + + /** Used to specify the sort order of localized time zone information. */ + enum TTzSortOrder + { + /** Unsorted. This is the fastest way to get localized data. */ + ETzUnsorted, + /** Sort by UTC offset starting with the lowest. */ + ETzUTCAscending, + /** Sort by UTC offset starting with the highest. */ + ETzUTCDescending, + /** Sort by name (city name/group name/standard time zone name), from A-Z. */ + ETzAlphaNameAscending, + /** Sort by name (city name/group name/standard time zone name), from Z-A. */ + ETzAlphaNameDescending, + /** Sort by standard name from A-Z. */ + ETzAlphaStandardNameAscending, + /** Sort by daylight savings name from A-Z. */ + ETzAlphaDaylightNameAscending, + /** Sort by short standard name from A-Z. */ + ETzAlphaShortStandardNameAscending, + /** Sort by short daylight savings name from A-Z. */ + ETzAlphaShortDaylightNameAscending, + /** Sort by standard name from Z-A. */ + ETzAlphaStandardNameDescending, + /** Sort by daylight savings name from Z-A. */ + ETzAlphaDaylightNameDescending, + /** Sort by short standard name from Z-A. */ + ETzAlphaShortStandardNameDescending, + /** Sort by short daylight savings name from Z-A. */ + ETzAlphaShortDaylightNameDescending + }; + + /** + This enumeration indicates the data source(s) to use for CTzLocalizer + methods that return a combination of system time zone localization + information and user-defined time zone names. The enumeration values + are bit flags which can be combined using the logical OR operator. + */ + enum TTzLocalizerDataSource + { + /** Use system time zone localization information. */ + ETzDataSourceSystem = 0x1, + /** Use non-localized user time zone names. */ + ETzDataSourceUser = 0x2 + }; + + public: + //Construction / Destruction + IMPORT_C static CTzLocalizer* NewL(); + IMPORT_C static CTzLocalizer* NewLC(); + IMPORT_C ~CTzLocalizer(); + + private: + CTzLocalizer(); + void ConstructL(); + TBool DbNeedsUpdatingL() const; + void UpgradeDbVersionL(); + void FetchCityToUpgradeL(CTzLocalizedTimeZoneArray& aTimeZoneArray, CTzLocalizedCityArray& aCityArray, CTzLocalizedTimeZone::TTzFrequentlyUsedZone aCachedZone); + void RecreateDbL(); + + public: + //Time zones + IMPORT_C CTzLocalizedTimeZone* GetLocalizedTimeZoneL(TInt aTimeZoneId) const; + IMPORT_C CTzLocalizedTimeZone* GetLocalizedTimeZoneL(const CTzLocalizedCity& aCity) const; + IMPORT_C CTzLocalizedTimeZoneArray* GetAllTimeZonesL(const TTzSortOrder aSortOrder = ETzUnsorted); + + IMPORT_C void SetTimeZoneL(TInt aTimeZoneId); + + //City Management + IMPORT_C CTzLocalizedCity* GetDefaultCityL(TInt aTimeZoneId) const; + IMPORT_C CTzLocalizedCity* GetDefaultCityL(const CTzLocalizedCity& aCity) const; + IMPORT_C CTzLocalizedCity* GetDefaultCityL(const CTzLocalizedTimeZone& aTimeZone) const; + + IMPORT_C CTzLocalizedCityArray* GetCitiesL(const TTzSortOrder aSortOrder = ETzUnsorted); + IMPORT_C CTzLocalizedCityArray* GetCitiesL(TInt aTimeZoneId,const TTzSortOrder aSortOrder = ETzUnsorted); + IMPORT_C CTzLocalizedCityArray* GetCitiesL(const CTzLocalizedTimeZone& aTimeZone,const TTzSortOrder aSortOrder = ETzUnsorted); + IMPORT_C CTzLocalizedCityArray* GetCitiesL(const CTzLocalizedCity& aCity,const TTzSortOrder aSortOrder = ETzUnsorted); + + IMPORT_C CTzLocalizedCity* AddCityL(TInt aTimeZoneId,const TDesC& aCityName, TInt aGroupId = 0); + IMPORT_C void RemoveCityL(CTzLocalizedCity* aCity); + + //City Groups + IMPORT_C CTzLocalizedCityGroupArray* GetAllCityGroupsL(const TTzSortOrder aSortOrder = ETzUnsorted) const; + IMPORT_C CTzLocalizedCityGroup* GetCityGroupL(TInt aGroupId) const; + IMPORT_C CTzLocalizedCityGroup* GetCityGroupL(const CTzLocalizedCity& aCity) const ; + + IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(TInt aGroupId,const TTzSortOrder aSortOrder = ETzUnsorted); + IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(const CTzLocalizedCity& aCity,const TTzSortOrder aSortOrder = ETzUnsorted); + IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(const CTzLocalizedCityGroup& aCityGroup,const TTzSortOrder aSortOrder = ETzUnsorted); + + //Frequently Used Zones + IMPORT_C CTzLocalizedTimeZone* GetFrequentlyUsedZoneL(const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); + IMPORT_C CTzLocalizedCity* GetFrequentlyUsedZoneCityL(const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); + IMPORT_C void SetFrequentlyUsedZoneL(TInt aTimeZoneId,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); + IMPORT_C void SetFrequentlyUsedZoneL(const CTzLocalizedTimeZone& aTimeZone,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); + IMPORT_C void SetFrequentlyUsedZoneL(const CTzLocalizedCity& aCity,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); + + //Find functions + IMPORT_C CTzLocalizedCity* FindCityByNameL(const TDesC& aCityName, const TInt aTimeZoneId = 0); + IMPORT_C CTzLocalizedTimeZone* FindTimeZoneByNameL(const TDesC& aTimeZoneName); + IMPORT_C CTzLocalizedCityGroup* FindCityGroupByNameL(const TDesC& aCityGroupName); + + IMPORT_C TBool CheckLanguage(); + + //Cities and Time Zones with a specified UTC offset + IMPORT_C CTzLocalizedCityArray* GetCitiesWithUTCOffsetL(TInt aUTCOffsetInMinutes, const TTzSortOrder aSortOrder = ETzUnsorted); + IMPORT_C CTzLocalizedTimeZoneArray* GetTimeZonesWithUTCOffsetL(TInt aUTCOffsetInMinutes, const TTzSortOrder aSortOrder = ETzUnsorted); + + IMPORT_C void SetDataSource(TUint aDataSource); + + private: + TBool PrepareFrequentlyUsedZonesL(); + void UpdateFrequentlyUsedZonesL(); + CTzLocalizedTimeZone* GetFrequentlyUsedDefaultZoneL(CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFreqUsedZone); + TUint32 GetFrequentlyUsedDefaultZoneCenRepKeyL(CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFreqUsedZone); + void GetCitiesL(CTzLocalizedCityArray& aCities, const TTzLocalizedId& aLocalizedId, + TBool aUseDataSource, const TTzSortOrder aSortOrder = ETzUnsorted); + TLinearOrder CitySortOrderL(const TTzSortOrder aSortOrder); + TLinearOrder TimeZoneSortOrderL(const TTzSortOrder aSortOrder); + template void PrepareForUTCSortL(T& aArray); + TInt GetTimeZoneIdFromTzServerL(); + void DoSetTimeZoneL(TInt aTimeZoneId); + void ChangeHomeTimeZoneL(TInt aNewId); + TBool FindCityAndSetCityIndexL(CTzLocalizedCity& aLocalizedCity, TTzLocalizerDataSource aDataSource); + TBool IsOperateOnUserDbL(TInt aTimeZoneId, TBool aUseDataSource) const; + void ReadCitiesL(CTzLocalizedCityArray& aCityArray, TInt aTimeZoneId, TBool aUseDataSource) const; + CTzLocalizedCity* ReadDefaultCityL(TInt aTimeZoneId, TBool aUseDataSource) const; + void WriteAllFrequentlyUsedZonesL(const CTzLocalizedTimeZoneArray& aTimeZones, const CTzLocalizedCityArray& aCities); + void SetFrequentlyUsedZoneL(const CTzLocalizedTimeZone& aTimeZone, const CTzLocalizedCity& aCity, + const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone); + CTzLocalizedTimeZone* GetLocalizedTimeZoneL(TInt aTimeZoneId, TBool aUseDataSource) const; + CTzLocalizedTimeZone* GetLocalizedTimeZoneL(const CTzLocalizedCity& aCity, TBool aUseDataSource) const; + static void PopulateCityArrayL(const RPointerArray& aCityRecords, + CTzLocalizedCityArray& aCities); + static CTzLocalizedTimeZoneRecord* CreateTimeZoneRecordL(const CTzLocalizedTimeZone& aTimeZone); + static CTzLocalizedTimeZoneRecord* CreateTimeZoneRecordLC(const CTzLocalizedTimeZone& aTimeZone); + static CTzLocalizedCityRecord* CreateCityRecordL(const CTzLocalizedCity& aCity); + static CTzLocalizedCityRecord* CreateCityRecordLC(const CTzLocalizedCity& aCity); + static CTzLocalizedTimeZone* CreateTimeZoneL(const CTzLocalizedTimeZoneRecord& aTimeZoneRecord); + static CTzLocalizedCity* CreateCityL(const CTzLocalizedCityRecord& aCityRecord); + static void CleanupTimeZonePointerArray(TAny* aArray); + static void CleanupCityPointerArray(TAny* aArray); + +private: + CTzLocalizationResourceReader* iStaticDataReader; + CTzLocalizationUserDataReader* iUserDataReader; + + TLanguage iLanguage; + TUint iDataSource; + RTz iTzSession; + }; + +#endif//__TzLocalizer_H__