<?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-DF4D7DFF-ECA9-40CF-9F3B-4BBC3F8162E4" xml:lang="en"><title>Converting
between UTC and local time</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-9CB60EE8-93DA-473B-AF76-5DBFAEED0E09"><title>Time zone ID</title> 
     <p>Each time zone is uniquely identified by its time zone ID which is
a numeric reference or a name. The <codeph>CTzId</codeph> class encapsulates
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
method, for example: </p><codeblock xml:space="preserve">_LIT8( KAsiaHongKong,"Asia/Hong_Kong" ); //A valid time zone name
CTzId* zoneId = CTzId::NewL( KAsiaHongKong );</codeblock><p>The time zone’s
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.
 </p><p><codeph>operator==()</codeph> and <codeph>operator!=()</codeph> can
be used to check if the time zone ID matches or differs from another time
zone ID.  </p></section>
<section id="GUID-4A2ED95F-8697-47FF-A89A-0871449ADFEE"><title>Converting
between UTC and local time</title><p>You can convert between times expressed
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.
 </p><p> <xref href="GUID-37A4A4ED-FFF8-3C98-B028-EA1947EA7BEF.dita"><apiname>CTzConverter</apiname></xref> does the conversion on the client
side by caching rules which it gets from the time zone server. This class
should be used for conversion between UTC and local time for the system time
zone, for performance reasons.   </p><p>If the conversion involves foreign
time zones, the <codeph>RTz</codeph> class can be used instead.  </p><p> The
following types of time conversion are possible:  </p><ul>
<li id="GUID-0B4E9E64-99DB-4BF2-A0FF-E62508F8E54A"><p><xref href="GUID-237E0861-EC1B-41DA-BDB0-1DEB50620CC8.dita">UTC
to local time in any time zone</xref></p></li>
<li id="GUID-B90DEC70-F232-43CD-AC8B-6D3D64090E2A"><p><xref href="GUID-F2487AEE-966E-472E-9162-E0400C9A8234.dita">UTC
to local time in the system time zone</xref></p></li>
<li id="GUID-2CC49848-516F-4345-91A4-8DE97566E297"><p><xref href="GUID-7A16B6E1-16F7-41EC-ABCC-4A2BEBD66FFF.dita">Local
time in the system time zone to UTC</xref> </p></li>
<li id="GUID-474CB987-56DB-4596-AC9F-7333A8619A0F"><p><xref href="GUID-043A9408-1A97-4122-9364-965ECC08B40F.dita">Local
time in any time zone to UTC</xref></p></li>
</ul></section>
<section id="GUID-9B7F2465-48B5-40E5-A459-FFE839DEF58C"><title>Setting the
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
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).
TTime myTime( KMyTime ); //Create the time as a TTime object
TInt errCode = myTZoneServer.SetHomeTime( myTime );</codeblock><p>The <codeph>WriteDeviceData</codeph> capability
is needed to set the system time.  </p></section>
<section id="GUID-12459F4B-EEF2-44DB-BB85-A180DA3FBD47"><title>Automatic UTC
offset</title><p>Whenever DST begins or ends, the UTC offset needs to be updated
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>.
This function takes a value from the <codeph>TTzAutoDSTUpdateModes</codeph> enum.
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>,
the UTC offset is automatically updated for changes to DST. </p></section>
<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
the time zone server</xref></p></section>
</conbody></concept>