<?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 id="GUID-340A1745-6C2C-41E5-A637-346F32F11A21"><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 id="GUID-A36EB85A-A039-4396-BF31-2780D57E85F7"><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 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 id="GUID-A56CA8E4-4794-41A4-9C12-F5867525DD8C"><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 id="GUID-2E27B7FB-A188-450C-8BA3-485FFB63F66C"><title>Class
Summary</title><ul>
<li><p><xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita"><apiname>RTz</apiname></xref></p></li>
<li><p><xref href="GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE.dita"><apiname>CTzId</apiname></xref></p></li>
<li><p><xref href="GUID-BE7D196E-357B-36BE-80BB-CCBBE00DFA90.dita#GUID-BE7D196E-357B-36BE-80BB-CCBBE00DFA90/GUID-C58E6A33-D690-3071-A93D-A2509D989AE4"><apiname>ESock::TTime</apiname></xref></p></li>
</ul></section>
</conbody></concept>