timezoneconversion: Time Zone Conversion Example

Description

This example code first connects to the time zone server (class RTz). Then it uses RTz::ConvertToLocalTime() to convert a UTC time to local time. The time to convert and the +time zone to convert it to are randomly chosen. This demonstrates +that the time zone server can convert any time, past, present or future, +for any time zone, as long as a rule exists for the conversion. Conversion +rules are stored in a native Symbian database that is a compressed +form of the Olson time zone database (http://www.twinsun.com/tz/tz-link.htm). The database can be configured by phone manufacturers to save +space.

The example then converts the current local time for +the system time zone to the current local time for a different time +zone. This is a two stage process. First, the local time is converted +to UTC using RTz::ConvertToUniversalTime(). When +converting between local and UTC times for the current system time +zone, there is no need to specify the time zone ID. Then UTC is converted +to local time for the other time zone. Before the example terminates, +the connection to the server is closed.

No special capabilities +are needed to do time zone conversion.

Class CTzId identifies a time zone. It stores the identifier either as text, +(for instance Australia/Sydney), or as a number. Numeric time zone +IDs are assigned by the phone manufacturer, so can vary from phone +to phone.

For efficiency, the time zone server caches a copy +of a range of conversion rules for the current time zone. These cached +rules are actualised, meaning they have been expanded from +the encoded compact format as stored in the database, so are quicker +to access.

Class CTzConverter, which is +not used in this example, provides an alternative conversion API to RTz. It caches 5 years' worth of conversion rules for a +specific time zone (either the time zone specified in the conversion +function, or the system time zone), on the client side, so avoiding +the need for an an IPC call for each conversion. CTzConverter is more efficient than RTz when doing multiple +conversions for a single time zone.