RTz Class Reference

class RTz : public RSessionBase

The client interface to the time zone server.

This class performs two basic functions:

1. Converts between UTC time and local time. 2. Sets the current local time zone.

NOTE: The presence of a time zone server will alter the behaviour of the time zone related function calls User::SetUTCOffset() and User::SetUTCTimeAndOffset(). The time zone server is shutdown when the last session (RTz) is closed. Therefore, to maintain consistent time related behaviour, licensees may want to keep a system level time zone server session open at all times.

Exceptional cases occur when a user requests conversion for a non-existent local time or a double local time.

Non-existent local times occur when the local time changes from winter to summer for DST.

For example, 01:59 local time is non-existent on the day of a change to BST in Europe/London since the time changes directly from 12:59:59 to 2:00.

A double local time occurs when the local time changes from summer to winter.

For example, if the time changes at 02:00 AM BST to 01:00 AM GMT then local times between 01:00 and 01:59 occur twice.

The conversion applies the DST offset if the local time value is double and applies the standard UTC offset if the local time does not exists.

This decision makes the conversion process asymmetrical around the discontinuity in the local time when there is a DST change.

An example conversion from a double local time to UTC and from UTC to a double local time is:

01:59 AM BST => 00:59 AM UTC 01:59 AM UTC => 01:59 AM GMT

An example conversion from a non-existent local time to UTC and from UTC to local time is:

01:59 AM GMT => 01:59 AM UTC 01:59 AM UTC => 02:59 AM BST

9.1

Inherits from

