1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-71DCEB48-8E8C-59A0-A99F-23245FF2DF13" xml:lang="en"><title>timezoneconversion: Time Zone Conversion Example</title><prolog><metadata><keywords/></metadata></prolog><conbody>

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

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

    15 time zone to convert it to are randomly chosen. This demonstrates

    16 that the time zone server can convert any time, past, present or future,

    17 for any time zone, as long as a rule exists for the conversion. Conversion

    18 rules are stored in a native Symbian database that is a compressed

    19 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

    20 space. </p> <p>The example then converts the current local time for

    21 the system time zone to the current local time for a different time

    22 zone. This is a two stage process. First, the local time is converted

    23 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

    24 converting between local and UTC times for the current system time

    25 zone, there is no need to specify the time zone ID. Then UTC is converted

    26 to local time for the other time zone. Before the example terminates,

    27 the connection to the server is closed. </p> <p>No special capabilities

    28 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,

    29 (for instance Australia/Sydney), or as a number. Numeric time zone

    30 IDs are assigned by the phone manufacturer, so can vary from phone

    31 to phone. </p> <p>For efficiency, the time zone server caches a copy

    32 of a range of conversion rules for the current time zone. These cached

    33 rules are <i>actualised</i>, meaning they have been expanded from

    34 the encoded compact format as stored in the database, so are quicker

    35 to access. </p> <p>Class <xref href="GUID-37A4A4ED-FFF8-3C98-B028-EA1947EA7BEF.dita"><apiname>CTzConverter</apiname></xref>, which is

    36 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

    37 specific time zone (either the time zone specified in the conversion

    38 function, or the system time zone), on the client side, so avoiding

    39 the need for an an IPC call for each conversion. <codeph>CTzConverter</codeph> is more efficient than <codeph>RTz</codeph> when doing multiple

    40 conversions for a single time zone. </p> </section>

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

    42 an executable called<filepath> TZExample.exe</filepath> in the standard

    43 location (<filepath>\epoc32\release\winscw\&lt;build_variant&gt;</filepath> for CodeWarrior). After launching the executable, depending on the

    44 emulator you are using, you may need to task away from the app launcher/shell

    45 screen to view the console.</p></section>

    46 <section id="GUID-2E27B7FB-A188-450C-8BA3-485FFB63F66C"><title>Class

    47 Summary</title><ul>

    48 <li><p><xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita"><apiname>RTz</apiname></xref></p></li>

    49 <li><p><xref href="GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE.dita"><apiname>CTzId</apiname></xref></p></li>

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

    51 </ul></section>

    52 </conbody></concept>