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
30typedef struct icalcomponent_impl icalcomponent;
31#endif
32#ifndef ICALTIMEZONE_DEFINED
33#define ICALTIMEZONE_DEFINED
34typedef struct _icaltimezone icaltimezone;
35#endif
36
37namespace KCal {
38
39class ICalTimeZone;
40class ICalTimeZoneSource;
41class ICalTimeZoneData;
42class ICalTimeZonesPrivate;
43class ICalTimeZonePrivate;
44class ICalTimeZoneSourcePrivate;
45class 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 */
64class 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 */
142class 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 */
258class 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 &comment = 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 */
328class 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 */
434class 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