Public Member Functions
RTz()
~RTz()
IMPORT_C TIntAutoUpdateSettingL()
TInt CancelRequestForNotice()
IMPORT_C voidClose()
IMPORT_C TIntConnect()
IMPORT_C TIntConvertToLocalTime(TTime &)
IMPORT_C TIntConvertToLocalTime(TTime &, const CTzId &)
IMPORT_C TIntConvertToUniversalTime(TTime &)
IMPORT_C TIntConvertToUniversalTime(TTime &, const CTzId &)
CTzId *CreateUserTimeZoneL(const CTzRules &, const CTzUserNames &)
TUint16 CurrentCachedTzId()
voidDeleteUserTimeZoneL(const CTzId &)
IMPORT_C voidGetOffsetsForTimeZoneIdsL(const RArray< TInt > &, RArray< TInt > &)
IMPORT_C CTzId *GetTimeZoneIdL()
IMPORT_C CTzRules *GetTimeZoneRulesL(const TTime &, const TTime &, TTzTimeReference)
IMPORT_C CTzRules *GetTimeZoneRulesL(const CTzId &, const TTime &, const TTime &, TTzTimeReference)
voidGetUserTimeZoneIdsL(RPointerArray< CTzId > &)
CTzUserNames *GetUserTimeZoneNamesL(const CTzId &)
IMPORT_C TBoolIsDaylightSavingOnL(CTzId &)
IMPORT_C TBoolIsDaylightSavingOnL(CTzId &, const TTime &)
IMPORT_C voidLocalizationCloseDbL()
IMPORT_C voidLocalizationDeleteCityL(const TDesC &, TInt)
IMPORT_C voidLocalizationOpenDbL()
IMPORT_C CTzLocalizedCityRecord *LocalizationReadCachedTimeZoneCityL(TInt)
IMPORT_C voidLocalizationReadCitiesInGroupL(RPointerArray< CTzLocalizedCityRecord > &, TUint8)
IMPORT_C voidLocalizationReadCitiesL(RPointerArray< CTzLocalizedCityRecord > &)
IMPORT_C voidLocalizationReadCitiesL(RPointerArray< CTzLocalizedCityRecord > &, TInt)
IMPORT_C CTzLocalizedTimeZoneRecord *LocalizationReadFrequentlyUsedZoneL(TInt)
IMPORT_C voidLocalizationWriteAllFrequentlyUsedZonesL(const RPointerArray< CTzLocalizedTimeZoneRecord > &, const RPointerArray< CTzLocalizedCityRecord > &)
IMPORT_C voidLocalizationWriteCityL(const TDesC &, TInt, TUint8, TUint)
IMPORT_C voidLocalizationWriteFrequentlyUsedZoneL(const CTzLocalizedTimeZoneRecord &, const CTzLocalizedCityRecord &, TInt)
IMPORT_C voidNotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange &)
IMPORT_C voidPanic(TPanic)
voidRegisterTzChangeNotifier(TRequestStatus &)
IMPORT_C voidSetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes)
IMPORT_C TIntSetHomeTime(const TTime &)
IMPORT_C voidSetTimeZoneL(CTzId &)
IMPORT_C voidSetUnknownZoneTimeL(const TTime &, const TInt)
IMPORT_C voidSetUnknownZoneTimeL(const TTime &, const TInt, TBool)
TBool StartCachingL()
IMPORT_C voidSwiObsBeginL()
IMPORT_C voidSwiObsEndL()
IMPORT_C voidSwiObsFileChangedL(TSWIObserverFilterIndex)
voidUpdateUserTimeZoneL(const CTzId &, const CTzRules &, const CTzUserNames &)
TVersion Version()
IMPORT_C void__dbgClearCacheL(TBool)
IMPORT_C TInt__dbgRequestAllocatedCellsL(TInt)
IMPORT_C void__dbgResetHeapL()
IMPORT_C void__dbgSetHeapFailL(RAllocator::TAllocFail, TInt)
Private Member Functions
TInt DoConnect()
TInt StartServer()
voiddoConvertL(const CTzId &, TTime &, TTzTimeReference)
voiddoConvertL(TTime &, TTzTimeReference)
Inherited Functions
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RSessionBase::CreateSession(RServer2,const TVersion &)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Open(TInt,TOwnerType)
RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Send(TInt)const
RSessionBase::Send(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt)const
RSessionBase::SendReceive(TInt,TRequestStatus &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSessionBase::SetReturnedHandle(TInt)
RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
RSessionBase::ShareAuto()
RSessionBase::ShareProtected()
Public Member Enumerations
enumTPanic {
EPanicServerNotFound = 1, EPanicServerDead, EPanicTimeZoneNameIdNotSet, EPanicRulesIndexOutofRange, EPanicTimeNotCoveredByRules, EPanicBadTimeZoneRules, EPanicUnsupportedTimeReference, EPanicUnsupportedTimeZoneNoId, EPanicNotificationRequestPending, EPanicInvalidArgument, EPanicBadSchema
}
enumTSWIObserverFilterIndex { EFilterTzPrivate = 0, EFilterResourceTimezonelocalization }
enumTTzAutoDSTUpdateModes { ETZAutoDSTUpdateOff = 0, ETZAutoDSTUpdateOn, ETZAutoDSTNotificationOnly }
enumTTzChanges { ETZDatabaseChanged = 1, ETZSystemTimeZoneChanged, ETZDSTRuleChanged, ETZAutomaticTimeUpdate, ETZLocalizationDataChanged }
Inherited Enumerations
RHandleBase:TAttributes
RSessionBase:TAttachMode
Private Attributes
CTzRuleHolder *iRulesHolder
Inherited Attributes
RHandleBase::iHandle

Constructor & Destructor Documentation

RTz()

IMPORT_CRTz()

~RTz()

IMPORT_C~RTz()

Member Functions Documentation

AutoUpdateSettingL()

IMPORT_C TIntAutoUpdateSettingL()

CancelRequestForNotice()

TInt CancelRequestForNotice()const

Close()

IMPORT_C voidClose()

Connect()

IMPORT_C TIntConnect()

ConvertToLocalTime(TTime &)

IMPORT_C TIntConvertToLocalTime(TTime &aTime)const

Parameters

TTime & aTime

ConvertToLocalTime(TTime &, const CTzId &)

IMPORT_C TIntConvertToLocalTime(TTime &aTime,
const CTzId &aZone
)const

Parameters

TTime & aTime
const CTzId & aZone

ConvertToUniversalTime(TTime &)

IMPORT_C TIntConvertToUniversalTime(TTime &aTime)const

Parameters

TTime & aTime

ConvertToUniversalTime(TTime &, const CTzId &)

IMPORT_C TIntConvertToUniversalTime(TTime &aTime,
const CTzId &aZone
)const

Parameters

TTime & aTime
const CTzId & aZone

CreateUserTimeZoneL(const CTzRules &, const CTzUserNames &)

CTzId *CreateUserTimeZoneL(const CTzRules &aTzUserRules,
const CTzUserNames &aTzUserNames
)

Parameters

const CTzRules & aTzUserRules
const CTzUserNames & aTzUserNames

CurrentCachedTzId()

TUint16 CurrentCachedTzId()

DeleteUserTimeZoneL(const CTzId &)

voidDeleteUserTimeZoneL(const CTzId &aTzId)

Parameters

const CTzId & aTzId

DoConnect()

TInt DoConnect()[private]

GetOffsetsForTimeZoneIdsL(const RArray< TInt > &, RArray< TInt > &)

IMPORT_C voidGetOffsetsForTimeZoneIdsL(const RArray< TInt > &aTzNumericIds,
RArray< TInt > &aOffsets
)const

Parameters

const RArray< TInt > & aTzNumericIds
RArray< TInt > & aOffsets

GetTimeZoneIdL()

IMPORT_C CTzId *GetTimeZoneIdL()const

This should not be used externally.

GetTimeZoneRulesL(const TTime &, const TTime &, TTzTimeReference)

IMPORT_C CTzRules *GetTimeZoneRulesL(const TTime &aStartTime,
const TTime &aEndTime,
TTzTimeReferenceaTimeRef
)const

Parameters

const TTime & aStartTime
const TTime & aEndTime
TTzTimeReference aTimeRef

GetTimeZoneRulesL(const CTzId &, const TTime &, const TTime &, TTzTimeReference)

IMPORT_C CTzRules *GetTimeZoneRulesL(const CTzId &aZone,
const TTime &aStartTime,
const TTime &aEndTime,
TTzTimeReferenceaTimeRef
)const

Parameters

const CTzId & aZone
const TTime & aStartTime
const TTime & aEndTime
TTzTimeReference aTimeRef

GetUserTimeZoneIdsL(RPointerArray< CTzId > &)

voidGetUserTimeZoneIdsL(RPointerArray< CTzId > &aTzIds)const

Parameters

RPointerArray< CTzId > & aTzIds

GetUserTimeZoneNamesL(const CTzId &)

CTzUserNames *GetUserTimeZoneNamesL(const CTzId &aTzId)const

Parameters

const CTzId & aTzId

IsDaylightSavingOnL(CTzId &)

IMPORT_C TBoolIsDaylightSavingOnL(CTzId &aZone)const

Parameters

CTzId & aZone

IsDaylightSavingOnL(CTzId &, const TTime &)

IMPORT_C TBoolIsDaylightSavingOnL(CTzId &aZone,
const TTime &aUTCTime
)const

Parameters

CTzId & aZone
const TTime & aUTCTime

LocalizationCloseDbL()

IMPORT_C voidLocalizationCloseDbL()

LocalizationDeleteCityL(const TDesC &, TInt)

IMPORT_C voidLocalizationDeleteCityL(const TDesC &aCityName,
TIntaCityTzId
)

Parameters

const TDesC & aCityName
TInt aCityTzId

LocalizationOpenDbL()

IMPORT_C voidLocalizationOpenDbL()

LocalizationReadCachedTimeZoneCityL(TInt)

IMPORT_C CTzLocalizedCityRecord *LocalizationReadCachedTimeZoneCityL(TIntaFrequentlyUsedZone)

Parameters

TInt aFrequentlyUsedZone

LocalizationReadCitiesInGroupL(RPointerArray< CTzLocalizedCityRecord > &, TUint8)

IMPORT_C voidLocalizationReadCitiesInGroupL(RPointerArray< CTzLocalizedCityRecord > &aCities,
TUint8aGroupId
)

Parameters

RPointerArray< CTzLocalizedCityRecord > & aCities
TUint8 aGroupId

LocalizationReadCitiesL(RPointerArray< CTzLocalizedCityRecord > &)

IMPORT_C voidLocalizationReadCitiesL(RPointerArray< CTzLocalizedCityRecord > &aCities)

Parameters

RPointerArray< CTzLocalizedCityRecord > & aCities

LocalizationReadCitiesL(RPointerArray< CTzLocalizedCityRecord > &, TInt)

IMPORT_C voidLocalizationReadCitiesL(RPointerArray< CTzLocalizedCityRecord > &aCities,
TIntaTimeZoneId
)

Parameters

RPointerArray< CTzLocalizedCityRecord > & aCities
TInt aTimeZoneId

LocalizationReadFrequentlyUsedZoneL(TInt)

IMPORT_C CTzLocalizedTimeZoneRecord *LocalizationReadFrequentlyUsedZoneL(TIntaFrequentlyUsedZone)

Parameters

TInt aFrequentlyUsedZone

LocalizationWriteAllFrequentlyUsedZonesL(const RPointerArray< CTzLocalizedTimeZoneRecord > &, const RPointerArray< CTzLocalizedCityRecord > &)

IMPORT_C voidLocalizationWriteAllFrequentlyUsedZonesL(const RPointerArray< CTzLocalizedTimeZoneRecord > &aTimeZones,
const RPointerArray< CTzLocalizedCityRecord > &aCities
)

Parameters

const RPointerArray< CTzLocalizedTimeZoneRecord > & aTimeZones
const RPointerArray< CTzLocalizedCityRecord > & aCities

LocalizationWriteCityL(const TDesC &, TInt, TUint8, TUint)

IMPORT_C voidLocalizationWriteCityL(const TDesC &aCityName,
TIntaCityTzId,
TUint8aCityGroupId,
TUintaCityTzResourceId
)

Parameters

const TDesC & aCityName
TInt aCityTzId
TUint8 aCityGroupId
TUint aCityTzResourceId

LocalizationWriteFrequentlyUsedZoneL(const CTzLocalizedTimeZoneRecord &, const CTzLocalizedCityRecord &, TInt)

IMPORT_C voidLocalizationWriteFrequentlyUsedZoneL(const CTzLocalizedTimeZoneRecord &aTimeZone,
const CTzLocalizedCityRecord &aCity,
TIntaFrequentlyUsedZone
)

Parameters

const CTzLocalizedTimeZoneRecord & aTimeZone
const CTzLocalizedCityRecord & aCity
TInt aFrequentlyUsedZone

NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange &)

