2
This file is part of the KDE libraries
3
Copyright (c) 2005 S.R.Haque <srhaque@iee.org>.
5
This library is free software; you can redistribute it and/or
6
modify it under the terms of the GNU Library General Public
7
License version 2 as published by the Free Software Foundation.
9
This library is distributed in the hope that it will be useful,
10
but WITHOUT ANY WARRANTY; without even the implied warranty of
11
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12
Library General Public License for more details.
14
You should have received a copy of the GNU Library General Public License
15
along with this library; see the file COPYING.LIB. If not, write to
16
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17
Boston, MA 02110-1301, USA.
20
#ifndef _KstTIMEZONES_H
21
#define _KstTIMEZONES_H
23
#include <qdatetime.h>
24
#include <qnamespace.h>
27
#include <ksharedptr.h>
28
#include <kst_export.h>
29
class KstTimezoneDetails;
30
class KstTimezoneDetailsPrivate;
31
class KstTimezonePrivate;
32
class KstTimezonesPrivate;
35
* The KTimezoneSource class contains information source-dependent functions
36
* related to a timezone. Create subclasses to implement custom sources of
37
* timezone information.
39
* For example, to be able to create {@link KTimezone } objects from libical's
42
* <li>Subclass this class with a custom {@link parse() } routine.
43
* <li>Create one or more instances of this class.
44
* <li>Use the instance(s) to create {@link KTimezone } objects.
45
* <li>If required, add the objects to a {@link KTimezones } database.
48
* @author S.R.Haque <srhaque@iee.org>.
50
class KST_EXPORT KstTimezoneSource :
54
KstTimezoneSource(const QString &db);
55
virtual ~KstTimezoneSource();
58
* Location of system timezone information.
59
* @return value which can be combined with zone name to retrieve timezone info.
64
* Extract timezone detail information. The default implementation consists
65
* of a parser for zoneinfo files in tzfile(5).
66
* @return true if the parse encountered no errors.
68
virtual bool parse(const QString &zone, KstTimezoneDetails &dataReceiver) const;
75
* The KstTimezone class contains core functions related to a timezone. Instances
76
* are created in the context of a {@link KstTimezoneSource } which provides
77
* extended functionality via {@link KstTimezoneDetails }.
79
* @see KstTimezoneSource
80
* @see KstTimezoneDetails
82
* @author S.R.Haque <srhaque@iee.org>.
84
class KST_EXPORT KstTimezone
88
* A representation for unknown locations; this is a float
89
* that does not represent a real latitude or longitude.
91
static const float UNKNOWN;
94
* A test for a valid latitude. The valid range is +90.0 (North Pole)
95
* to -90.0 (South Pole).
97
static bool isValidLatitude(float latitude);
100
* A test for a valid longitude. The valid range is +180.0 (east of
101
* Greenwich) to -180.0 (west of Greenwich).
103
static bool isValidLongitude(float longitude);
108
* @param db database of timezones.
109
* @param name in system-dependent format.
110
* @param countryCode ISO 3166 2-character country code, empty if unknown.
111
* @param latitude in degrees, UNKNOWN if not known.
112
* @param longitude in degrees, UNKNOWN if not known.
113
* @param comment description of the timezone, if any.
116
KSharedPtr<KstTimezoneSource> db, const QString &name,
117
const QString &countryCode = QString(), float latitude = UNKNOWN, float longitude = UNKNOWN,
118
const QString &comment = QString());
122
* Returns the name of the timezone.
124
* @return name in system-dependent format.
126
QString name() const;
129
* Returns the two-letter country code of the timezone.
131
* @return ISO 3166 2-character country code, empty if unknown.
133
QString countryCode() const;
136
* Returns the latitude of the timezone.
138
* @return latitude in degrees, UNKNOWN if not known.
140
float latitude() const;
143
* Returns the latitude of the timezone.
145
* @return latitude in degrees, UNKNOWN if not known.
147
float longitude() const;
150
* Returns the current offset of this timezone to UTC or the local
151
* timezone in seconds.
153
* Take care if you cache the results of this routine; that would
154
* break if the result were stored across a daylight savings change.
156
* @return offset in seconds.
158
int offset(Qt::TimeSpec basisSpec = Qt::UTC) const;
161
* Returns the offset of the given timezone to UTC at the given
162
* date/time (which is interpreted as being UTC).
164
* @return offset in seconds.
166
int offset(const QDateTime &dateTime) const;
169
* Convert a date/time (which is interpreted as being localtime in this
170
* timezone) into localtime in the given timezone.
172
* @return converted date/time.
174
QDateTime convert(const KstTimezone *newZone, const QDateTime &dateTime) const;
177
* Returns any comment for the timezone.
179
* @return comment, may be empty.
181
QString comment() const;
184
* Extract timezone detail information.
185
* @return true if the parse encountered no errors.
187
bool parse(KstTimezoneDetails &dataReceiver) const;
190
KSharedPtr<KstTimezoneSource> m_db;
192
QString m_countryCode;
196
KstTimezonePrivate *d;
200
* The KstTimezoneDetails class contains extended functions related to a
203
* The parser must be customised by overriding the given virtual callbacks:
205
* <li>{@link parseEnded() }
206
* <li>{@link parseStarted() }
207
* <li>{@link gotHeader() }
208
* <li>{@link gotTransitionTime() }
209
* <li>{@link gotLocalTimeIndex() }
210
* <li>{@link gotLocalTime() }
211
* <li>{@link gotAbbreviation() }
212
* <li>{@link gotLeapAdjustment() }
213
* <li>{@link gotIsStandard() }
214
* <li>{@link gotIsUTC() }
219
* @author S.R.Haque <srhaque@iee.org>.
221
class KST_EXPORT KstTimezoneDetails
224
KstTimezoneDetails();
225
virtual ~KstTimezoneDetails();
228
* Always called after all other callbacks.
230
virtual void parseEnded();
233
* Always called before any other callback.
235
virtual void parseStarted();
238
* Called when the header is seen.
240
virtual void gotHeader(
241
unsigned ttIsGmtCnt, unsigned ttIsStdCnt, unsigned leapCnt,
242
unsigned timeCnt, unsigned typeCnt, unsigned charCnt);
245
* Called when a transition time is seen.
247
virtual void gotTransitionTime(int index, unsigned transitionTime);
250
* Called when a local time index is seen.
252
virtual void gotLocalTimeIndex(int index, unsigned localTimeIndex);
255
* Called when a local time is seen.
257
virtual void gotLocalTime(int index, int gmtOff, bool isDst, unsigned abbrIndex);
260
* Called when a timezone abbreviation is seen. Note that the index here
261
* is NOT a simple incrementing integer, rather it matches the sequence
262
* of abbrIndex values from {@link gotLocalTime() }.
264
virtual void gotAbbreviation(int index, const QString &abbr);
267
* Called when a leap second adjustment is seen.
269
virtual void gotLeapAdjustment(int index, unsigned leapTime, unsigned leapSeconds);
272
* Called when a standard/wall time indicator is seen.
274
virtual void gotIsStandard(int index, bool isStandard);
277
* Called when a UTC/local time indicator is seen.
279
virtual void gotIsUTC(int index, bool isUTC);
282
KstTimezoneDetailsPrivate *d;
286
* The KstTimezones class models a timezone database. It supports system
287
* timezones, and also has support for private timezone entries.
290
* @author S.R.Haque <srhaque@iee.org>.
292
class KST_EXPORT KstTimezones
299
* Returns the local timezone. The idea of this routine is to provide a
300
* robust lookup of the local timezone.
302
* The problem is that on Unix systems, there are a variety of mechanisms
303
* for setting this information, and no real way of getting it. For example,
304
* if you set your timezone to "Europe/London", then the tzname[]
305
* maintained by tzset() typically returns { "GMT", "BST" }. The point of
306
* this routine is to actually return "Europe/London" (or rather, the
307
* corresponding KstTimezone).
309
* @return local timezone. If necessary, we will use a series of heuristics
310
* which end by returning UTC. We will never return NULL.
312
const KstTimezone *local();
315
* Returns the given timezone.
317
* @param name Name of timezone. Empty is equivalent to UTC.
318
* @return named timezone, NULL on error.
320
const KstTimezone *zone(const QString &name);
322
typedef QMap<QString, KstTimezone *> ZoneMap;
325
* Return timezone database.
326
* @return known timezones.
328
const ZoneMap allZones();
331
* Add user-defined timezone to database.
333
void add(KstTimezone *zone);
336
float convertCoordinate(const QString &coordinate);
338
QString m_zoneinfoDir;
341
KstTimezonesPrivate *d;
added
removed
kst/kst/ksttimezones.h
