KSystemTimeZones Class Reference

#include <ksystemtimezone.h>

Inheritance diagram for KSystemTimeZones:

Public Member Functions
	~KSystemTimeZones ()

Static Public Member Functions
static bool	isSimulated ()
static bool	isTimeZoneDaemonAvailable ()
static KTimeZone	local ()
static KTimeZone	readZone (const QString &name)
static KTimeZone	realLocalZone ()
static void	setLocalZone (const KTimeZone &tz)
static KTimeZones *	timeZones ()
static KTimeZone	zone (const QString &name)
static QString	zoneinfoDir ()
static const KTimeZones::ZoneMap	zones ()

Detailed Description

The KSystemTimeZones class represents the system time zone database, consisting of a collection of individual system time zone definitions, indexed by name.

Each individual time zone is defined in a KSystemTimeZone or KTzfileTimeZone instance. Additional time zones (of any class derived from KTimeZone) may be added if desired.

At initialisation, KSystemTimeZones on UNIX systems reads the zone.tab file to obtain the list of system time zones, and creates a KTzfileTimeZone instance for each one.

Note

KSystemTimeZones gets the system's time zone configuration, including the current local system time zone and the location of zone.tab, from the KDE time zone daemon, ktimezoned. If ktimezoned cannot be started, KSystemTimeZones will only know about the UTC time zone.

Note that KSystemTimeZones is not derived from KTimeZones, but instead contains a KTimeZones instance which holds the system time zone database. Convenience static methods are defined to access its data, or alternatively you can access the KTimeZones instance directly via the timeZones() method.

As an example, find the local time in Oman corresponding to the local system time of 12:15:00 on 13th November 1999:

QDateTime sampleTime(QDate(1999,11,13), QTime(12,15,0), Qt::LocalTime);
KTimeZone local = KSystemTimeZones::local();
KTimeZone oman  = KSystemTimeZones::zone("Asia/Muscat");
QDateTime omaniTime = local.convert(oman, sampleTime);

Note

KTzfileTimeZone is used in preference to KSystemTimeZone on UNIX systems since use of the standard system libraries by KSystemTimeZone requires the use of tzset() in several methods. That function reads and parses the local system time zone definition file every time it is called, and this has been observed to make applications hang for many seconds when a large number of KSystemTimeZone calls are made in succession.

This class provides a facility to simulate the local system time zone. This facility is provided for testing purposes only, and is only available if the library is compiled with debug enabled. In release mode, simulation is inoperative and the real local system time zone is used at all times.

System time zone access

See also

KTimeZones, KSystemTimeZone, KSystemTimeZoneSource, KTzfileTimeZone

Author

David Jarvie djarv.nosp@m.ie@k.nosp@m.de.or.nosp@m.g.

S.R.Haque srhaq.nosp@m.ue@i.nosp@m.ee.or.nosp@m.g.

Definition at line 94 of file ksystemtimezone.h.

Constructor & Destructor Documentation

KSystemTimeZones::~KSystemTimeZones

(

)

Definition at line 191 of file ksystemtimezone.cpp.

Member Function Documentation

bool KSystemTimeZones::isSimulated ( )

static

Check whether there is a simulated local system time zone.

Warning

This method is provided only for testing purposes, and should not be used in released code. If the library is compiled without debug enabled, isSimulated() always returns false. To avoid confusion, it is recommended that calls to it should be conditionally compiled, e.g.:

#ifndef NDEBUG
   if (KSystemTimeZones::isSimulated())
   {
       ...
   }
#endif

See also

setLocalZone()

Since

4.3

Definition at line 219 of file ksystemtimezone.cpp.

bool KSystemTimeZones::isTimeZoneDaemonAvailable ( )

static

Return whether the KDE time zone daemon, ktimezoned, appears to be available and working.

If not, UTC will be the only recognized time zone.

Since

4.6

Definition at line 234 of file ksystemtimezone.cpp.

KTimeZone KSystemTimeZones::local ( )

