<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-71DCEB48-8E8C-59A0-A99F-23245FF2DF13" xml:lang="en"><title>timezoneconversion:
Time Zone Conversion Example</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section><title>Download</title> <p>Click on the following link to download
the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-c9019536-b967-4421-8221-150afb121307.zip" scope="external">TZExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-c9019536-b967-4421-8221-150afb121307.html" scope="peer">browse</xref> to view the example code. </p> </section>
<section><title>Description</title> <p>This example code first connects to
the time zone server (class <xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita"><apiname>RTz</apiname></xref>). Then it uses <xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita#GUID-052221AD-916E-3E47-9510-AC0495A19A70/GUID-A7D33D36-8AA5-3775-B4B8-36C30EF88DB0"><apiname>RTz::ConvertToLocalTime()</apiname></xref> 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
(<xref href="http://www.twinsun.com/tz/tz-link.htm" scope="external">http://www.twinsun.com/tz/tz-link.htm</xref>).
The database can be configured by phone manufacturers to save space. </p> <p>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 <xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita#GUID-052221AD-916E-3E47-9510-AC0495A19A70/GUID-645162AA-631E-3125-A002-82EB8D91DB08"><apiname>RTz::ConvertToUniversalTime()</apiname></xref>.
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. </p> <p>No special capabilities are needed to do
time zone conversion. </p> <p>Class <xref href="GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE.dita"><apiname>CTzId</apiname></xref> 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. </p> <p>For efficiency, the time zone server
caches a copy of a range of conversion rules for the current time zone. These
cached rules are <i>actualised</i>, meaning they have been expanded from the
encoded compact format as stored in the database, so are quicker to access. </p> <p>Class <xref href="GUID-37A4A4ED-FFF8-3C98-B028-EA1947EA7BEF.dita"><apiname>CTzConverter</apiname></xref>,
which is not used in this example, provides an alternative conversion API
to <xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita"><apiname>RTz</apiname></xref>. 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. <codeph>CTzConverter</codeph> is more efficient
than <codeph>RTz</codeph> when doing multiple conversions for a single time
zone. </p> </section>
<section><title>Usage</title><p> This is a console application, so does not
have a GUI. It builds an executable called<filepath> TZExample.exe</filepath> in
the standard location (<filepath>\epoc32\release\winscw\&lt;build_variant&gt;</filepath> 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.</p></section>
<section><title>Class Summary</title><p> <xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita"><apiname>RTz</apiname></xref></p><p>  <xref href="GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE.dita"><apiname>CTzId</apiname></xref> </p><p> <xref href="GUID-A2D3BA72-9B27-3BFF-950A-D7E3B2004821.dita"><apiname>TTime</apiname></xref> </p></section>
</conbody></concept>