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@2: // 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
williamr@2: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.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@2: #include <e32base.h>
williamr@2: #include <s32std.h>
williamr@2: #include <tzdefines.h>
williamr@2: #include <tzupdate.h>
williamr@2: 
williamr@2: class CTzChangeNotifier;
williamr@2: class CTzRules;
williamr@2: class CTzRuleHolder;
williamr@2: 
williamr@2: //-------------------------------------------------------------------------
williamr@2: /**
williamr@2: Encapsulates a time zone identifier.
williamr@2: 
williamr@2: The identifier may be either a name or a number.
williamr@2: @publishedAll
williamr@2: @released
williamr@2: @since 9.1
williamr@2: */
williamr@2: class CTzId : public CBase
williamr@2: 	{
williamr@2: public:
williamr@2: 
williamr@2: 	IMPORT_C ~CTzId();
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalComponent 
williamr@2: 	*/
williamr@2: 	IMPORT_C CTzId* CloneL() const;
williamr@2: 	
williamr@2: 	IMPORT_C static CTzId* NewL(TUint aNumericId);
williamr@2: 	
williamr@2: 	IMPORT_C static CTzId* NewL(const TDesC8& aNameIdentity);
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalComponent 
williamr@2: 	*/
williamr@2: 	IMPORT_C static CTzId* NewL(RReadStream& aStream);
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalComponent 
williamr@2: 	*/
williamr@2: 	IMPORT_C void SetId(TUint aNumericId);
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalComponent 
williamr@2: 	*/
williamr@2: 	IMPORT_C void SetIdL(const TDesC8& aNameIdentity);
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalComponent 
williamr@2: 	*/
williamr@2: 	IMPORT_C void InternalizeL(RReadStream& aStream);
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalComponent 
williamr@2: 	*/
williamr@2: 	IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
williamr@2: 
williamr@2: 	IMPORT_C const TDesC8& TimeZoneNameID() const;
williamr@2: 	
williamr@2: 	IMPORT_C TUint TimeZoneNumericID() const;
williamr@2: 	
williamr@2: 	IMPORT_C TBool operator==(const CTzId& aTZId) const;
williamr@2: 
williamr@2: 	inline TBool operator!=(const CTzId& aTZId) const;
williamr@2: 
williamr@2: public:
williamr@2: 	static CTzId* NewL(TUint aReferenceId, const TDesC8& aZoneIdentity);
williamr@2: 	void SetIdL(TUint aNumRefId, const TDesC8& aZoneIdentity);
williamr@2: 
williamr@2: private:
williamr@2: 	void ConstructL(const TDesC8& aZoneIdentity);
williamr@2: 	CTzId();
williamr@2: 	CTzId(TUint aNumericId);
williamr@2: 
williamr@2: private:
williamr@2: 	HBufC8* iZoneId;
williamr@2: 	TUint32 iReferenceId;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: /** 
williamr@2: The client interface to the time zone server. 
williamr@2: 
williamr@2: This class performs two basic functions:
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@2: User::SetUTCTimeAndOffset(). The time zone server is shutdown when the 
williamr@2: last session (RTz) is closed. Therefore, to maintain consistent time related behaviour, 
williamr@2: licensees may want to keep a system level time zone server session open at all times.
williamr@2: 
williamr@2: @see User
williamr@2: 
williamr@2: Exceptional cases occur when a user requests conversion 
williamr@2: for a non-existent local time or a double local time. 
williamr@2: 
williamr@2: Non-existent local times occur when the local time 
williamr@2: changes from winter to summer for DST.
williamr@2: 
williamr@2: For example, 01:59 local time is non-existent on the day of a change to BST
williamr@2: in Europe/London since the time changes directly from 12:59:59 to 2:00.
williamr@2: 
williamr@2: A double local time occurs when the local time changes from
williamr@2: summer to winter. 
williamr@2: 
williamr@2: For example, if the time changes at 02:00 AM BST to 01:00 AM GMT
williamr@2: then local times between 01:00 and 01:59 occur twice.
williamr@2: 
williamr@2: The conversion applies the DST offset if the local time value is double and applies
williamr@2: the standard UTC offset if the local time does not exists.
williamr@2: 
williamr@2: This decision makes the conversion process asymmetrical around
williamr@2: the discontinuity in the local time when there is a DST change.
williamr@2: 
williamr@2: An example conversion from a double local time to UTC and 
williamr@2: from UTC to a double 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: 
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@2: 	These enumerators are to describe different modes of the automatic 
williamr@2: 	DST event handling.
williamr@2: 
williamr@2: 	These are used both as arguments for the API SetAutoUpdateBehaviorL, 
williamr@2: 	and as notifications for the publish and subscribe.
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@2: 		/** Automatic time update will occur and the client app will be notified. */
williamr@2: 		ETZAutoDSTUpdateOn,
williamr@2: 
williamr@2: 		/** Client app needs to confirm that the time should be updated whenever a DST event occurs. */
williamr@2: 		ETZAutoDSTNotificationOnly,
williamr@2: 		};
williamr@2: 
williamr@2: 	enum TTzChanges
williamr@2: 		{
williamr@2: 		/** Used for notifying that the timezone database has changed.*/
williamr@2: 		ETZDatabaseChanged = 1,
williamr@2: 		/** Used for notifying that the system timezone database 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@2: 		ETZAutomaticTimeUpdate
williamr@2: 		};
williamr@2: 
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@2: 		/** This panic indicates that there are no rules present for this time zone.*/
williamr@2: 		EPanicTimeNotCoveredByRules,
williamr@2: 		/** This panic indicates that the time zone rules are unusable.*/
williamr@2: 		EPanicBadTimeZoneRules,
williamr@2: 		/** This panic indicates  that an unsupported time reference has been accessed.*/
williamr@2: 		EPanicUnsupportedTimeReference,
williamr@2: 		/** This panic indicates that the time zone ID is not supported.*/
williamr@2: 		EPanicUnsupportedTimeZoneNoId,
williamr@2: 		/** This panic indicates that a request for notification is already pending from the client.*/
williamr@2: 		EPanicNotificationRequestPending,
williamr@2: 		/** This panic indicates that an incorrect data has been sent to the server.*/
williamr@2: 		EPanicInvalidArgument
williamr@2: 		};
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalComponent 
williamr@2: 	*/
williamr@2: 	IMPORT_C static void Panic(TPanic aPanic);
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalTechnology
williamr@2: 	*/
williamr@2: 	IMPORT_C CTzId* GetTimeZoneIdL() const;
williamr@2: 	
williamr@2: 	/** 
williamr@2: 	@internalTechnology
williamr@2: 	*/
williamr@2: 	IMPORT_C void SetTimeZoneL(CTzId& aZone) const;
williamr@2: 
williamr@2: 	IMPORT_C void Close();
williamr@2: 	
williamr@2: 	IMPORT_C TInt Connect();
williamr@2: 
williamr@2: 	IMPORT_C ~RTz();
williamr@2: 	
williamr@2: 	IMPORT_C RTz();
williamr@2: 	
williamr@2: 	IMPORT_C TInt ConvertToLocalTime(TTime& aTime) const;
williamr@2: 	
williamr@2: 	IMPORT_C TInt ConvertToLocalTime(TTime& aTime, const CTzId& aZone) const;
williamr@2: 
williamr@2: 	IMPORT_C TInt ConvertToUniversalTime(TTime& aTime) const;
williamr@2: 	
williamr@2: 	IMPORT_C TInt ConvertToUniversalTime(TTime& aTime, const CTzId& aZone) const;
williamr@2: 	
williamr@2: 	IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray<TInt>& aTzNumericIds, RArray<TInt>& aOffsets) const; 
williamr@2: 	
williamr@2: 	IMPORT_C TInt AutoUpdateSettingL();
williamr@2: 	
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:     
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@2: 	IMPORT_C CTzRules* GetTimeZoneRulesL(const TTime& aStartTime, const TTime& aEndTime, TTzTimeReference aTimeRef) const;
williamr@2: 	
williamr@2: 	IMPORT_C CTzRules* GetTimeZoneRulesL(const CTzId& aZone, const TTime& aStartTime, const TTime& aEndTime, 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@2: 	IMPORT_C void NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange& aChange) const;
williamr@2: 	
williamr@2: 	IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset);
williamr@2: 	
williamr@2: 	IMPORT_C void SetUnknownZoneTimeL(const TTime& aUTCTime, const TInt aUTCOffset, TBool aPersistInCenRep);
williamr@2: 
williamr@2: 	IMPORT_C void __dbgClearCacheL(TBool aRestartCaching);
williamr@2: 
williamr@2:     TBool StartCachingL();
williamr@2:     TUint16 CurrentCachedTzId();
williamr@2: 
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@2: private:
williamr@2: 	CTzRuleHolder* iRulesHolder;
williamr@2: 	};
williamr@2: 
williamr@2: /**
williamr@2: Encapsulates a TTime and a TTzTimeReference.
williamr@2: Use, for example, for iCalendar's DTSTART.
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@2: 	inline TTimeWithReference();
williamr@2: 	inline TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference);
williamr@2: 	inline TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference=ETzUtcTimeReference);
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: /** Inequality operator.
williamr@2: 
williamr@2: @param aTZId The time zone ID to compare with this one.
williamr@2: @return True if the two IDs are different. False if they are the same.
williamr@2: */
williamr@2: inline TBool CTzId::operator!=(const CTzId& aTZId) const
williamr@2: 	{
williamr@2: 	return (!operator==(aTZId));
williamr@2: 	}
williamr@2: 
williamr@2: //////////////////////////////////
williamr@2: // TTimeWithReference
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@2: inline TTimeWithReference::TTimeWithReference() 
williamr@2: 		: iTime(0), iTimeReference(ETzUtcTimeReference)
williamr@2: 	{
williamr@2: 	}
williamr@2: inline TTimeWithReference::TTimeWithReference(TTime aTime, TTzTimeReference aTimeReference)
williamr@2: 		: iTime(aTime), iTimeReference(aTimeReference)
williamr@2: 	{
williamr@2: 	}
williamr@2: inline TTimeWithReference::TTimeWithReference(TDateTime aTime, TTzTimeReference aTimeReference)
williamr@2: 		: iTime(aTime), iTimeReference(aTimeReference)
williamr@2: 	{
williamr@2: 	}
williamr@2: inline bool TTimeWithReference::operator==(const TTimeWithReference& aTime) const
williamr@2: 	{
williamr@2: 	return(aTime.iTime == iTime && aTime.iTimeReference == iTimeReference);
williamr@2: 	}
williamr@2: inline bool TTimeWithReference::operator!=(const TTimeWithReference& aTime) const
williamr@2: 	{
williamr@2: 	return(!(*this == aTime));
williamr@2: 	}
williamr@2: #endif