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