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-DF4D7DFF-ECA9-40CF-9F3B-4BBC3F8162E4" xml:lang="en"><title>Converting

    13 between UTC and local time</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-9CB60EE8-93DA-473B-AF76-5DBFAEED0E09"><title>Time zone ID</title> 

    15      <p>Each time zone is uniquely identified by its time zone ID which is

    16 a numeric reference or a name. The <codeph>CTzId</codeph> class encapsulates

    17 a time zone identifier. A time zone ID is created using the <xref href="GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE.dita#GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE/GUID-72A203C7-593F-34E3-9D7A-646D8A1E85D3"><apiname>CTzId::NewL()</apiname></xref> factory

    18 method, for example: </p><codeblock xml:space="preserve">_LIT8( KAsiaHongKong,"Asia/Hong_Kong" ); //A valid time zone name

    19 CTzId* zoneId = CTzId::NewL( KAsiaHongKong );</codeblock><p>The time zone’s

    20 numeric ID or name can be retrieved using <xref href="GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE.dita#GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE/GUID-5165FA78-3EB8-3099-BA0A-EA727BF75AED"><apiname>CTzId::TimeZoneNumericID()</apiname></xref> or <xref href="GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE.dita#GUID-0B5453C5-76A2-31B2-A32C-2CDC1F3367CE/GUID-A9F74527-2885-326E-9516-FDE2AE8A0425"><apiname>CTzId::TimeZoneNameID()</apiname></xref> respectively.

    21  </p><p><codeph>operator==()</codeph> and <codeph>operator!=()</codeph> can

    22 be used to check if the time zone ID matches or differs from another time

    23 zone ID.  </p></section>

    24 <section id="GUID-4A2ED95F-8697-47FF-A89A-0871449ADFEE"><title>Converting

    25 between UTC and local time</title><p>You can convert between times expressed

    26 in UTC and local time using either the <xref href="GUID-37A4A4ED-FFF8-3C98-B028-EA1947EA7BEF.dita"><apiname>CTzConverter</apiname></xref> or <codeph>RTz</codeph> class.

    27  </p><p> <xref href="GUID-37A4A4ED-FFF8-3C98-B028-EA1947EA7BEF.dita"><apiname>CTzConverter</apiname></xref> does the conversion on the client

    28 side by caching rules which it gets from the time zone server. This class

    29 should be used for conversion between UTC and local time for the system time

    30 zone, for performance reasons.   </p><p>If the conversion involves foreign

    31 time zones, the <codeph>RTz</codeph> class can be used instead.  </p><p> The

    32 following types of time conversion are possible:  </p><ul>

    33 <li id="GUID-0B4E9E64-99DB-4BF2-A0FF-E62508F8E54A"><p><xref href="GUID-237E0861-EC1B-41DA-BDB0-1DEB50620CC8.dita">UTC

    34 to local time in any time zone</xref></p></li>

    35 <li id="GUID-B90DEC70-F232-43CD-AC8B-6D3D64090E2A"><p><xref href="GUID-F2487AEE-966E-472E-9162-E0400C9A8234.dita">UTC

    36 to local time in the system time zone</xref></p></li>

    37 <li id="GUID-2CC49848-516F-4345-91A4-8DE97566E297"><p><xref href="GUID-7A16B6E1-16F7-41EC-ABCC-4A2BEBD66FFF.dita">Local

    38 time in the system time zone to UTC</xref> </p></li>

    39 <li id="GUID-474CB987-56DB-4596-AC9F-7333A8619A0F"><p><xref href="GUID-043A9408-1A97-4122-9364-965ECC08B40F.dita">Local

    40 time in any time zone to UTC</xref></p></li>

    41 </ul></section>

    42 <section id="GUID-9B7F2465-48B5-40E5-A459-FFE839DEF58C"><title>Setting the

    43 local time </title><p><xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita#GUID-052221AD-916E-3E47-9510-AC0495A19A70/GUID-ED5486E0-392F-37C5-992F-16421560C49B"><apiname>RTz::SetHomeTime()</apiname></xref> sets the local

    44 time in the system time zone:</p><codeblock xml:space="preserve">_LIT8( KMyTime, "20050105:103000.00" ); // Local time to set (5th January 2005 10:30 hrs).

    45 TTime myTime( KMyTime ); //Create the time as a TTime object

    46 TInt errCode = myTZoneServer.SetHomeTime( myTime );</codeblock><p>The <codeph>WriteDeviceData</codeph> capability

    47 is needed to set the system time.  </p></section>

    48 <section id="GUID-12459F4B-EEF2-44DB-BB85-A180DA3FBD47"><title>Automatic UTC

    49 offset</title><p>Whenever DST begins or ends, the UTC offset needs to be updated

    50 accordingly. This can be done automatically by calling <xref href="GUID-052221AD-916E-3E47-9510-AC0495A19A70.dita#GUID-052221AD-916E-3E47-9510-AC0495A19A70/GUID-7CF53489-5FF4-3665-8660-263433D8F090"><apiname>RTz::SetAutoUpdateBehaviorL()</apiname></xref>.

    51 This function takes a value from the <codeph>TTzAutoDSTUpdateModes</codeph> enum.

    52 When set to <xref href="GUID-C94A18B2-5652-3F2C-8D87-1B59A37E6122.dita#GUID-C94A18B2-5652-3F2C-8D87-1B59A37E6122/GUID-0B745B98-814D-3157-9290-557339119877"><apiname>TTzAutoDSTUpdateModes::ETZAutoDSTUpdateOn()</apiname></xref>,

    53 the UTC offset is automatically updated for changes to DST. </p></section>

    54 <section id="GUID-BF084ED0-7E7C-4A5B-8BEF-9F809F1F1DC0"><title>See also</title><p><xref href="GUID-A0E21681-F1EF-4E79-965A-040AC7D72A01.dita">Time zone conversion overview</xref></p><p><xref href="GUID-71DCEB48-8E8C-59A0-A99F-23245FF2DF13.dita">timezoneconversion: Using

    55 the time zone server</xref></p></section>

    56 </conbody></concept>