»
Symbian OS v9.3 »
Symbian OS reference »
C++ component reference »
Application Services TZ »
RTz
Location:
tz.h
Link against: tzclient.lib
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() 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 regardless of whether the local time value exists or is double.
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
Derivation
RSessionBase
- Client-side handle to a session with a server
RTz
- The client interface to the time zone server
Members
Defined in RTz
:
AutoUpdateSettingL()
, Close()
, Connect()
, ConvertToLocalTime()
, ConvertToLocalTime()
, ConvertToUniversalTime()
, ConvertToUniversalTime()
, EPanicBadTimeZoneRules
, EPanicInvalidArgument
, EPanicNotificationRequestPending
, EPanicRulesIndexOutofRange
, EPanicServerDead
, EPanicServerNotFound
, EPanicTimeNotCoveredByRules
, EPanicTimeZoneNameIdNotSet
, EPanicUnsupportedTimeReference
, EPanicUnsupportedTimeZoneNoId
, ETZAutoDSTNotificationOnly
, ETZAutoDSTUpdateOff
, ETZAutoDSTUpdateOn
, ETZAutomaticTimeUpdate
, ETZDSTRuleChanged
, ETZDatabaseChanged
, ETZSystemTimeZoneChanged
, GetOffsetsForTimeZoneIdsL()
, GetTimeZoneRulesL()
, GetTimeZoneRulesL()
, IsDaylightSavingOnL()
, NotifyHomeTimeZoneChangedL()
, RTz()
, SetAutoUpdateBehaviorL()
, SetHomeTime()
, SetUnknownZoneTimeL()
, TPanic
, TTzAutoDSTUpdateModes
, TTzChanges
, ~RTz()
Inherited from RHandleBase
:
Attributes()
,
Duplicate()
,
FullName()
,
Handle()
,
HandleInfo()
,
Name()
,
SetHandle()
,
SetHandleNC()
,
iHandle
Inherited from RSessionBase
:
CreateSession()
,
EAutoAttach
,
EExplicitAttach
,
Open()
,
Send()
,
SendReceive()
,
SetReturnedHandle()
,
ShareAuto()
,
ShareProtected()
,
TAttachMode
See also
See also:
Construction and destruction
IMPORT_C ~RTz();
Description
Destructor. Calls 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.
|
|
GetOffsetsForTimeZoneIdsL()
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
IMPORT_C void SetAutoUpdateBehaviorL(TTzAutoDSTUpdateModes aUpdateEnabled);
Description
Sets the configuration of the UTC Offset auto-update functionality.
Parameters
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 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.
|
|
NotifyHomeTimeZoneChangedL()
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 .
Parameters
const TTime &aUTCTime |
Universal Time to set the device time to.
|
const TInt aUTCOffset |
|
|
Enum TTzAutoDSTUpdateModes
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.