|
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\<build_variant></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> |