static

Returns the current local system time zone.

The idea of this routine is to provide a robust lookup of the local time zone. On Unix systems, there are a variety of mechanisms for setting this information, and no well defined way of getting it. For example, if you set your time zone to "Europe/London", then the tzname[] maintained by tzset() typically returns { "GMT", "BST" }. The function of this routine is to actually return "Europe/London" (or rather, the corresponding KTimeZone).

Note that depending on how the system stores its current time zone, this routine may return a synonym of the expected time zone. For example, "Europe/London", "Europe/Guernsey" and some other time zones are all identical and there may be no way for the routine to distinguish which of these is the correct zone name from the user's point of view.

Warning

For testing purposes, if the library is compiled with debug enabled, this method returns any simulated local system time zone set by setLocalZone(). If the library is compiled in release mode, it always returns the real local system time zone.

Returns

local system time zone. If necessary, we will use a series of heuristics which end by returning UTC. We will never return NULL. Note that if UTC is returned as a default, it may not belong to the the collection returned by KSystemTimeZones::zones().

Definition at line 195 of file ksystemtimezone.cpp.

KTimeZone KSystemTimeZones::readZone ( const QString &  name )

static

Returns the time zone with the given name, containing the full time zone definition read directly from the system time zone database.

This may incur a higher overhead than zone(), but will provide whatever historical data the system holds.

Parameters

name	name of time zone

Returns

time zone (usually a KTzfileTimeZone instance), or invalid if not found

See also

zone()

Definition at line 245 of file ksystemtimezone.cpp.

KTimeZone KSystemTimeZones::realLocalZone ( )

static

Return the real (not simulated) local system time zone.

Warning

This method is provided only for testing purposes, and should not be used in released code. If the library is compiled without debug enabled, local() and realLocalZone() both return the real local system time zone. To avoid confusion, it is recommended that calls to realLocalZone() should be conditionally compiled, e.g.:

#ifndef NDEBUG
   tz = KSystemTimeZones::realLocalZone();
#endif

See also

setLocalZone()

Since

4.3

Definition at line 205 of file ksystemtimezone.cpp.

void KSystemTimeZones::setLocalZone ( const KTimeZone &  tz )

static

Set or clear the simulated local system time zone.

Warning

This method is provided only for testing purposes, and should not be used in released code. If the library is compiled without debug enabled, setLocalZone() has no effect. To avoid confusion, it is recommended that calls to it should be conditionally compiled, e.g.:

#ifndef NDEBUG
   KSystemTimeZones::setLocalZone(tz);
#endif

Parameters

tz	the time zone to simulate, or an invalid KTimeZone instance (i.e. tz.isValid() == false ) to cancel simulation

Since

4.3

Definition at line 211 of file ksystemtimezone.cpp.

KTimeZones * KSystemTimeZones::timeZones ( )

static

Returns the unique KTimeZones instance containing the system time zones collection.

It is first created if it does not already exist.

Returns

time zones.

Definition at line 240 of file ksystemtimezone.cpp.

KTimeZone KSystemTimeZones::zone ( const QString &  name )

static

Returns the time zone with the given name.

The time zone definition is obtained using system library calls, and may not contain historical data. If you need historical time change data, use the potentially slower method readZone().

Parameters

name	name of time zone

Returns

time zone (usually a KSystemTimeZone instance), or invalid if not found

See also

readZone()

Definition at line 255 of file ksystemtimezone.cpp.

QString KSystemTimeZones::zoneinfoDir ( )

static

Returns the location of the system time zone zoneinfo database.

Returns

path of directory containing the zoneinfo database

Definition at line 228 of file ksystemtimezone.cpp.

const KTimeZones::ZoneMap KSystemTimeZones::zones ( )

static

Returns all the time zones defined in this collection.

Returns

time zone collection

Definition at line 250 of file ksystemtimezone.cpp.

---

The documentation for this class was generated from the following files:

• ksystemtimezone.h
• ksystemtimezone.cpp