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:

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:

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.

See also

• Time zone services tutorials

• Time Zone Conversion Overview