epoc32/include/tzlocalizer.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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 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 __TzLocalizer_H__
    17 #define __TzLocalizer_H__
    18 
    19 #include <e32base.h> //CBase
    20 
    21 #include <tzlocalizationdatatypes.h> 	//CTzLocalizedCity, CTzLocalizedCityGroup etc
    22 
    23 // Forward Declarations
    24 class MTzLocalizationReader;
    25 class MTzLocalizationWriter;
    26 
    27 /**
    28 Retrieves localized time zone information based on a time zone ID.
    29 
    30 Time zone information is available in the following forms:
    31 - Standard Name, for instance Greenwich Mean Time,
    32 - Short Standard Name, for instance GMT,
    33 - Daylight Savings Name, for instance British Summer Time,
    34 - Short Daylight Savings Name, for instance BST.
    35 
    36 This information is encapsulated in a CTzLocalizedTimeZone object.
    37 
    38 A collection of localizable cities for a specific time zone can also be returned.
    39 New cities can be added to a time zone.  Cities may also be added to groups, but 
    40 a city may only be a member of one group.
    41 
    42 @publishedAll
    43 @released
    44 */
    45 class CTzLocalizer : public CBase
    46 	{
    47 	public:
    48 		/** Panic reasons for the time zone localization component. */
    49 		enum TTzLocalizerPanics
    50 			{
    51 			/** The time zone server was not found. */
    52 			ETzLocalizerPanicTimeZoneServerNotFound,
    53 			/** A resource file was not found. */
    54 			ETzLocalizerPanicResourceFileNotFound
    55 			};
    56 
    57 		/** Used to specify the sort order of localized time zone information. */
    58 		enum TTzSortOrder
    59 			{
    60 			/** Unsorted. This is the fastest way to get localized data. */
    61 			ETzUnsorted,
    62 			/** Sort by UTC offset starting with the lowest. */
    63 			ETzUTCAscending,
    64 			/** Sort by UTC offset starting with the highest. */
    65 			ETzUTCDescending,
    66 			/** Sort by name (city name/group name/standard time zone name), from A-Z. */
    67 			ETzAlphaNameAscending,
    68 			/** Sort by name (city name/group name/standard time zone name), from Z-A. */
    69 			ETzAlphaNameDescending,
    70 			/** Sort by standard name from A-Z. */
    71 			ETzAlphaStandardNameAscending,
    72 			/** Sort by daylight savings name from A-Z. */
    73 			ETzAlphaDaylightNameAscending,
    74 			/** Sort by short standard name from A-Z. */
    75 			ETzAlphaShortStandardNameAscending,
    76 			/** Sort by short daylight savings name from A-Z. */
    77 			ETzAlphaShortDaylightNameAscending,
    78 			/** Sort by standard name from Z-A. */
    79 			ETzAlphaStandardNameDescending,
    80 			/** Sort by daylight savings name from Z-A. */
    81 			ETzAlphaDaylightNameDescending,
    82 			/** Sort by short standard name from Z-A. */
    83 			ETzAlphaShortStandardNameDescending,
    84 			/** Sort by short daylight savings name from Z-A. */
    85 			ETzAlphaShortDaylightNameDescending
    86 			};
    87 
    88 	public:
    89 		//Construction / Destruction
    90 		IMPORT_C static CTzLocalizer* NewL();
    91 		IMPORT_C static CTzLocalizer* NewLC();
    92 		IMPORT_C ~CTzLocalizer();
    93 
    94 		//Time zones
    95 		IMPORT_C CTzLocalizedTimeZone* GetLocalizedTimeZoneL(TInt aTimeZoneId) const;
    96 		IMPORT_C CTzLocalizedTimeZone* GetLocalizedTimeZoneL(const CTzLocalizedCity& aCity) const;
    97 		IMPORT_C CTzLocalizedTimeZoneArray* GetAllTimeZonesL(const TTzSortOrder aSortOrder = ETzUnsorted);
    98 		
    99 		IMPORT_C void SetTimeZoneL(TInt aTimeZoneId);
   100 
   101 		//City Management
   102 		IMPORT_C CTzLocalizedCity* GetDefaultCityL(TInt aTimeZoneId) const;
   103 		IMPORT_C CTzLocalizedCity* GetDefaultCityL(const CTzLocalizedCity& aCity) const;
   104 		IMPORT_C CTzLocalizedCity* GetDefaultCityL(const CTzLocalizedTimeZone& aTimeZone) const;
   105 
   106 		IMPORT_C CTzLocalizedCityArray* GetCitiesL(const TTzSortOrder aSortOrder = ETzUnsorted);
   107 		IMPORT_C CTzLocalizedCityArray* GetCitiesL(TInt aTimeZoneId,const TTzSortOrder aSortOrder = ETzUnsorted);
   108 		IMPORT_C CTzLocalizedCityArray* GetCitiesL(const CTzLocalizedTimeZone& aTimeZone,const TTzSortOrder aSortOrder = ETzUnsorted);
   109 		IMPORT_C CTzLocalizedCityArray* GetCitiesL(const CTzLocalizedCity& aCity,const TTzSortOrder aSortOrder = ETzUnsorted);
   110 
   111 		IMPORT_C CTzLocalizedCity* AddCityL(TInt aTimeZoneId,const TDesC& aCityName, TInt aGroupId = 0);
   112 		IMPORT_C void RemoveCityL(CTzLocalizedCity* aCity);
   113 
   114 		//City Groups
   115 		IMPORT_C CTzLocalizedCityGroupArray* GetAllCityGroupsL(const TTzSortOrder aSortOrder = ETzUnsorted) const;
   116 		IMPORT_C CTzLocalizedCityGroup* GetCityGroupL(TInt aGroupId) const;
   117 		IMPORT_C CTzLocalizedCityGroup* GetCityGroupL(const CTzLocalizedCity& aCity) const ;
   118 
   119 		IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(TInt aGroupId,const TTzSortOrder aSortOrder = ETzUnsorted);
   120 		IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(const CTzLocalizedCity& aCity,const TTzSortOrder aSortOrder = ETzUnsorted);
   121 		IMPORT_C CTzLocalizedCityArray* GetCitiesInGroupL(const CTzLocalizedCityGroup& aCityGroup,const TTzSortOrder aSortOrder = ETzUnsorted);
   122 
   123 		//Frequently Used Zones
   124 		IMPORT_C CTzLocalizedTimeZone* GetFrequentlyUsedZoneL(const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);
   125 		IMPORT_C CTzLocalizedCity* GetFrequentlyUsedZoneCityL(const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);
   126 		IMPORT_C void SetFrequentlyUsedZoneL(TInt aTimeZoneId,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);
   127 		IMPORT_C void SetFrequentlyUsedZoneL(const CTzLocalizedTimeZone& aTimeZone,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);
   128 		IMPORT_C void SetFrequentlyUsedZoneL(const CTzLocalizedCity& aCity,const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);
   129 
   130 		//Find functions
   131 		IMPORT_C CTzLocalizedCity* FindCityByNameL(const TDesC& aCityName, const TInt aTimeZoneId = 0);
   132 		IMPORT_C CTzLocalizedTimeZone* FindTimeZoneByNameL(const TDesC& aTimeZoneName);
   133 		IMPORT_C CTzLocalizedCityGroup* FindCityGroupByNameL(const TDesC& aCityGroupName);
   134 		
   135 		IMPORT_C TBool CheckLanguage();
   136 		
   137 		//Cities and Time Zones with a specified UTC offset
   138 		IMPORT_C CTzLocalizedCityArray* GetCitiesWithUTCOffsetL(TInt aUTCOffsetInMinutes, const TTzSortOrder aSortOrder = ETzUnsorted);
   139 		IMPORT_C CTzLocalizedTimeZoneArray* GetTimeZonesWithUTCOffsetL(TInt aUTCOffsetInMinutes, const TTzSortOrder aSortOrder = ETzUnsorted);
   140 		
   141 	private:
   142 		void ConstructL();
   143 		CTzLocalizer();
   144 		
   145 		TBool PrepareFrequentlyUsedZonesL();
   146 		void UpdateFrequentlyUsedZonesL();
   147 		CTzLocalizedTimeZone* GetFrequentlyUsedDefaultZoneL(CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFreqUsedZone);
   148 		TUint32 GetFrequentlyUsedDefaultZoneCenRepKeyL(CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFreqUsedZone);
   149 		
   150 		void GetCitiesL(CTzLocalizedCityArray& aCities, const TTzLocalizedId& aLocalizedId, const TTzSortOrder aSortOrder = ETzUnsorted);
   151 		
   152 		TLinearOrder<CTzLocalizedCity> CitySortOrderL(const TTzSortOrder aSortOrder);
   153 		TLinearOrder<CTzLocalizedTimeZone> TimeZoneSortOrderL(const TTzSortOrder aSortOrder);
   154 		template <class T> void PrepareForUTCSortL(T& aArray);
   155 		
   156 		TInt GetTimeZoneIdFromTzServerL();
   157 		void DoSetTimeZoneL(TInt aTimeZoneId);
   158 		void ChangeHomeTimeZoneL(TInt aNewId);
   159 		
   160 		void ValidateDbL();
   161         void RecreateDbL();
   162         TBool DbNeedsUpdatingL() const;
   163 		TBool DbIsInvalidL() const;
   164         void UpgradeDbVersionL();
   165         void FetchCityToUpgradeL(CTzLocalizedTimeZoneArray& aTimeZoneArray, CTzLocalizedCityArray& aCityArray, CTzLocalizedTimeZone::TTzFrequentlyUsedZone aCachedZone);
   166 
   167 	private:
   168 		//Member data
   169 		MTzLocalizationReader* iStaticDataReader;
   170 		MTzLocalizationReader* iPersistedDataReader;
   171 		MTzLocalizationWriter* iPersistedDataWriter;
   172 		TLanguage iLanguage;
   173 	};
   174 
   175 #endif//__TzLocalizer_H__