<?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>