timezoneconversion: Using time zone conversion

Found in examples\AppServices\timezoneconversion\.

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

This is a console application, so does not have a GUI. It builds an executable called TZExample.exe in the standard location (\epoc32\release\winscw\<build_variant> for CodeWarrior). After launching the executable, depending on the emulator you are using, you may need to task away from the app launcher/shell screen to view the console. Alternatively, adding the string textshell to the emulator configuration file epoc.ini causes the emulator to start in text mode.