|
||
Each time zone is uniquely identified by its time zone ID which is a
numeric reference or a name. The CTzId
class encapsulates
a time zone identifier. A time zone ID is created using the
CTzId::NewL()
factory method, for example:
_LIT8(KAsiaHongKong,"Asia/Hong_Kong"); //A valid time zone name
CTzId* zoneId = CTzId::NewL(KAsiaHongKong);
The time zone’s numeric ID or name can be retrieved using
CTzId::TimeZoneNumericID()
or
CTzId::TimeZoneNameID()
respectively.
operator==()
and operator!=()
can be used to
check if the time zone ID matches or differs from another time zone ID.
You can convert between times expressed in UTC and local time using
either the CTzConverter
or RTz
class.
CTzConverter
does the conversion on the client
side by caching rules which it gets from the time zone server. This class
should be used for conversion between UTC and local time for the system time
zone, for performance reasons.
If the conversion involves foreign time zones, the
RTz
class can be used instead.
The following types of time conversion are possible:
UTC to local time in any time zone
UTC to local time in the system time zone
Local time in the system time zone to UTC
Local time in any time zone to UTC.
Each of these is discussed in the sections below.
The following code fragment converts a randomly chosen UTC time to local time for London.
_LIT8(KEuropeLondon,"Europe/London");
// Create a pointer to the time zone id.
// This is the time zone for the local time to which you wish to convert.
CTzId* myZoneId = CTzId::NewL(KEuropeLondon);
CleanupStack::PushL(myZoneId);
// Create a client interface object to the time zone server
RTz myTZoneServer;
// Connect to the time zone server, leaves if fails to connect
User::LeaveIfError(myTZoneServer.Connect());
CleanupClosePushL(myTZoneServer);
// Create a converter object.
CTzConverter* myConverter = CTzConverter::NewL(myTZoneServer);
CleanupStack::PushL(myConverter);
_LIT8(KMyTime,"20050328:185600.00"); // UTC time to convert (28 March 2005 18:56 hrs).
TTime myTime(KMyTime); // Create the time as a TTime object
// Convert UTC to local time in Europe/London time zone.
myConverter->ConvertToLocalTime(myTime, *myZoneId);
// myTime is updated to hold the local time value.
// Clean up
CleanupStack::PopAndDestroy(3);// causes myTZoneServer.Close() to be called
To convert from UTC to the local time of the system time zone, use
CTzConverter::ConvertToLocalTime()
, without specifying a time zone
ID to convert to:
TInt errCode = myConverter->ConvertToLocalTime(myTime);
To convert the local time in the system time zone to UTC, use
CTzConverter::ConvertToUniversalTime()
, without specifying the
time zone to convert from:
TInt errCode = myConverter->ConvertToUniversalTime(myTime);
To convert the local time of a non-system time zone to UTC, use
CTzConverter::ConvertToUniversalTime()
, specifying the time zone
to convert from:
TInt errCode = myConverter->ConvertToUniversalTime(myTime, myZoneId);
These time conversions internally do the following:
fetch a number of 'actualised' rules applicable to the years around the supplied time and zone, where an 'actualised' rule defines a single and specific time of year when local time changes. It is derived from the encoded day rule defined in the Olson’s tz database RULE.
cache these rules for subsequent use
identify which rule immediately precedes the time supplied
apply the appropriate offsets defined by this rule.
RTz::SetHomeTime()
sets the local time in the
system time zone:
_LIT8(KMyTime, "20050105:103000.00"); // Local time to set (5th January 2005 10:30 hrs).
TTime myTime(KMyTime); //Create the time as a TTime object
TInt errCode = myTZoneServer.SetHomeTime(myTime);
The WriteDeviceData
capability is needed to set the system
time.
Whenever DST begins or ends, the UTC offset needs to be updated
accordingly. This can be done automatically by calling
RTz::SetAutoUpdateBehaviorL()
. This function takes a value
from the TTzAutoDSTUpdateModes
enum. When set to
TTzAutoDSTUpdateModes::ETZAutoDSTUpdateOn
, the UTC offset
is automatically updated for changes to DST.