--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-71DCEB48-8E8C-59A0-A99F-23245FF2DF13.dita Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,53 @@
+<?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\<build_variant></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>
\ No newline at end of file