Class RTz

class RTz : public RSessionBase;

Description

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(TTimeIntervalSeconds) and User::SetUTCTimeAndOffset(const TTime &,TTimeIntervalSeconds). 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

Derivation

• RHandleBase - A handle to an object.

• RSessionBase - Client-side handle to a session with a server.

• RTz - The client interface to the time zone server.

Members

Defined in RTz:

• AutoUpdateSettingL()Retrieves the daylight saving auto-update functionality.
• Close()Closes the connection to the time zone server.
• Connect()Connects to the time zone server, attempting to start it if necessary.
• ConvertToLocalTime(TTime &)constConverts a time from UTC to local (wall-clock) time for the current system time ...
• ConvertToLocalTime(TTime &,const CTzId &)constConverts a time from UTC to the local (wall-clock) time for the specified time z...
• ConvertToUniversalTime(TTime &)constConverts a local (wall-clock) time for the current system time zone, to UTC. If ...
• ConvertToUniversalTime(TTime &,const CTzId &)constConverts a local (wall-clock) time for the specified time zone, to UTC.
• EPanicBadTimeZoneRulesThis panic indicates that the time zone rules are unusable.
• EPanicInvalidArgumentThis panic indicates that an incorrect data has been sent to the server.
• EPanicNotificationRequestPendingThis panic indicates that a request for notification is already pending from the...
• EPanicRulesIndexOutofRangeThis panic indicates that an out of range index was accessed.
• EPanicServerDeadThis panic indicates that the server has died.
• EPanicServerNotFoundThis panic indicates that the time zone server has not been found.
• EPanicTimeNotCoveredByRulesThis panic indicates that there are no rules present for this time zone.
• EPanicTimeZoneNameIdNotSetThis panic indicates that the time zone ID is not set.
• EPanicUnsupportedTimeReferenceThis panic indicates that an unsupported time reference has been accessed.
• EPanicUnsupportedTimeZoneNoIdThis panic indicates that the time zone ID is not supported.
• ETZAutoDSTNotificationOnlyClient app needs to confirm that the time should be updated whenever a DST event...
• ETZAutoDSTUpdateOffNo auto update notification when a DST event occurs.
• ETZAutoDSTUpdateOnAutomatic time update will occur and the client app will be notified.
• ETZAutomaticTimeUpdateUsed for notifying that an automatic time update has taken place.
• ETZDSTRuleChangedUsed for notifying that the DST rule has changed.
• ETZDatabaseChangedUsed for notifying that the timezone database has changed.
• ETZSystemTimeZoneChangedUsed for notifying that the system timezone database has changed.
• GetOffsetsForTimeZoneIdsL(const RArray< TInt > &,RArray< TInt > &)constRetrieves the UTC offset for an array of numeric time zone ids. The offset is wr...
• GetTimeZoneRulesL(const CTzId &,const TTime &,const TTime &,TTzTimeReference)constRetrieves the time zone rules for a specified time zone.
• GetTimeZoneRulesL(const TTime &,const TTime &,TTzTimeReference)constRetrieves the time zone rules for the current home time zone.
• IsDaylightSavingOnL(CTzId &)constTells if daylight savings are applied at the specified zone at the current time
• IsDaylightSavingOnL(CTzId &,const TTime &)constTells if daylight savings are applied at the specified zone at a specified time
• RTz()Constructor.
• SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes)Sets the configuration of the UTC Offset auto-update functionality.
• SetHomeTime(const TTime &)constSets the system time to the given local time. Note that the standard Tz algorith...
• SetUnknownZoneTimeL(const TTime &,const TInt)Sets the UTC time and the wall-clock offset for a zone not defined in the Timezo...
• SetUnknownZoneTimeL(const TTime &,const TInt,TBool)Sets the UTC time and the wall-clock offset for a zone not defined in the Timezo...
• TPanic
• TTzAutoDSTUpdateModesThese enumerators are to describe different modes of the automatic DST event han...
• TTzChanges
• ~RTz()Destructor. Calls RTz::Close().

