1 | /* |
2 | This file is part of the kcal library. |
3 | |
4 | Copyright (c) 2005-2007 David Jarvie <djarvie@kde.org> |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef KCAL_ICALTIMEZONES_H |
23 | #define KCAL_ICALTIMEZONES_H |
24 | |
25 | #include <ktimezone.h> |
26 | |
27 | #include "kcal_export.h" |
28 | |
29 | #ifndef ICALCOMPONENT_H |
30 | typedef struct icalcomponent_impl icalcomponent; |
31 | #endif |
32 | #ifndef ICALTIMEZONE_DEFINED |
33 | #define ICALTIMEZONE_DEFINED |
34 | typedef struct _icaltimezone icaltimezone; |
35 | #endif |
36 | |
37 | namespace KCal { |
38 | |
39 | class ICalTimeZone; |
40 | class ICalTimeZoneSource; |
41 | class ICalTimeZoneData; |
42 | class ICalTimeZonesPrivate; |
43 | class ICalTimeZonePrivate; |
44 | class ICalTimeZoneSourcePrivate; |
45 | class ICalTimeZoneDataPrivate; |
46 | |
47 | /** |
48 | * The ICalTimeZones class represents a time zone database which consists of a |
49 | * collection of individual iCalendar time zone definitions. |
50 | * |
51 | * Each individual time zone is defined in a ICalTimeZone instance. The time zones in the |
52 | * collection are indexed by name, which must be unique within the collection. |
53 | * |
54 | * Different calendars could define the same time zone differently. As a result, |
55 | * to avoid conflicting definitions, each calendar should normally have its own |
56 | * ICalTimeZones collection. |
57 | * |
58 | * This class is analogous to KTimeZones, but holds ICalTimeZone instances |
59 | * rather than generic KTimeZone instances. |
60 | * |
61 | * @short Represents a collection of iCalendar time zones |
62 | * @author David Jarvie <software@astrojar.org.uk>. |
63 | */ |
64 | class KCAL_DEPRECATED_EXPORT ICalTimeZones |
65 | { |
66 | public: |
67 | /** |
68 | * Constructs an empty time zone collection. |
69 | */ |
70 | ICalTimeZones(); |
71 | /** |
72 | * Destructor. |
73 | */ |
74 | ~ICalTimeZones(); |
75 | |
76 | /** |
77 | * Returns the time zone with the given name. |
78 | * Note that the ICalTimeZone returned remains a member of the ICalTimeZones |
79 | * collection, and should not be deleted without calling remove() first. |
80 | * |
81 | * @param name name of time zone |
82 | * @return time zone, or invalid if not found |
83 | */ |
84 | ICalTimeZone zone( const QString &name ) const; |
85 | |
86 | typedef QMap<QString, ICalTimeZone> ZoneMap; |
87 | |
88 | /** |
89 | * Returns all the time zones defined in this collection. |
90 | * |
91 | * @return time zone collection |
92 | */ |
93 | const ZoneMap zones() const; |
94 | |
95 | /** |
96 | * Adds a time zone to the collection. |
97 | * The time zone's name must be unique within the collection. |
98 | * |
99 | * @param zone time zone to add |
100 | * @return @c true if successful, @c false if zone's name duplicates one |
101 | * already in the collection |
102 | */ |
103 | bool add( const ICalTimeZone &zone ); |
104 | |
105 | /** |
106 | * Removes a time zone from the collection. |
107 | * |
108 | * @param zone time zone to remove |
109 | * @return the time zone which was removed, or invalid if not found |
110 | */ |
111 | ICalTimeZone remove( const ICalTimeZone &zone ); |
112 | |
113 | /** |
114 | * Removes a time zone from the collection. |
115 | * |
116 | * @param name name of time zone to remove |
117 | * @return the time zone which was removed, or invalid if not found |
118 | */ |
119 | ICalTimeZone remove( const QString &name ); |
120 | |
121 | /** |
122 | * Clears the collection. |
123 | */ |
124 | void clear(); |
125 | |
126 | private: |
127 | ICalTimeZones( const ICalTimeZones & ); // prohibit copying |
128 | ICalTimeZones &operator=( const ICalTimeZones & ); // prohibit copying |
129 | |
130 | ICalTimeZonesPrivate *const d; |
131 | }; |
132 | |
133 | /** |
134 | * The ICalTimeZone class represents an iCalendar VTIMEZONE component. |
135 | * |
136 | * ICalTimeZone instances are normally created by ICalTimeZoneSource::parse(). |
137 | * |
138 | * @short An iCalendar time zone |
139 | * @see ICalTimeZoneSource, ICalTimeZoneData |
140 | * @author David Jarvie <software@astrojar.org.uk>. |
141 | */ |
142 | class KCAL_DEPRECATED_EXPORT ICalTimeZone : public KTimeZone //krazy:exclude=dpointer |
143 | //(no d-pointer for KTimeZone derived classes) |
144 | { |
145 | public: |
146 | /** |
147 | * Constructs a null time zone. A null time zone is invalid. |
148 | * |
149 | * @see isValid() |
150 | */ |
151 | ICalTimeZone(); |
152 | |
153 | /** |
154 | * Creates a time zone. This constructor is normally called from |
155 | * ICalTimeZoneSource::parse(). |
156 | * |
157 | * @param source iCalendar VTIMEZONE reader and parser |
158 | * @param name time zone's unique name within the iCalendar object |
159 | * @param data parsed VTIMEZONE data |
160 | */ |
161 | ICalTimeZone( ICalTimeZoneSource *source, const QString &name, ICalTimeZoneData *data ); |
162 | |
163 | /** |
164 | * Constructor which converts a KTimeZone to an ICalTimeZone instance. |
165 | * |
166 | * @param tz KTimeZone instance |
167 | * @param earliest earliest date for which time zone data should be stored |
168 | */ |
169 | explicit ICalTimeZone( const KTimeZone &tz, const QDate &earliest = QDate() ); |
170 | |
171 | /** |
172 | * Destructor. |
173 | */ |
174 | virtual ~ICalTimeZone(); |
175 | |
176 | /** |
177 | * Returns the name of the city for this time zone, if any. There is no |
178 | * fixed format for the name. |
179 | * |
180 | * @return city name |
181 | */ |
182 | QString city() const; |
183 | |
184 | /** |
185 | * Returns the URL of the published VTIMEZONE definition, if any. |
186 | * |
187 | * @return URL |
188 | */ |
189 | QByteArray url() const; |
190 | |
191 | /** |
192 | * Returns the LAST-MODIFIED time of the VTIMEZONE, if any. |
193 | * |
194 | * @return time, or QDateTime() if none |
195 | */ |
196 | QDateTime lastModified() const; |
197 | |
198 | /** |
199 | * Returns the VTIMEZONE string which represents this time zone. |
200 | * |
201 | * @return VTIMEZONE string |
202 | */ |
203 | QByteArray vtimezone() const; |
204 | |
205 | /** |
206 | * Returns the ICal timezone structure which represents this time zone. |
207 | * The caller is responsible for freeing the returned structure using |
208 | * icaltimezone_free(). |
209 | * |
210 | * @return icaltimezone structure |
211 | */ |
212 | icaltimezone *icalTimezone() const; |
213 | |
214 | /** |
215 | * Update the definition of the time zone to be identical to another |
216 | * ICalTimeZone instance. A prerequisite is that the two instances must |
217 | * have the same name. |
218 | * |
219 | * The purpose of this method is to enable updates of ICalTimeZone |
220 | * definitions when a calendar is reloaded, without invalidating pointers |
221 | * to the instance (particularly pointers held by KDateTime objects). |
222 | * |
223 | * @param other time zone whose definition is to be used |
224 | * @return true if definition was updated (i.e. names are the same) |
225 | */ |
226 | bool update( const ICalTimeZone &other ); |
227 | |
228 | /** |
229 | * Returns a standard UTC time zone, with name "UTC". |
230 | * |
231 | * @note The ICalTimeZone returned by this method does not belong to any |
232 | * ICalTimeZones collection. Any ICalTimeZones instance may contain its own |
233 | * UTC ICalTimeZone defined by its time zone source data, but that will be |
234 | * a different instance than this ICalTimeZone. |
235 | * |
236 | * @return UTC time zone |
237 | */ |
238 | static ICalTimeZone utc(); |
239 | |
240 | private: |
241 | // d-pointer is in ICalTimeZoneBackend. |
242 | // This is a requirement for classes inherited from KTimeZone. |
243 | }; |
244 | |
245 | /** |
246 | * Backend class for KICalTimeZone class. |
247 | * |
248 | * This class implements KICalTimeZone's constructors and virtual methods. A |
249 | * backend class is required for all classes inherited from KTimeZone to |
250 | * allow KTimeZone virtual methods to work together with reference counting of |
251 | * private data. |
252 | * |
253 | * @short Backend class for KICalTimeZone class |
254 | * @see KTimeZoneBackend, KICalTimeZone, KTimeZone |
255 | * @ingroup timezones |
256 | * @author David Jarvie <software@astrojar.org.uk>. |
257 | */ |
258 | class KCAL_DEPRECATED_EXPORT ICalTimeZoneBackend : public KTimeZoneBackend |
259 | { |
260 | public: |
261 | /** Implements ICalTimeZone::ICalTimeZone(). */ |
262 | ICalTimeZoneBackend(); |
263 | /** |
264 | * Implements ICalTimeZone::ICalTimeZone(). |
265 | * |
266 | * @param source iCalendar VTIMEZONE reader and parser |
267 | * @param name time zone's unique name within the iCalendar object |
268 | * @param countryCode ISO 3166 2-character country code, empty if unknown |
269 | * @param latitude in degrees (between -90 and +90), UNKNOWN if not known |
270 | * @param longitude in degrees (between -180 and +180), UNKNOWN if not known |
271 | * @param comment description of the time zone, if any |
272 | */ |
273 | ICalTimeZoneBackend( ICalTimeZoneSource *source, const QString &name, |
274 | const QString &countryCode = QString(), |
275 | float latitude = KTimeZone::UNKNOWN, |
276 | float longitude = KTimeZone::UNKNOWN, |
277 | const QString & = QString() ); |
278 | |
279 | /** Implements ICalTimeZone::ICalTimeZone(). |
280 | * |
281 | * @param tz KTimeZone instance |
282 | * @param earliest earliest date for which time zone data should be stored |
283 | */ |
284 | ICalTimeZoneBackend( const KTimeZone &tz, const QDate &earliest ); |
285 | |
286 | virtual ~ICalTimeZoneBackend(); |
287 | |
288 | /** |
289 | * Creates a copy of this instance. |
290 | * |
291 | * @return new copy |
292 | */ |
293 | virtual KTimeZoneBackend *clone() const; |
294 | |
295 | /** |
296 | * Returns the class name of the data represented by this instance. |
297 | * |
298 | * @return "ICalTimeZone" |
299 | */ |
300 | virtual QByteArray type() const; |
301 | |
302 | /** |
303 | * Implements ICalTimeZone::hasTransitions(). |
304 | * |
305 | * Return whether daylight saving transitions are available for the time zone. |
306 | * |
307 | * @param caller calling ICalTimeZone object |
308 | * @return @c true |
309 | */ |
310 | virtual bool hasTransitions( const KTimeZone *caller ) const; |
311 | |
312 | private: |
313 | ICalTimeZonePrivate *d; //krazy:exclude=dpointer |
314 | //(non-const d-pointer for KTimeZoneBackend-derived classes) |
315 | }; |
316 | |
317 | /** |
318 | * A class which reads and parses iCalendar VTIMEZONE components, and accesses |
319 | * libical time zone data. |
320 | * |
321 | * ICalTimeZoneSource is used to parse VTIMEZONE components and create |
322 | * ICalTimeZone instances to represent them. |
323 | * |
324 | * @short Reader and parser for iCalendar time zone data |
325 | * @see ICalTimeZone, ICalTimeZoneData |
326 | * @author David Jarvie <software@astrojar.org.uk>. |
327 | */ |
328 | class KCAL_DEPRECATED_EXPORT ICalTimeZoneSource : public KTimeZoneSource |
329 | { |
330 | public: |
331 | /** |
332 | * Constructs an iCalendar time zone source. |
333 | */ |
334 | ICalTimeZoneSource(); |
335 | |
336 | /** |
337 | * Destructor. |
338 | */ |
339 | virtual ~ICalTimeZoneSource(); |
340 | |
341 | /** |
342 | * Creates an ICalTimeZone instance containing the detailed information |
343 | * parsed from a VTIMEZONE component. |
344 | * |
345 | * @param vtimezone the VTIMEZONE component from which data is to be extracted |
346 | * @return an ICalTimeZone instance containing the parsed data, or invalid on error |
347 | */ |
348 | ICalTimeZone parse( icalcomponent *vtimezone ); |
349 | |
350 | /** |
351 | * Creates an ICalTimeZone instance for each VTIMEZONE component within a |
352 | * CALENDAR component. The ICalTimeZone instances are added to a |
353 | * ICalTimeZones collection. |
354 | * |
355 | * If an error occurs while processing any time zone, any remaining time |
356 | * zones are left unprocessed. |
357 | * |
358 | * @param calendar the CALENDAR component from which data is to be extracted |
359 | * @param zones the time zones collection to which the ICalTimeZone |
360 | * instances are to be added |
361 | * @return @c false if any error occurred (either parsing a VTIMEZONE |
362 | * component or adding an ICalTimeZone to @p zones), @c true otherwise |
363 | */ |
364 | bool parse( icalcomponent *calendar, ICalTimeZones &zones ); |
365 | |
366 | /** |
367 | * Reads an iCalendar file and creates an ICalTimeZone instance for each |
368 | * VTIMEZONE component within it. The ICalTimeZone instances are added to a |
369 | * ICalTimeZones collection. |
370 | * |
371 | * If an error occurs while processing any time zone, any remaining time |
372 | * zones are left unprocessed. |
373 | * |
374 | * @param fileName the file from which data is to be extracted |
375 | * @param zones the time zones collection to which the ICalTimeZone |
376 | * instances are to be added |
377 | * @return @c false if any error occurred, @c true otherwise |
378 | */ |
379 | bool parse( const QString &fileName, ICalTimeZones &zones ); |
380 | |
381 | /** |
382 | * Creates an ICalTimeZone instance containing the detailed information |
383 | * contained in an icaltimezone structure. |
384 | * |
385 | * Note that an icaltimezone instance may internally refer to a built-in |
386 | * (i.e. system) time zone, in which case the data obtained from @p tz will |
387 | * actually be derived from the built-in time zone rather than from a |
388 | * VTIMEZONE component. |
389 | * |
390 | * @param tz the icaltimezone structure from which data is to be extracted |
391 | * @return an ICalTimeZone instance containing the time zone data, or invalid on error |
392 | */ |
393 | ICalTimeZone parse( icaltimezone *tz ); |
394 | |
395 | /** |
396 | * Creates an ICalTimeZone instance for a standard time zone. The system |
397 | * time zone definition is used in preference; otherwise, the built-in |
398 | * libical time zone definition is used. |
399 | * |
400 | * @param zone time zone name, which may optionally include the libical |
401 | * prefix string |
402 | * @param icalBuiltIn @p true to fetch only the libical built-in time zone, |
403 | * and ignore system time zone definitions |
404 | * @return an ICalTimeZone instance containing the time zone data, or invalid on error |
405 | */ |
406 | ICalTimeZone standardZone( const QString &zone, bool icalBuiltIn = false ); |
407 | |
408 | /** |
409 | * Returns the prefix string used in the TZID field in built-in libical |
410 | * time zones. The prefix string starts and ends with '/'. The name |
411 | * normally used for the time zone is obtained by stripping the prefix and |
412 | * the following characters up to the next '/', inclusive. |
413 | * |
414 | * @return prefix string |
415 | */ |
416 | static QByteArray icalTzidPrefix(); |
417 | |
418 | using KTimeZoneSource::parse; // prevent warning about hidden virtual method |
419 | |
420 | private: |
421 | ICalTimeZoneSourcePrivate *const d; |
422 | }; |
423 | |
424 | /** |
425 | * Parsed iCalendar VTIMEZONE data. |
426 | * |
427 | * This class is used by the ICalTimeZoneSource class to pass parsed |
428 | * data to an ICalTimeZone intance. |
429 | * |
430 | * @short Parsed iCalendar time zone data |
431 | * @see ICalTimeZone, ICalTimeZoneSource |
432 | * @author David Jarvie <software@astrojar.org.uk>. |
433 | */ |
434 | class KCAL_DEPRECATED_EXPORT ICalTimeZoneData : public KTimeZoneData |
435 | { |
436 | friend class ICalTimeZoneSource; |
437 | |
438 | public: |
439 | /** |
440 | * Default constructor. |
441 | */ |
442 | ICalTimeZoneData(); |
443 | |
444 | /** |
445 | * Copy constructor. |
446 | * |
447 | * @param rhs instance to copy from |
448 | */ |
449 | ICalTimeZoneData( const ICalTimeZoneData &rhs ); |
450 | |
451 | /** |
452 | * Constructor which converts a KTimeZoneData to an ICalTimeZoneData instance. |
453 | * If @p data is for a system time zone (i.e. @p tz is a KSystemTimeZone |
454 | * instance), the full time zone data is read from the system time zone |
455 | * database if possible; otherwise, the built-in libical time zone's data |
456 | * is used. |
457 | * |
458 | * @param rhs KTimeZoneData instance |
459 | * @param tz time zone which @p rhs belongs to |
460 | * @param earliest earliest date for which time zone data should be stored |
461 | */ |
462 | ICalTimeZoneData( const KTimeZoneData &rhs, const KTimeZone &tz, const QDate &earliest ); |
463 | |
464 | /** |
465 | * Destructor. |
466 | */ |
467 | virtual ~ICalTimeZoneData(); |
468 | |
469 | /** |
470 | * Assignment operator. |
471 | * |
472 | * @param rhs instance to copy from |
473 | * @return this instance |
474 | */ |
475 | ICalTimeZoneData &operator=( const ICalTimeZoneData &rhs ); |
476 | |
477 | /** |
478 | * Creates a new copy of this object. |
479 | * The caller is responsible for deleting the copy. |
480 | * |
481 | * @return copy of this instance |
482 | */ |
483 | virtual KTimeZoneData *clone() const; |
484 | |
485 | /** |
486 | * Returns the name of the city for this time zone, if any. There is no fixed |
487 | * format for the name. |
488 | * |
489 | * @return city name |
490 | */ |
491 | QString city() const; |
492 | |
493 | /** |
494 | * Returns the URL of the published VTIMEZONE definition, if any. |
495 | * |
496 | * @return URL |
497 | */ |
498 | QByteArray url() const; |
499 | |
500 | /** |
501 | * Returns the LAST-MODIFIED time of the VTIMEZONE, if any. |
502 | * |
503 | * @return time, or QDateTime() if none |
504 | */ |
505 | QDateTime lastModified() const; |
506 | |
507 | /** |
508 | * Returns the VTIMEZONE string which represents this time zone. |
509 | * |
510 | * @return VTIMEZONE string |
511 | */ |
512 | QByteArray vtimezone() const; |
513 | |
514 | /** |
515 | * Returns the ICal timezone structure which represents this time zone. |
516 | * The caller is responsible for freeing the returned structure using |
517 | * icaltimezone_free(). |
518 | * |
519 | * @return icaltimezone structure |
520 | */ |
521 | icaltimezone *icalTimezone() const; |
522 | |
523 | /** |
524 | * Return whether daylight saving transitions are available for the time zone. |
525 | * |
526 | * @return @c true |
527 | */ |
528 | virtual bool hasTransitions() const; |
529 | |
530 | private: |
531 | ICalTimeZoneDataPrivate *const d; |
532 | }; |
533 | |
534 | } |
535 | |
536 | #endif |
537 | |