Time +Zone Services Overview

Purpose

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.

Key concepts/termsThe following terms are used throughout +Time Zone Services documentation:

P&S: Publish and Subscribe.
System TZ data: Refers to the time zone database found in the TZ Server component and +the TZ localization resources found in the TZ Localization component.
TZID: Refers to the time zone database found in the TZ Server component and +the TZ localization resources found in the TZ Localization component.
TZ rules data: 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.
User-defined TZ data: 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.
UTC: Universal Time Coordinated.

Architectural relationships

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.

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.

Time Zone Services interfaces

The following classes +form the main interface to Time Zone Services:

+ + + +

Interface

Description

+ + + + +

CTzUserData

Allows a client to manage user-defined time zones.

+ + +

CTzUserNames

Contains the names for a user-defined time zone.

+ + +

CTzRules

Encapsulates a collection of time zone rules

+ + +

CTzId

Contains a time zone identifier.

+ + +

RTz

Converts between UTC time and local time, and sets the current local +time zone.

+ + +

CTzConverter

Provides client-side caching for conversions in the local time zone.

+ + + +

The following interfaces are also used:

SWI service - see System TZ Data Update
Resource files - see User-defined TZ Data
Publish and Subscribe - see TZ Data Change Notification

System TZ data update

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.

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.

User-defined TZ data

CTzUserData 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. +

CTzUserNames 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.

TZID is a time zone identifier +contained in the CTzId class. There are two components to +a TZID: a numeric identifier and a name identifier.

TZ data change +notification

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.

The Calendar uses the callback API MCalChangeCallBack2 for +asynchronous change notification.

Publish and Subscribe - The NTzUpdate namespace +contains a property category and property keys. The property key ETzRulesChange is +used to inform clients of changes to:
- the system TZ database
- current and system TZ rules
- user-defined rules.
The property key ETzNamesChange is responsible for +changes to the localized system TZ names and non-localized user-defined TZ +names.
Alarm Server client - 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.
See System +Time and Locale Changes.
Calendar client - The Calendar API allows a client to be notified +of changes to Calendar entries.
For more information, see Callback +Interfaces.