Inherited from RHandleBase:

• Attributes()const
• BTraceId()constReturns a unique object identifier for use with BTrace
• Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
• FullName()constGets the full name of the handle.
• FullName(TDes &)constGets the full name of the handle.
• Handle()constRetrieves the handle-number of the object associated with this handle.
• HandleInfo(THandleInfo *)Gets information about the handle.
• Name()constGets the name of the handle.
• Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.
• RHandleBase(TInt)Copy constructor.
• SetHandle(TInt)Sets the handle-number of this handle to the specified value.
• SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...
• iHandle

Inherited from RSessionBase:

• CreateSession(RServer2,const TVersion &)Creates a session with a server, specifying no message slots.
• CreateSession(RServer2,const TVersion &,TInt)Creates a session with a server.
• CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)Creates a session with a server.
• CreateSession(const TDesC &,const TVersion &)Creates a session with a server, specifying no message slots.
• CreateSession(const TDesC &,const TVersion &,TInt)Creates a session with a server.
• CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)Creates a session with a server.
• CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
• EAutoAttach
• EExplicitAttach
• Open(RMessagePtr2,TInt,TOwnerType)Opens a handle to a session using a handle number sent by a client to a server.
• Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)Opens a handle to a session using a handle number sent by a client to a server, ...
• Open(TInt,TOwnerType)Opens a handle to a session using a handle number passed as an environment data ...
• Open(TInt,const TSecurityPolicy &,TOwnerType)Opens a handle to a session using a handle number passed as an environment data ...
• Send(TInt)constIssues a blind request to the server with the specified function number, but wit...
• Send(TInt,const TIpcArgs &)constIssues a blind request to the server with the specified function number, and arg...
• SendReceive(TInt)constIssues a synchronous request to the server with the specified function number, b...
• SendReceive(TInt,TRequestStatus &)constIssues an asynchronous request to the server with the specified function number,...
• SendReceive(TInt,const TIpcArgs &)constIssues a synchronous request to the server with the specified function number an...
• SendReceive(TInt,const TIpcArgs &,TRequestStatus &)constIssues an asynchronous request to the server with the specified function number ...
• SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.
• SetReturnedHandle(TInt,RHandleBase &)
• SetReturnedHandle(TInt,const TSecurityPolicy &)Sets the handle-number of this session handle to the specified value after valid...
• ShareAuto()Creates a session that can be shared by other threads in the current process.
• ShareProtected()Creates a session handle that can be be passed via IPC to another process as wel...
• TAttachModeIndicates whether or not threads in the process are automatically attached to th...

Related Topics

 » Symbian OS v9.4 » Examples » Application Services example code » timezoneconversion: Using time zone conversion

• timezoneconversion: Using time zone conversion

IMPORT_C ~RTz();

Description

Destructor. Calls RTz::Close().

IMPORT_C RTz();

Description

Constructor.

IMPORT_C void Close();

Description

Closes the connection to the time zone server.

IMPORT_C TInt Connect();

Description

Connects to the time zone server, attempting to start it if necessary.

Return value

TInt KErrNone if successful, otherwise a system error code.

Panic codes

TzServer 1 The attempt to connect to the server failed with an error code other than KErrNotFound.

IMPORT_C TInt ConvertToLocalTime(TTime &aTime) const;

Description

Converts a time from UTC to local (wall-clock) time for the current system time zone. If caching has been enabled by the CTzConverter class, then the conversion will be done using the cache instead of issuing a request to the server.

Parameters

TTime &aTime On entry, contains the UTC time to be converted, and the converted value on exit.

Return value

TInt KErrNone if successful, otherwise another system error code.

IMPORT_C TInt ConvertToLocalTime(TTime &aTime, const CTzId &aZone) const;

Description

Converts a time from UTC to the local (wall-clock) time for the specified time zone.

Parameters

TTime &aTime On entry, contains the UTC time to be converted, and the converted value on exit. const CTzId &aZone Time zone ID.

Return value

TInt KErrNone if successful, otherwise another system error code.