IMPORT_C voidNotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange &aChange)const

Parameters

const NTzUpdate::TTimeZoneChange & aChange

Panic(TPanic)

IMPORT_C voidPanic(TPanicaPanic)[static]

This should not be used externally.

Parameters

TPanic aPanic

RegisterTzChangeNotifier(TRequestStatus &)

voidRegisterTzChangeNotifier(TRequestStatus &aStatus)const

Parameters

TRequestStatus & aStatus

SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes)

IMPORT_C voidSetAutoUpdateBehaviorL(TTzAutoDSTUpdateModesaUpdateEnabled)

Parameters

TTzAutoDSTUpdateModes aUpdateEnabled

SetHomeTime(const TTime &)

IMPORT_C TIntSetHomeTime(const TTime &aLocalTime)const

Parameters

const TTime & aLocalTime

SetTimeZoneL(CTzId &)

IMPORT_C voidSetTimeZoneL(CTzId &aZone)const

This should not be used externally.

Parameters

CTzId & aZone

SetUnknownZoneTimeL(const TTime &, const TInt)

IMPORT_C voidSetUnknownZoneTimeL(const TTime &aUTCTime,
const TIntaUTCOffset
)

Parameters

const TTime & aUTCTime
const TInt aUTCOffset

SetUnknownZoneTimeL(const TTime &, const TInt, TBool)

