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 | |
34 | class KTzfileTimeZoneSource; |
35 | class KTzfileTimeZonePrivate; |
36 | class KTzfileTimeZoneDataPrivate; |
37 | class 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 | */ |
50 | class KDECORE_EXPORT KTzfileTimeZone : public KTimeZone //krazy:exclude=dpointer (no d-pointer for KTimeZone derived classes) |
51 | { |
52 | public: |
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 & = QString()); |
67 | |
68 | ~KTzfileTimeZone(); |
69 | |
70 | private: |
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 | */ |
89 | class KDECORE_EXPORT KTzfileTimeZoneBackend : public KTimeZoneBackend //krazy:exclude=dpointer (non-const d-pointer for KTimeZoneBackend-derived classes) |
90 | { |
91 | public: |
92 | /** Implements KTzfileTimeZone::KTzfileTimeZone(). */ |
93 | KTzfileTimeZoneBackend(KTzfileTimeZoneSource *source, const QString &name, |
94 | const QString &countryCode, float latitude, float longitude, const QString &); |
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 | |
122 | private: |
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 | */ |
138 | class KDECORE_EXPORT KTzfileTimeZoneSource : public KTimeZoneSource |
139 | { |
140 | public: |
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 | |
171 | private: |
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 | */ |
185 | class KTzfileTimeZoneData : public KTimeZoneData |
186 | { |
187 | friend class KTzfileTimeZoneSource; |
188 | |
189 | public: |
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 | |
213 | private: |
214 | // Enable this if you add KDECORE_EXPORT to this class |
215 | //KTzfileTimeZoneDataPrivate * const d; |
216 | }; |
217 | |
218 | #endif |
219 | |