|
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-676D1493-0035-4AD3-A0E5-A207B25809E4" xml:lang="en"><title>Time |
|
13 Zone Services Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-30F76544-4824-4979-93A6-CC7F09818443"> <title>Purpose</title><p>Interfaces |
|
15 within Time Zone Services are used to enable client applications to make updates |
|
16 to system TZ data, receive notification of time changes, and manage user-defined |
|
17 TZ data. Conversion services enable a client to convert time between Universal |
|
18 Time Coordinated and any other time. </p></section> |
|
19 <section id="GUID-8C787174-5ABD-4CE5-A205-986873AA5F00"><title>Key concepts/terms</title>The following terms are used throughout |
|
20 Time Zone Services documentation:<p><dl> |
|
21 <dlentry> |
|
22 <dt>P&S</dt> |
|
23 <dd><p>Publish and Subscribe. </p></dd> |
|
24 </dlentry> |
|
25 |
|
26 |
|
27 |
|
28 <dlentry> |
|
29 <dt>System TZ data </dt> |
|
30 <dd><p>Refers to the time zone database found in the TZ Server component and |
|
31 the TZ localization resources found in the TZ Localization component.</p></dd> |
|
32 </dlentry> |
|
33 <dlentry> |
|
34 <dt>TZID</dt> |
|
35 <dd><p>Refers to the time zone database found in the TZ Server component and |
|
36 the TZ localization resources found in the TZ Localization component.</p></dd> |
|
37 </dlentry> |
|
38 <dlentry> |
|
39 <dt>TZ rules data</dt> |
|
40 <dd><p>Refers to the TZ rules found in the TZ database, the TZ rules that |
|
41 define the current/system TZ and the user-defined TZ rules.</p></dd> |
|
42 </dlentry> |
|
43 <dlentry> |
|
44 <dt>User-defined TZ data</dt> |
|
45 <dd><p>The TZ rules and TZ names (city name, region name and long/short standard |
|
46 time name and long/short daylight time names). User-defined TZ data may be |
|
47 added by the user of the device. </p></dd> |
|
48 </dlentry> |
|
49 <dlentry> |
|
50 <dt>UTC </dt> |
|
51 <dd><p>Universal Time Coordinated.</p></dd> |
|
52 </dlentry> |
|
53 </dl></p></section> |
|
54 <section id="GUID-4E5DB06A-4729-4008-BB03-9C3A27C4DE96"><title>Architectural relationships</title><p>Alarm Server and Calendar |
|
55 Server components depend on the latest TZ rules information. When notified |
|
56 of changes to TZ rules data these components update their TZ-dependent data. |
|
57 TZ conversion rules are used to convert between UTC and a time in the past, |
|
58 present or future, for any time zone.</p><p>Time zone conversion allows you |
|
59 to set the device time zone and to convert time between UTC and any time, |
|
60 past, present or future, for any time zone, as long as a rule exists for the |
|
61 conversion. </p></section> |
|
62 <section id="GUID-5C98F76D-C181-4D43-8784-1306830E4D7D"><title>Time Zone Services interfaces </title><p>The following classes |
|
63 form the main interface to Time Zone Services:</p><table id="GUID-F78AECCB-AEDE-4054-929C-DC756DA901AC"> |
|
64 <tgroup cols="2"><colspec colname="col1" colwidth="0.58*"/><colspec colname="col2" colwidth="1.42*"/> |
|
65 <thead> |
|
66 <row> |
|
67 <entry valign="top"><p>Interface</p></entry> |
|
68 <entry valign="top"><p>Description</p></entry> |
|
69 </row> |
|
70 </thead> |
|
71 <tbody> |
|
72 <row> |
|
73 <entry><p><codeph>CTzUserData</codeph></p></entry> |
|
74 <entry><p>Allows a client to manage user-defined time zones.</p></entry> |
|
75 </row> |
|
76 <row> |
|
77 <entry><p><codeph>CTzUserNames</codeph></p></entry> |
|
78 <entry><p>Contains the names for a user-defined time zone.</p></entry> |
|
79 </row> |
|
80 <row> |
|
81 <entry><p><codeph>CTzRules</codeph></p></entry> |
|
82 <entry><p>Encapsulates a collection of time zone rules</p></entry> |
|
83 </row> |
|
84 <row> |
|
85 <entry><p><codeph>CTzId</codeph></p></entry> |
|
86 <entry><p>Contains a time zone identifier.</p></entry> |
|
87 </row> |
|
88 <row> |
|
89 <entry><p><codeph>RTz</codeph></p></entry> |
|
90 <entry><p>Converts between UTC time and local time, and sets the current local |
|
91 time zone.</p></entry> |
|
92 </row> |
|
93 <row> |
|
94 <entry><p><codeph>CTzConverter</codeph></p></entry> |
|
95 <entry><p>Provides client-side caching for conversions in the local time zone.</p></entry> |
|
96 </row> |
|
97 </tbody> |
|
98 </tgroup> |
|
99 </table><p>The following interfaces are also used: </p><ul> |
|
100 <li><p>SWI service - see System TZ Data Update </p></li> |
|
101 <li><p>Resource files - see User-defined TZ Data </p></li> |
|
102 <li><p>Publish and Subscribe - see TZ Data Change Notification </p></li> |
|
103 </ul><p><b>System TZ data update</b></p><p>The system TZ data can be updated |
|
104 at run-time. The installation mechanism uses the standard SWI service to install |
|
105 a SIS file containing the updated TZ data onto a device.</p><p>Once the system |
|
106 TZ data has been updated using the SIS file, the device will automatically |
|
107 make use of the updated data. This includes updating any cached data managed |
|
108 by Symbian platform components and notifying all registered clients of the |
|
109 system TZ data change.</p><p/><p><b>User-defined TZ data</b></p><p><codeph>CTzUserData</codeph> provides |
|
110 functions to create, read, update or delete user-defined TZ data. The API |
|
111 also allows the TZIDs for all existing user-defined TZ data to be determined. |
|
112 </p><p><codeph>CTzUserNames</codeph> is used to contain the names for user-defined |
|
113 time zones. These include long/short standard time names, long/short daylight |
|
114 time names, city name and region name.</p><p>TZID is a time zone identifier |
|
115 contained in the <codeph>CTzId</codeph> class. There are two components to |
|
116 a TZID: a numeric identifier and a name identifier. </p><p><b>TZ data change |
|
117 notification</b></p><p>The Time Zone Services APIs support several Publish |
|
118 and Subscribe (P&S) properties, some of which are described below. Clients |
|
119 can attach and subscribe to these properties to allow them to be notified |
|
120 of TZ data changes.</p><p> The Calendar uses the callback API <codeph>MCalChangeCallBack2</codeph> for |
|
121 asynchronous change notification.</p><ul> |
|
122 <li><p><b>Publish and Subscribe</b> - The <codeph>NTzUpdate</codeph> namespace |
|
123 contains a property category and property keys. The property key <codeph>ETzRulesChange</codeph> is |
|
124 used to inform clients of changes to:</p><ul> |
|
125 <li><p>the system TZ database </p></li> |
|
126 <li><p>current and system TZ rules </p></li> |
|
127 <li><p>user-defined rules.</p></li> |
|
128 </ul><p>The property key <codeph>ETzNamesChange</codeph> is responsible for |
|
129 changes to the localized system TZ names and non-localized user-defined TZ |
|
130 names. </p> </li> |
|
131 <li><p><b>Alarm Server client</b> - The Alarm Server supports fixed UTC time |
|
132 and floating local time to express the expiry time of an alarm. The TZ Server |
|
133 then recalculates and sets the current UTC offset.</p><p>See <xref href="GUID-9BE3DEBE-A1CE-5A2F-9746-1E6F2B5B050E.dita">System |
|
134 Time and Locale Changes</xref>. </p></li> |
|
135 <li><p><b>Calendar client</b> - The Calendar API allows a client to be notified |
|
136 of changes to Calendar entries.</p><p>For more information, see <xref href="GUID-3987D040-27F7-5226-96AC-D578ECA4C0A2.dita">Callback |
|
137 Interfaces</xref>.</p></li> |
|
138 </ul></section> |
|
139 <section id="GUID-5102801C-87DC-4AC1-8733-F216C043A36F"><title>See also</title><ul> |
|
140 <li><p><xref href="GUID-F0C71D6E-CAF1-49CC-A697-FC1A810DF1D5.dita">Time zone services |
|
141 tutorials</xref></p></li> |
|
142 <li><p><xref href="GUID-A0E21681-F1EF-4E79-965A-040AC7D72A01.dita">Time Zone Conversion |
|
143 Overview</xref></p></li> |
|
144 </ul></section> |
|
145 </conbody></concept> |