IMPORT_C TInt ConvertToUniversalTime(TTime &aTime) const;

Description

Converts a local (wall-clock) time for the current system time zone, to UTC. If caching has been enabled by the CTzConverter class, then the conversion will be done using the cache instead of issuing a request to the server.

Parameters

TTime &aTime On entry, contains the local time to be converted, and the converted value on exit.

Return value

TInt KErrNone if successful, otherwise another system error code.

IMPORT_C TInt ConvertToUniversalTime(TTime &aTime, const CTzId &aZone) const;

Description

Converts a local (wall-clock) time for the specified time zone, to UTC.

Parameters

TTime &aTime On entry, contains the local time to be converted, and the converted value on exit. const CTzId &aZone The time zone ID of interest.

Return value

TInt KErrNone if successful, otherwise another system error code.

IMPORT_C void GetOffsetsForTimeZoneIdsL(const RArray< TInt > &aTzNumericIds, RArray< TInt > &aOffsets) const;

Description

Retrieves the UTC offset for an array of numeric time zone ids. The offset is written back into aOffsets.

Parameters

const RArray< TInt > &aTzNumericIds An array of numeric time zone IDs for which the current UTC offset is required. RArray< TInt > &aOffsets An array that, on return, will contain the UTC offsets corresponding to the the time zone IDs in aTzNumericIds.

IMPORT_C TInt AutoUpdateSettingL();

Description

Retrieves the daylight saving auto-update functionality.

Return value

TInt An error code. KErrNone is expected unless there is an error while trying to retrieve the auto-update setting.

IMPORT_C void SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes aUpdateEnabled);

Description

Sets the configuration of the UTC Offset auto-update functionality.

Parameters

RTz::TTzAutoDSTUpdateModes aUpdateEnabled If set to RTz::ETZAutoDSTUpdateOn then the UTC Offset is automatically updated for changes to Daylight Savings Time. If set to RTz::ETZAutoDSTUpdateOff then auto-update is disabled. The RTz::ETZAutoDSTNotificationOnly - Means that the client app needs to confirm that the time should be updated whenever a DST event occurs.

Capability:

WriteDeviceData

IMPORT_C TInt SetHomeTime(const TTime &aLocalTime) const;

Description

Sets the system time to the given local time. Note that the standard Tz algorithm is used - in the case of an ambiguous time the first occurance of the given local wall-clock time is chosen.

An example of an ambiguous time: 01:30 wall-clock time on 31/10/2004 in the UK could map to either 01:30 BST (00:30 GMT) or 01:30 GMT, as the clocks would go back at 02:00 BST (01:00 GMT))

Parameters

const TTime &aLocalTime The time to set in wall-clock time.

Return value

TInt An error code. KErrNone is expected unless there is an error in converting the given local time to UTC.

IMPORT_C TBool IsDaylightSavingOnL(CTzId &aZone) const;

Description

Tells if daylight savings are applied at the specified zone at the current time

Parameters

CTzId &aZone The time zone ID.

Return value

TBool ETrue if the Daylight Saving is on, i.e. if it is summertime.

IMPORT_C TBool IsDaylightSavingOnL(CTzId &aZone, const TTime &aUTCTime) const;

Description

Tells if daylight savings are applied at the specified zone at a specified time

Parameters

CTzId &aZone The time zone ID. const TTime &aUTCTime The UTC time at which DST settings are required.

Return value

TBool ETrue if the Daylight Saving is on, i.e. if it is summertime.

IMPORT_C CTzRules* GetTimeZoneRulesL(const TTime &aStartTime, const TTime &aEndTime, TTzTimeReference aTimeRef) const;

Description

Retrieves the time zone rules for the current home time zone.

Parameters

const TTime &aStartTime The start date to generate the time zone rules from. const TTime &aEndTime The end date to generate the time zone rules to. TTzTimeReference aTimeRef Whether to generate the rules relative to UTC or local time. Use ETzUtcTimeReference to generate from UTC, ETzWallTimeReference to generate from local time.

Return value

