williamr@2: // Copyright (c) 1997-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 __TIMEZONE_H__
williamr@2: #define __TIMEZONE_H__
williamr@2: 
williamr@4: 
williamr@2: #include <e32base.h>
williamr@2: #include <s32std.h>
williamr@4: #include <s32strm.h>
williamr@2: #include <tzdefines.h>
williamr@4: #include <tzid.h>
williamr@2: #include <tzupdate.h>
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: #include <tzlocalizedcityrecord.h> //This should be be included as it is internalTechnology.
williamr@4: #include <tzlocalizedtimezonerecord.h> // Same as above and probably should not be exported to the epoc include
williamr@4: #endif
williamr@2: 
williamr@4: 
williamr@4: // Forward class references.
williamr@2: class CTzRules;
williamr@2: class CTzRuleHolder;
williamr@4: class CTzLocalizedCityRecord;
williamr@4: #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS // This can be forward declared i.e. it should not be included as it is internal.
williamr@4: class CTzLocalizedTimeZoneRecord;
williamr@4: #endif
williamr@2: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@2: /**
williamr@4: The CTzUserNames class is used to encapsulate the names for a user-defined
williamr@4: time zone.
williamr@2: 
williamr@4: When creating an instance of this class the client can specify the following
williamr@4: names:
williamr@4: 
williamr@4: - Long standard time name, for example "Mountain Standard Time"
williamr@4: - Short standard time name, for example "MST"
williamr@4: - Long daylight saving time name, for example "Mountain Daylight Time"
williamr@4: - Short daylight saving time name, for example "MDT"
williamr@4: - City name, for example "Shiprock"
williamr@4: - Region name, for example "America"
williamr@4: 
williamr@4: The client can also read these names.  
williamr@4: 
williamr@4: @publishedPartner
williamr@2: @released
williamr@4: */ 
williamr@4: class CTzUserNames : public CBase
williamr@4:     {
williamr@2: public:
williamr@4:     IMPORT_C static CTzUserNames* NewL(const TDesC& aStandardName,
williamr@4:     	const TDesC& aShortStandardName, const TDesC& aDaylightSaveName,
williamr@4:     	const TDesC& aShortDaylightSaveName, const TDesC& aCityName,
williamr@4:     	const TDesC& aRegionName);
williamr@4:     IMPORT_C static CTzUserNames* NewLC(const TDesC& aStandardName,
williamr@4:     	const TDesC& aShortStandardName, const TDesC& aDayLightSaveName,
williamr@4:     	const TDesC& aShortDaylightSaveName, const TDesC& aCityName,
williamr@4:     	const TDesC& aRegionName);
williamr@4: 	IMPORT_C ~CTzUserNames();
williamr@2: 	
williamr@4: 	IMPORT_C const TDesC& StandardName() const;
williamr@4: 	IMPORT_C const TDesC& ShortStandardName() const;
williamr@4: 	IMPORT_C const TDesC& DaylightSaveName() const;
williamr@4: 	IMPORT_C const TDesC& ShortDaylightSaveName() const;
williamr@4: 	IMPORT_C const TDesC& CityName() const;
williamr@4: 	IMPORT_C const TDesC& RegionName() const;
williamr@2: 	
williamr@4: 	IMPORT_C static CTzUserNames* NewL(RReadStream& aStream);
williamr@4: 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
williamr@2: 	IMPORT_C void InternalizeL(RReadStream& aStream);
williamr@4: 	IMPORT_C TInt SizeOfObject() const;
williamr@2: 
williamr@2: private:
williamr@4:     CTzUserNames();
williamr@4: 	void ConstructL(const TDesC& aStandardName, const TDesC& aShortStandardName,
williamr@4: 		const TDesC& aDayLightSaveName, const TDesC& aShortDayLightSaveName,
williamr@4: 		const TDesC& aCityName, const TDesC& aRegionName);
williamr@4: 	
williamr@2: private:
williamr@4:     HBufC* iStandardName;
williamr@4:     HBufC* iShortStandardName;
williamr@4:     HBufC* iDaylightName;
williamr@4:     HBufC* iShortDaylightName;	
williamr@4:     HBufC* iCityName;
williamr@4:     HBufC* iRegionName;
williamr@4:     };
williamr@4: #else
williamr@4: class CTzUserNames;
williamr@4: #endif //SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@2: /** 
williamr@2: The client interface to the time zone server. 
williamr@2: 
williamr@2: This class performs two basic functions:
williamr@4: 
williamr@2: 1. Converts between UTC time and local time.
williamr@2: 2. Sets the current local time zone.
williamr@2: 
williamr@2: NOTE: The presence of a time zone server will alter the behaviour of the 
williamr@2: time zone related function calls User::SetUTCOffset() and 
williamr@4: User::SetUTCTimeAndOffset().  The time zone server is shutdown when the last
williamr@4: session (RTz) is closed.  Therefore, to maintain consistent time related
williamr@4: behaviour, licensees may want to keep a system level time zone server session
williamr@4: open at all times.
williamr@2: 
williamr@4: Exceptional cases occur when a user requests conversion for a non-existent local
williamr@4: time or a double local time. 
williamr@2: 
williamr@4: Non-existent local times occur when the local time changes from winter to summer
williamr@4: for DST.
williamr@2: 
williamr@4: For example, 01:59 local time is non-existent on the day of a change to BST in
williamr@4: Europe/London since the time changes directly from 12:59:59 to 2:00.
williamr@2: 
williamr@4: A double local time occurs when the local time changes from summer to winter. 
williamr@2: 
williamr@4: For example, if the time changes at 02:00 AM BST to 01:00 AM GMT then local
williamr@4: times between 01:00 and 01:59 occur twice.
williamr@2: 
williamr@4: The conversion applies the DST offset if the local time value is double and
williamr@4: applies the standard UTC offset if the local time does not exists.
williamr@2: 
williamr@4: This decision makes the conversion process asymmetrical around the discontinuity
williamr@4: in the local time when there is a DST change.
williamr@2: 
williamr@4: An example conversion from a double local time to UTC and from UTC to a double
williamr@4: local time is:
williamr@2: 
williamr@2: 	01:59 AM BST => 00:59 AM UTC
williamr@2: 	01:59 AM UTC => 01:59 AM GMT
williamr@2: 	
williamr@2: An example conversion from a non-existent local time to UTC 
williamr@2: and from UTC to local time is:
williamr@2: 
williamr@2:     01:59 AM GMT => 01:59 AM UTC
williamr@2:     01:59 AM UTC => 02:59 AM BST 	
williamr@2: 	
williamr@2: @publishedAll
williamr@2: @released
williamr@2: @since 9.1
williamr@2: */
williamr@2: class RTz : public RSessionBase
williamr@2: 	{
williamr@2: public:
williamr@2: 	/**
williamr@4: 	Automatic DST update mode.
williamr@2: 	*/
williamr@2: 	enum TTzAutoDSTUpdateModes
williamr@2: 		{
williamr@2: 		/** No auto update notification when a DST event occurs. */
williamr@2: 		ETZAutoDSTUpdateOff = 0,
williamr@2: 
williamr@4: 		/** Automatic time update will occur and the client app will be
williamr@4: 			notified. */
williamr@2: 		ETZAutoDSTUpdateOn,
williamr@2: 
williamr@4: 		/** Client app needs to confirm that the time should be updated whenever
williamr@4: 			a DST event occurs. */
williamr@2: 		ETZAutoDSTNotificationOnly,
williamr@2: 		};
williamr@2: 
williamr@4: 	/**
williamr@4: 	Time zone server change events.
williamr@4: 	*/
williamr@2: 	enum TTzChanges
williamr@2: 		{
williamr@2: 		/** Used for notifying that the timezone database has changed.*/
williamr@2: 		ETZDatabaseChanged = 1,
williamr@4: 		/** Used for notifying that the system timezone has changed.*/
williamr@2: 		ETZSystemTimeZoneChanged,
williamr@2: 		/** Used for notifying that the DST rule has changed. */
williamr@2: 		ETZDSTRuleChanged,
williamr@2: 		/** Used for notifying that an automatic time update has taken place. */
williamr@4: 		ETZAutomaticTimeUpdate,
williamr@4: 		/** Used for notifying that a change in localization resources has taken
williamr@4: 			place. */
williamr@4: 		ETZLocalizationDataChanged
williamr@2: 		};
williamr@2: 
williamr@4: 	/**
williamr@4: 	Time zone server panic codes.
williamr@4: 	*/
williamr@2: 	enum TPanic
williamr@2: 		{
williamr@2: 		/** This panic indicates that the time zone server has not been found.*/
williamr@2: 		EPanicServerNotFound = 1,
williamr@2: 		/** This panic indicates that the server has died.*/
williamr@2: 		EPanicServerDead,
williamr@2: 		/** This panic indicates that the time zone ID is not set.*/
williamr@2: 		EPanicTimeZoneNameIdNotSet,
williamr@2: 		/** This panic indicates that an out of range index was accessed.*/
williamr@2: 		EPanicRulesIndexOutofRange,
williamr@4: 		/** This panic indicates that there are no rules present for this time
williamr@4: 			zone.*/
williamr@2: 		EPanicTimeNotCoveredByRules,
williamr@2: 		/** This panic indicates that the time zone rules are unusable.*/
williamr@2: 		EPanicBadTimeZoneRules,
williamr@4: 		/** This panic indicates  that an unsupported time reference has been
williamr@4: 			accessed.*/
williamr@2: 		EPanicUnsupportedTimeReference,
williamr@2: 		/** This panic indicates that the time zone ID is not supported.*/
williamr@2: 		EPanicUnsupportedTimeZoneNoId,
williamr@4: 		/** This panic indicates that a request for notification is already
williamr@4: 			pending from the client.*/
williamr@2: 		EPanicNotificationRequestPending,
williamr@4: 		/** This panic indicates that an incorrect data has been sent to the
williamr@4: 			server.*/
williamr@4: 		EPanicInvalidArgument,
williamr@4: 		/** This panic indicates that a table in the user-defined time zone
williamr@4: 			database has not conformed to the declared schema. */
williamr@4: 		EPanicBadSchema
williamr@2: 		};
williamr@2: 	
williamr@4: 	/**
williamr@4: 	The software install observer plugin can distinguish between changes to the
williamr@4: 	resource files or the rules database.  This enumeration indicates the filter
williamr@4: 	index that is used for the resource files and rules database filters.
williamr@4: 	This enum should not be used externally.
williamr@4: 	*/
williamr@4: 	enum TSWIObserverFilterIndex
williamr@4: 		{
williamr@4: 		/** The index of the Tz private directory filter. */
williamr@4: 		EFilterTzPrivate=0,
williamr@4: 		/** The index of the resources filter. */
williamr@4: 		EFilterResourceTimezonelocalization
williamr@4: 		};
williamr@4: 		
williamr@4: public:
williamr@2: 	/** 
williamr@4: 	This should not be used externally.
williamr@2: 	*/
williamr@2: 	IMPORT_C static void Panic(TPanic aPanic);
williamr@2: 	
williamr@2: 	/** 
williamr@4: 	This should not be used externally.
williamr@2: 	*/
williamr@2: 	IMPORT_C CTzId* GetTimeZoneIdL() const;
williamr@2: 	
williamr@2: 	/** 
williamr@4: 	This should not be used externally.
williamr@2: 	*/
williamr@2: 	IMPORT_C void SetTimeZoneL(CTzId& aZone) const;
williamr@2: 
williamr@2: 	IMPORT_C void Close();
williamr@2: 	IMPORT_C TInt Connect();
williamr@2: 
williamr@2: 	IMPORT_C ~RTz();
williamr@2: 	IMPORT_C RTz();
williamr@2: 	
williamr@2: 	IMPORT_C TInt ConvertToLocalTime(TTime& aTime) const;
williamr@2: 	IMPORT_C TInt ConvertToLocalTime(TTime& aTime, const CTzId& aZone) const;
williamr@2: 	IMPORT_C TInt ConvertToUniversalTime(TTime& aTime) const;
williamr@2: 	IMPORT_C TInt ConvertToUniversalTime(TTime& aTime, const CTzId& aZone) const;
williamr@2: 	
williamr@4: 	IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray<TInt>& aTzNumericIds,
williamr@4: 		RArray<TInt>& aOffsets) const; 
williamr@2: 	
williamr@2: 	IMPORT_C TInt AutoUpdateSettingL();
williamr@2:     IMPORT_C void SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes aUpdateEnabled);
williamr@2:     
williamr@2:     // Methods for setting the system time.
williamr@2:     IMPORT_C TInt SetHomeTime(const TTime& aLocalTime) const;
williamr@2: 
williamr@2:     IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone) const;
williamr@2:     IMPORT_C TBool IsDaylightSavingOnL(CTzId& aZone, const TTime& aUTCTime) const;
williamr@2: 
williamr@2:  	// Get Encoded Rules for Current Local Time Zone
williamr@4: 	IMPORT_C CTzRules* GetTimeZoneRulesL(const TTime& aStartTime,
williamr@4: 		const TTime& aEndTime, TTzTimeReference aTimeRef) const;
williamr@4: 	IMPORT_C CTzRules* GetTimeZoneRulesL(const CTzId& aZone,
williamr@4: 		const TTime& aStartTime, const TTime& aEndTime,
williamr@4: 		TTzTimeReference aTimeRef) const;
williamr@2: 	
williamr@2: 	void RegisterTzChangeNotifier(TRequestStatus& aStatus) const;
williamr@2: 	TInt CancelRequestForNotice() const;
williamr@2: 	TVersion Version() const;
williamr@2: 	
williamr@4: 	IMPORT_C void NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange&
williamr@4: 		aChange) const;
williamr@2: 	
williamr@4: 	IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime,
williamr@4: 		const TInt aUTCOffset);
williamr@4: 	IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime,
williamr@4: 		const TInt aUTCOffset, TBool aPersistInCenRep);
williamr@2: 	
williamr@4: 	IMPORT_C void LocalizationReadCitiesL(RPointerArray<CTzLocalizedCityRecord>&
williamr@4: 		aCities);
williamr@4: 	IMPORT_C void LocalizationReadCitiesL(RPointerArray<CTzLocalizedCityRecord>&
williamr@4: 		aCities, TInt aTimeZoneId);
williamr@4: 	IMPORT_C void LocalizationReadCitiesInGroupL(RPointerArray<CTzLocalizedCityRecord>&
williamr@4: 		aCities, TUint8 aGroupId);
williamr@4: 	IMPORT_C CTzLocalizedTimeZoneRecord* LocalizationReadFrequentlyUsedZoneL(
williamr@4: 		TInt aFrequentlyUsedZone);
williamr@4: 	IMPORT_C CTzLocalizedCityRecord* LocalizationReadCachedTimeZoneCityL(
williamr@4: 		TInt aFrequentlyUsedZone);
williamr@4: 	IMPORT_C void LocalizationCloseDbL();
williamr@4: 	IMPORT_C void LocalizationOpenDbL();
williamr@4: 	IMPORT_C void LocalizationWriteCityL(const TDesC& aCityName, TInt aCityTzId,
williamr@4: 		TUint8 aCityGroupId, TUint aCityTzResourceId);
williamr@4: 	IMPORT_C void LocalizationDeleteCityL(const TDesC& aCityName,
williamr@4: 		TInt aCityTzId);
williamr@4: 	IMPORT_C void LocalizationWriteFrequentlyUsedZoneL(const CTzLocalizedTimeZoneRecord&
williamr@4: 		aTimeZone, const CTzLocalizedCityRecord& aCity,
williamr@4: 		TInt aFrequentlyUsedZone);
williamr@4: 	IMPORT_C void LocalizationWriteAllFrequentlyUsedZonesL(const RPointerArray<CTzLocalizedTimeZoneRecord>& aTimeZones,
williamr@4: 		const RPointerArray<CTzLocalizedCityRecord>& aCities);
williamr@4: 	
williamr@4: 	// Debug only methods.
williamr@4: 	IMPORT_C void SwiObsBeginL();
williamr@4: 	IMPORT_C void SwiObsFileChangedL(TSWIObserverFilterIndex aType);
williamr@4: 	IMPORT_C void SwiObsEndL();
williamr@2: 
williamr@4: 	// Debug only methods.
williamr@2: 	IMPORT_C void __dbgClearCacheL(TBool aRestartCaching);
williamr@4: 	IMPORT_C TInt __dbgRequestAllocatedCellsL(TInt aHeapSizeInBytes);
williamr@4: 	IMPORT_C void __dbgSetHeapFailL(RAllocator::TAllocFail aType, TInt aRate);
williamr@4: 	IMPORT_C void __dbgResetHeapL();
williamr@2: 
williamr@2:     TBool StartCachingL();
williamr@2:     TUint16 CurrentCachedTzId();
williamr@2: 
williamr@4: 	// User-defined time zone access.
williamr@4:     CTzId* CreateUserTimeZoneL(const CTzRules& aTzUserRules, const CTzUserNames& aTzUserNames);
williamr@4:     CTzUserNames* GetUserTimeZoneNamesL(const CTzId& aTzId) const;
williamr@4:     void UpdateUserTimeZoneL(const CTzId& aTzId, const CTzRules& aTzUserRules, const CTzUserNames& aTzUserNames);
williamr@4:     void DeleteUserTimeZoneL(const CTzId& aTzId);
williamr@4: 	void GetUserTimeZoneIdsL(RPointerArray<CTzId>& aTzIds) const;
williamr@4: 	
williamr@2: private:
williamr@2: 	static TInt StartServer();
williamr@2: 	TInt DoConnect();
williamr@2: 	void doConvertL(const CTzId& aZone, TTime& aTime,
williamr@2: 					TTzTimeReference aTimerRef) const;
williamr@2: 	void doConvertL(TTime& aTime, 
williamr@2: 					TTzTimeReference aTimerRef) const;
williamr@4: 					
williamr@4: 	
williamr@4: 
williamr@2: private:
williamr@2: 	CTzRuleHolder* iRulesHolder;
williamr@2: 	};
williamr@2: 
williamr@4: 
williamr@2: /**
williamr@2: Encapsulates a TTime and a TTzTimeReference.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class TTimeWithReference
williamr@2: 	{
williamr@2: public:
williamr@2: 	static inline TTimeWithReference Max();
williamr@4: 
williamr@2: 	inline TTimeWithReference();
williamr@2: 	inline TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference);
williamr@2: 	inline TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference);
williamr@4: 
williamr@2: 	inline bool operator==(const TTimeWithReference& aTime) const;
williamr@2: 	inline bool operator!=(const TTimeWithReference& aTime) const;
williamr@2: 
williamr@2: 	TTime iTime;
williamr@2: 	TTzTimeReference iTimeReference;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: inline TTimeWithReference TTimeWithReference::Max()
williamr@2: 	{
williamr@2: 	return TTimeWithReference(
williamr@2: 		TDateTime(9999,EDecember,30,23,59,59,0), 
williamr@2: 		ETzUtcTimeReference);
williamr@2: 	}
williamr@2: 
williamr@4: 
williamr@2: inline TTimeWithReference::TTimeWithReference() 
williamr@4: 	: iTime(0), iTimeReference(ETzUtcTimeReference)
williamr@2: 	{
williamr@2: 	}
williamr@4: 
williamr@4: 
williamr@2: inline TTimeWithReference::TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference)
williamr@4: 	: iTime(aTime), iTimeReference(aTimeReference)
williamr@2: 	{
williamr@2: 	}
williamr@4: 
williamr@4: 
williamr@2: inline TTimeWithReference::TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference)
williamr@4: 	: iTime(aTime), iTimeReference(aTimeReference)
williamr@2: 	{
williamr@2: 	}
williamr@4: 
williamr@4: 
williamr@2: inline bool TTimeWithReference::operator==(const TTimeWithReference& aTime) const
williamr@2: 	{
williamr@2: 	return(aTime.iTime == iTime && aTime.iTimeReference == iTimeReference);
williamr@2: 	}
williamr@4: 
williamr@4: 
williamr@2: inline bool TTimeWithReference::operator!=(const TTimeWithReference& aTime) const
williamr@2: 	{
williamr@2: 	return(!(*this == aTime));
williamr@2: 	}
williamr@4: 
williamr@4: #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: /**
williamr@4: The CTzUserData class allows the client to create, read, update or delete
williamr@4: user-defined time zones. 
williamr@4: 
williamr@4: A user-defined time zone is comprised of time zone rules (encapsulated in a
williamr@4: CTzRules object) and time zone names (encapsulated in a CTzUserNames object).
williamr@4: 
williamr@4: A time zone identifier (encapsulated in a CTzId object) is used to uniquely
williamr@4: identify a user-defined time zone.
williamr@4: 
williamr@4: The CTzUserData class also allows the time zone identifiers for all existing
williamr@4: user-defined time zones to be determined. 
williamr@4: 
williamr@4: @publishedPartner
williamr@4: @released
williamr@4: */
williamr@4: class CTzUserData : public CBase
williamr@4:     {
williamr@4: public:
williamr@4:     IMPORT_C static CTzUserData* NewL(RTz& aTzServer);
williamr@4:     IMPORT_C ~CTzUserData();
williamr@4: 
williamr@4:     IMPORT_C CTzId* CreateL(const CTzRules& aTzUserRules, const CTzUserNames&
williamr@4:     	aTzUserNames);
williamr@4:     IMPORT_C CTzRules* ReadRulesL(const CTzId& aTzId) const;
williamr@4: 	IMPORT_C CTzUserNames* ReadNamesL(const CTzId& aTzId) const;
williamr@4:     IMPORT_C void UpdateL(const CTzId& aTzId, const CTzRules& aTzUserRules,
williamr@4:     	const CTzUserNames& aTzUserNames);
williamr@4:     IMPORT_C void DeleteL(const CTzId& aTzId);
williamr@4:     IMPORT_C void GetTzIdsL(RPointerArray<CTzId>& aTzIds) const;
williamr@4: 
williamr@4: private:
williamr@4:     CTzUserData(RTz& aTzServer);
williamr@4: 	
williamr@4: private:
williamr@4:     RTz& iTzServer;
williamr@4: 	};
williamr@4: 	
williamr@4: #endif // SYMBIAN_ENABLE_SPLIT_HEADERS
williamr@4: 
williamr@2: #endif