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/terms

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