1/*
2 This file is part of the KDE libraries
3 Copyright (c) 2005-2008 David Jarvie <djarvie@kde.org>
4
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 as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21/** @file
22 * TZFILE time zone functions
23 * @author David Jarvie <djarvie@kde.org>.
24 */
25
26#ifndef _KTZFILETIMEZONE_H
27#define _KTZFILETIMEZONE_H
28
29#include <kdecore_export.h>
30#include <ktimezone.h>
31
32#include <QtCore/QString>
33
34class KTzfileTimeZoneSource;
35class KTzfileTimeZonePrivate;
36class KTzfileTimeZoneDataPrivate;
37class KTzfileTimeZoneSourcePrivate;
38
39/**
40 * The KTzfileTimeZone class represents a time zone defined in tzfile(5) format.
41 *
42 * It works in partnership with the KTzfileTimeZoneSource class which reads and parses the
43 * time zone definition files.
44 *
45 * @short Represents a time zone defined in tzfile(5) format
46 * @see KTzfileTimeZoneBackend, KTzfileTimeZoneSource, KTzfileTimeZoneData
47 * @ingroup timezones
48 * @author David Jarvie <djarvie@kde.org>.
49 */
50class KDECORE_EXPORT KTzfileTimeZone : public KTimeZone //krazy:exclude=dpointer (no d-pointer for KTimeZone derived classes)
51{
52public:
53 /**
54 * Creates a time zone.
55 *
56 * @param source tzfile reader and parser
57 * @param name time zone's unique name, which must be the tzfile path relative
58 * to the location specified for @p source
59 * @param countryCode ISO 3166 2-character country code, empty if unknown
60 * @param latitude in degrees (between -90 and +90), UNKNOWN if not known
61 * @param longitude in degrees (between -180 and +180), UNKNOWN if not known
62 * @param comment description of the time zone, if any
63 */
64 KTzfileTimeZone(KTzfileTimeZoneSource *source, const QString &name,
65 const QString &countryCode = QString(), float latitude = UNKNOWN, float longitude = UNKNOWN,
66 const QString &comment = QString());
67
68 ~KTzfileTimeZone();
69
70private:
71 // d-pointer is in KTzfileTimeZoneBackend.
72 // This is a requirement for classes inherited from KTimeZone.
73};
74
75
76/**
77 * Backend class for KTzfileTimeZone class.
78 *
79 * This class implements KTzfileTimeZone's constructors and virtual methods. A
80 * backend class is required for all classes inherited from KTimeZone to
81 * allow KTimeZone virtual methods to work together with reference counting of
82 * private data.
83 *
84 * @short Backend class for KTzfileTimeZone class
85 * @see KTimeZoneBackend, KTzfileTimeZone, KTimeZone
86 * @ingroup timezones
87 * @author David Jarvie <djarvie@kde.org>.
88 */
89class KDECORE_EXPORT KTzfileTimeZoneBackend : public KTimeZoneBackend //krazy:exclude=dpointer (non-const d-pointer for KTimeZoneBackend-derived classes)
90{
91public:
92 /** Implements KTzfileTimeZone::KTzfileTimeZone(). */
93 KTzfileTimeZoneBackend(KTzfileTimeZoneSource *source, const QString &name,
94 const QString &countryCode, float latitude, float longitude, const QString &comment);
95
96 ~KTzfileTimeZoneBackend();
97
98 /**
99 * Creates a copy of this instance.
100 *
101 * @return new copy
102 */
103 virtual KTimeZoneBackend *clone() const;
104
105 /**
106 * Returns the class name of the data represented by this instance.
107 *
108 * @return "KTzfileTimeZone"
109 */
110 virtual QByteArray type() const;
111
112 /**
113 * Implements KTzfileTimeZone::hasTransitions().
114 *
115 * Returns whether daylight saving transitions are available for the time zone.
116 *
117 * @param caller calling KTzfileTimeZone object
118 * @return @c true
119 */
120 virtual bool hasTransitions(const KTimeZone* caller) const;
121
122private:
123 KTzfileTimeZonePrivate *d; // non-const
124};
125
126
127/**
128 * A class to read and parse tzfile time zone definition files.
129 *
130 * tzfile is the format used by zoneinfo files in the system time zone database.
131 * The format is documented in the tzfile(5) manpage.
132 *
133 * @short Reads and parses tzfile(5) time zone definition files
134 * @see KTzfileTimeZone, KTzfileTimeZoneData
135 * @ingroup timezones
136 * @author David Jarvie <djarvie@kde.org>.
137 */
138class KDECORE_EXPORT KTzfileTimeZoneSource : public KTimeZoneSource
139{
140public:
141 /**
142 * Constructs a time zone source.
143 *
144 * The directory containing the time zone definition files is given by the
145 * @p location parameter, which will usually be the zoneinfo directory. For
146 * tzfile files in other locations, bear in mind that the name generated
147 * for each KTzfileTimeZone is its file path relative to @p location.
148 *
149 * @param location the local directory containing the time zone definition files
150 */
151 explicit KTzfileTimeZoneSource(const QString &location);
152 virtual ~KTzfileTimeZoneSource();
153
154 /**
155 * Returns the local directory containing the time zone definition files.
156 *
157 * @return path to time zone definition files
158 */
159 QString location() const;
160
161 /**
162 * Parses a tzfile file to extract detailed information for one time zone.
163 *
164 * @param zone the time zone for which data is to be extracted
165 * @return a KTzfileTimeZoneData instance containing the parsed data.
166 * The caller is responsible for deleting the KTimeZoneData instance.
167 * Null is returned on error.
168 */
169 virtual KTimeZoneData *parse(const KTimeZone &zone) const;
170
171private:
172 KTzfileTimeZoneSourcePrivate * const d;
173};
174
175
176/**
177 * @internal
178 * The parsed data returned by KTzfileTimeZoneSource.
179 *
180 * @short Parsed data from tzfile(5) time zone definition files
181 * @see KTzfileTimeZoneSource, KTzfileTimeZone
182 * @ingroup timezones
183 * @author David Jarvie <djarvie@kde.org>.
184 */
185class KTzfileTimeZoneData : public KTimeZoneData
186{
187 friend class KTzfileTimeZoneSource;
188
189public:
190 KTzfileTimeZoneData();
191 KTzfileTimeZoneData(const KTzfileTimeZoneData &);
192 virtual ~KTzfileTimeZoneData();
193
194 KTzfileTimeZoneData &operator=(const KTzfileTimeZoneData &);
195
196 /**
197 * Creates a new copy of this object.
198 * The caller is responsible for deleting the copy.
199 * Derived classes must reimplement this method to return a copy of the
200 * calling instance
201 *
202 * @return copy of this instance. This is a KTzfileTimeZoneData pointer.
203 */
204 virtual KTimeZoneData *clone() const;
205
206 /**
207 * Return whether daylight saving transitions are available for the time zone.
208 *
209 * @return @c true
210 */
211 virtual bool hasTransitions() const;
212
213private:
214 // Enable this if you add KDECORE_EXPORT to this class
215 //KTzfileTimeZoneDataPrivate * const d;
216};
217
218#endif
219