IMPORT_C voidSetUnknownZoneTimeL(const TTime &aUTCTime,
const TIntaUTCOffset,
TBoolaPersistInCenRep
)

Parameters

const TTime & aUTCTime
const TInt aUTCOffset
TBool aPersistInCenRep

StartCachingL()

TBool StartCachingL()

StartServer()

TInt StartServer()[private, static]

SwiObsBeginL()

IMPORT_C voidSwiObsBeginL()

SwiObsEndL()

IMPORT_C voidSwiObsEndL()

SwiObsFileChangedL(TSWIObserverFilterIndex)

IMPORT_C voidSwiObsFileChangedL(TSWIObserverFilterIndexaType)

Parameters

TSWIObserverFilterIndex aType

UpdateUserTimeZoneL(const CTzId &, const CTzRules &, const CTzUserNames &)

voidUpdateUserTimeZoneL(const CTzId &aTzId,
const CTzRules &aTzUserRules,
const CTzUserNames &aTzUserNames
)

Parameters

const CTzId & aTzId
const CTzRules & aTzUserRules
const CTzUserNames & aTzUserNames

Version()

TVersion Version()const

__dbgClearCacheL(TBool)

IMPORT_C void__dbgClearCacheL(TBoolaRestartCaching)

Parameters

TBool aRestartCaching