CTzRules * Pointer to the time zone rules generated.

IMPORT_C CTzRules* GetTimeZoneRulesL(const CTzId &aZone, const TTime &aStartTime, const TTime &aEndTime, TTzTimeReference aTimeRef) const;

Description

Retrieves the time zone rules for a specified time zone.

Parameters

const CTzId &aZone The time zone to generate the rules for. const TTime &aStartTime The start date to generate the time zone rules from. const TTime &aEndTime The end date to generate the time zone rules to. TTzTimeReference aTimeRef Whether to generate the rules relative to UTC or local time. Use ETzUtcTimeReference to generate from UTC, ETzWallTimeReference to generate from local time.

Return value

CTzRules * Pointer to the time zone rules generated.

IMPORT_C void NotifyHomeTimeZoneChangedL(const NTzUpdate::TTimeZoneChange &aChange) const;

Description

Publish notification that the home time zone (as defined in CTzLocalizer) has been changed. This function should only be called from TimeZoneLocalization.

Parameters

const NTzUpdate::TTimeZoneChange &aChange

IMPORT_C void SetUnknownZoneTimeL(const TTime &aUTCTime, const TInt aUTCOffset);

Description

Sets the UTC time and the wall-clock offset for a zone not defined in the Timezone Database.

This is useful when the client wants to specify the UTC time and the wall-clock offset explicitly rather than using time zones. This function should be used instead of User::SetUTCOffset(TTimeIntervalSeconds) and User::SetUTCTimeAndOffset(const TTime &,TTimeIntervalSeconds).

If this function has been called the time zone server will use the value returned by User::UTCOffset() as the offset value when doing time conversions. Calling User::SetUTCOffset(TTimeIntervalSeconds) may therefore cause unexpected results.

The fact that the time zone has been set to the unknown time zone is not persisted across time zone server reboots. So it may be necessary to call this function each time the time zone server is started. If persistence across reboots is desired the overload RTz::SetUnknownZoneTimeL(const TTime &,const TInt,TBool) should be used.

Parameters

const TTime &aUTCTime Universal Time to set the device time to. const TInt aUTCOffset Offset (in minutes) in use in the time zone.

IMPORT_C void SetUnknownZoneTimeL(const TTime &aUTCTime, const TInt aUTCOffset, TBool aPersistInCenRep);

Description

Sets the UTC time and the wall-clock offset for a zone not defined in the Timezone Database.

This is useful when the client wants to specify the UTC time and the wall-clock offset explicitly rather than using time zones. This function should be used instead of User::SetUTCOffset(TTimeIntervalSeconds) and User::SetUTCTimeAndOffset(const TTime &,TTimeIntervalSeconds).

If this function has been called the time zone server will use the value returned by User::UTCOffset() as the offset value when doing time conversions. Calling User::SetUTCOffset(TTimeIntervalSeconds) may therefore cause unexpected results.

The fact that the time zone has been set to the unknown time zone is persisted across time zone server reboots only if the aPersistInCenRep argument is set to ETrue. The desired offset however is never persisted (the value returned by User::UTCOffset() is used). So it may be necessary to call this function each time the time zone server is started.

Parameters

const TTime &aUTCTime Universal Time to set the device time to. const TInt aUTCOffset Offset (in minutes) in use in the time zone. TBool aPersistInCenRep If ETrue the unknown time zone is persisted across reboots else it is not.

TTzAutoDSTUpdateModes

Description

These enumerators are to describe different modes of the automatic DST event handling.

These are used both as arguments for the API SetAutoUpdateBehaviorL, and as notifications for the publish and subscribe.

ETZAutoDSTUpdateOff 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.

TTzChanges

Description

ETZDatabaseChanged Used for notifying that the timezone database has changed. ETZSystemTimeZoneChanged Used for notifying that the system timezone database has changed. ETZDSTRuleChanged Used for notifying that the DST rule has changed. ETZAutomaticTimeUpdate Used for notifying that an automatic time update has taken place.

TPanic

Description

EPanicServerNotFound 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.