<?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-676D1493-0035-4AD3-A0E5-A207B25809E4" xml:lang="en"><title>Time

Zone Services Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-30F76544-4824-4979-93A6-CC7F09818443">       <title>Purpose</title><p>Interfaces

within Time Zone Services are used to enable client applications to make updates

to system TZ data, receive notification of time changes, and manage user-defined

TZ data. Conversion services enable a client to convert time between Universal

Time Coordinated and any other time.  </p></section>

<section id="GUID-8C787174-5ABD-4CE5-A205-986873AA5F00"><title>Key concepts/terms</title>The following terms are used throughout

Time Zone Services documentation:<p><dl>

<dlentry>

<dt>P&amp;S</dt>

<dd><p>Publish and Subscribe. </p></dd>

</dlentry>

<dlentry>

<dt>PKG</dt>

<dd><p>Package File Format, which allows easy installation of software. </p></dd>

</dlentry>

<dlentry>

<dt>SIS</dt>

<dd><p>Symbian installation file. A collection of executables and/or data

files packaged in a form suitable so that the Software Installer can install

them onto a device.</p></dd>

</dlentry>

<dlentry>

<dt>SWI </dt>

<dd><p>Software Installer.</p></dd>

</dlentry>

<dlentry>

<dt>System TZ data </dt>

<dd><p>Refers to the time zone database found in the TZ Server component and

the TZ localization resources found in the TZ Localization component.</p></dd>

</dlentry>

<dlentry>

<dt>TZID</dt>

<dd><p>Refers to the time zone database found in the TZ Server component and

the TZ localization resources found in the TZ Localization component.</p></dd>

</dlentry>

<dlentry>

<dt>TZ rules data</dt>

<dd><p>Refers to the TZ rules found in the TZ database, the TZ rules that

define the current/system TZ and the user-defined TZ rules.</p></dd>

</dlentry>

<dlentry>

<dt>User-defined TZ data</dt>

<dd><p>The TZ rules and TZ names (city name, region name and long/short standard

time name and long/short daylight time names). User-defined TZ data may be

added by the user of the device. </p></dd>

</dlentry>

<dlentry>

<dt>UTC </dt>

<dd><p>Universal Time Coordinated.</p></dd>

</dlentry>

</dl></p></section>

<section id="GUID-4E5DB06A-4729-4008-BB03-9C3A27C4DE96"><title>Architectural relationships</title><p>Alarm Server and Calendar

Server components depend on the latest TZ rules information. When notified

of changes to TZ rules data these components update their TZ-dependent data.

TZ conversion rules are used to convert between UTC and a time in the past,

present or future, for any time zone.</p><p>Time zone conversion allows you

to set the device time zone and to convert time between UTC and any time,

past, present or future, for any time zone, as long as a rule exists for the

conversion.  </p></section>

<section id="GUID-5C98F76D-C181-4D43-8784-1306830E4D7D"><title>Time Zone Services interfaces </title><p>The following classes

form the main interface to Time Zone Services:</p><table id="GUID-F78AECCB-AEDE-4054-929C-DC756DA901AC">

<tgroup cols="2"><colspec colname="col1" colwidth="0.58*"/><colspec colname="col2" colwidth="1.42*"/>

<thead>

<row>

<entry valign="top"><p>Interface</p></entry>

<entry valign="top"><p>Description</p></entry>

</row>

</thead>

<tbody>

<row>

<entry><p><codeph>CTzUserData</codeph></p></entry>

<entry><p>Allows a client to manage user-defined time zones.</p></entry>

</row>

<row>

<entry><p><codeph>CTzUserNames</codeph></p></entry>

<entry><p>Contains the names for a user-defined time zone.</p></entry>

</row>

<row>

<entry><p><codeph>CTzRules</codeph></p></entry>

<entry><p>Encapsulates a collection of time zone rules</p></entry>

</row>

<row>

<entry><p><codeph>CTzId</codeph></p></entry>

<entry><p>Contains a time zone identifier.</p></entry>

</row>

<row>

<entry><p><codeph>RTz</codeph></p></entry>

<entry><p>Converts between UTC time and local time, and sets the current local

time zone.</p></entry>

</row>

<row>

<entry><p><codeph>CTzConverter</codeph></p></entry>

<entry><p>Provides client-side caching for conversions in the local time zone.</p></entry>

</row>

</tbody>

</tgroup>

</table><p>The following interfaces are also used: </p><ul>

<li><p>SWI service - see System TZ Data Update </p></li>

<li><p>Resource files - see User-defined TZ Data </p></li>

<li><p>Publish and Subscribe - see TZ Data Change Notification </p></li>

</ul><p><b>System TZ data update</b></p><p>The system TZ data can be updated

at run-time. The installation mechanism uses the standard SWI service to install

a SIS file containing the updated TZ data onto a device.</p><p>Once the system

TZ data has been updated using the SIS file, the device will automatically

make use of the updated data. This includes updating any cached data managed

by Symbian platform components and notifying all registered clients of the

system TZ data change.</p><p/><p><b>User-defined TZ data</b></p><p><codeph>CTzUserData</codeph> provides

functions to create, read, update or delete user-defined TZ data. The API

also allows the TZIDs for all existing user-defined TZ data to be determined.

  </p><p><codeph>CTzUserNames</codeph> is used to contain the names for user-defined

time zones. These include long/short standard time names, long/short daylight

time names, city name and region name.</p><p>TZID is a time zone identifier

contained in the <codeph>CTzId</codeph> class. There are two components to

a TZID: a numeric identifier and a name identifier. </p><p><b>TZ data change

notification</b></p><p>The Time Zone Services APIs support several Publish

and Subscribe (P&S) properties, some of which are described below. Clients

can attach and subscribe to these properties to allow them to be notified

of TZ data changes.</p><p> The Calendar uses the callback API <codeph>MCalChangeCallBack2</codeph> for

asynchronous change notification.</p><ul>

<li><p><b>Publish and Subscribe</b> - The <codeph>NTzUpdate</codeph> namespace

contains a property category and property keys. The property key <codeph>ETzRulesChange</codeph> is

used to inform clients of changes to:</p><ul>

<li><p>the system TZ database </p></li>

<li><p>current and system TZ rules </p></li>

<li><p>user-defined rules.</p></li>

</ul><p>The property key <codeph>ETzNamesChange</codeph> is responsible for

changes to the localized system TZ names and non-localized user-defined TZ

names. </p> </li>

<li><p><b>Alarm Server client</b> - The Alarm Server supports fixed UTC time

and floating local time to express the expiry time of an alarm. The TZ Server

then recalculates and sets the current UTC offset.</p><p>See <xref href="GUID-9BE3DEBE-A1CE-5A2F-9746-1E6F2B5B050E.dita">System

Time and Locale Changes</xref>. </p></li>

<li><p><b>Calendar client</b> - The Calendar API allows a client to be notified

of changes to Calendar entries.</p><p>For more information, see <xref href="GUID-3987D040-27F7-5226-96AC-D578ECA4C0A2.dita">Callback

Interfaces</xref>.</p></li>

</ul></section>

<section id="GUID-5102801C-87DC-4AC1-8733-F216C043A36F"><title>See also</title><ul>

<li><p><xref href="GUID-F0C71D6E-CAF1-49CC-A697-FC1A810DF1D5.dita">Time zone services

tutorials</xref></p></li>

<li><p><xref href="GUID-A0E21681-F1EF-4E79-965A-040AC7D72A01.dita">Time Zone Conversion

Overview</xref></p></li>

</ul></section>

</conbody></concept>