__dbgRequestAllocatedCellsL(TInt)

IMPORT_C TInt__dbgRequestAllocatedCellsL(TIntaHeapSizeInBytes)

Parameters

TInt aHeapSizeInBytes

__dbgResetHeapL()

IMPORT_C void__dbgResetHeapL()

__dbgSetHeapFailL(RAllocator::TAllocFail, TInt)

IMPORT_C void__dbgSetHeapFailL(RAllocator::TAllocFailaType,
TIntaRate
)

Parameters

RAllocator::TAllocFail aType
TInt aRate

doConvertL(const CTzId &, TTime &, TTzTimeReference)

voiddoConvertL(const CTzId &aZone,
TTime &aTime,
TTzTimeReferenceaTimerRef
)const [private]

Parameters

const CTzId & aZone
TTime & aTime
TTzTimeReference aTimerRef

doConvertL(TTime &, TTzTimeReference)

voiddoConvertL(TTime &aTime,
TTzTimeReferenceaTimerRef
)const [private]

Parameters

TTime & aTime
TTzTimeReference aTimerRef

Member Enumerations Documentation

Enum TPanic

Time zone server panic codes.

Enumerators

EPanicServerNotFound = 1

This panic indicates that the time zone server has not been found.

EPanicServerDead

This panic indicates that the server has died.

EPanicTimeZoneNameIdNotSet

This panic indicates that the time zone ID is not set.

EPanicRulesIndexOutofRange

This panic indicates that an out of range index was accessed.

EPanicTimeNotCoveredByRules

This panic indicates that there are no rules present for this time zone.

EPanicBadTimeZoneRules

This panic indicates that the time zone rules are unusable.

EPanicUnsupportedTimeReference

This panic indicates that an unsupported time reference has been accessed.

EPanicUnsupportedTimeZoneNoId

This panic indicates that the time zone ID is not supported.

EPanicNotificationRequestPending

This panic indicates that a request for notification is already pending from the client.

EPanicInvalidArgument

This panic indicates that an incorrect data has been sent to the server.

EPanicBadSchema

This panic indicates that a table in the user-defined time zone database has not conformed to the declared schema.

Enum TSWIObserverFilterIndex

The software install observer plugin can distinguish between changes to the resource files or the rules database. This enumeration indicates the filter index that is used for the resource files and rules database filters. This enum should not be used externally.

Enumerators

EFilterTzPrivate = 0

The index of the Tz private directory filter.

EFilterResourceTimezonelocalization

The index of the resources filter.

Enum TTzAutoDSTUpdateModes

Automatic DST update mode.

Enumerators

ETZAutoDSTUpdateOff = 0

No auto update notification when a DST event occurs.

ETZAutoDSTUpdateOn

Automatic time update will occur and the client app will be notified.

ETZAutoDSTNotificationOnly

Client app needs to confirm that the time should be updated whenever a DST event occurs.

Enum TTzChanges

Time zone server change events.

Enumerators

ETZDatabaseChanged = 1

Used for notifying that the timezone database has changed.

ETZSystemTimeZoneChanged

Used for notifying that the system timezone has changed.

ETZDSTRuleChanged

Used for notifying that the DST rule has changed.

ETZAutomaticTimeUpdate

Used for notifying that an automatic time update has taken place.

ETZLocalizationDataChanged

Used for notifying that a change in localization resources has taken place.

Member Data Documentation

CTzRuleHolder * iRulesHolder

CTzRuleHolder *iRulesHolder[private]