KCalendarCore

vcalformat.h
Go to the documentation of this file.
1 /*
2  This file is part of the kcalcore library.
3 
4  SPDX-FileCopyrightText: 1998 Preston Brown <[email protected]>
5  SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-or-later
8 */
9 /**
10  @file
11  This file is part of the API for handling calendar data and
12  defines the VCalFormat base class.
13 
14  This class implements the vCalendar format. It provides methods for
15  loading/saving/converting vCalendar format data into the internal
16  representation as Calendar and Incidences.
17 
18  @brief
19  vCalendar format implementation.
20 
21  @author Preston Brown <[email protected]>
22  @author Cornelius Schumacher <[email protected]>
23 */
24 
25 #ifndef KCALCORE_VCALFORMAT_H
26 #define KCALCORE_VCALFORMAT_H
27 
28 #include "attendee.h"
29 #include "calformat.h"
30 #include "event.h"
31 #include "journal.h"
32 #include "kcalendarcore_export.h"
33 #include "todo.h"
34 
35 struct VObject;
36 
37 class QDate;
38 
39 #define _VCAL_VERSION "1.0"
40 
41 /* extensions for iMIP / iTIP */
42 #define ICOrganizerProp "X-ORGANIZER"
43 #define ICMethodProp "X-METHOD"
44 #define ICRequestStatusProp "X-REQUEST-STATUS"
45 
46 namespace KCalendarCore
47 {
48 class Event;
49 class Todo;
50 class VCalFormatPrivate;
51 
52 /**
53  @brief
54  vCalendar format implementation.
55 
56  This class implements the vCalendar format. It provides methods for
57  loading/saving/converting vCalendar format data into the internal
58  representation as Calendar and Incidences.
59 */
60 class KCALENDARCORE_EXPORT VCalFormat : public CalFormat
61 {
62 public:
63  /**
64  Constructor a new vCalendar Format object.
65  */
66  VCalFormat();
67 
68  /**
69  Destructor.
70  */
71  ~VCalFormat() override;
72 
73  /**
74  @copydoc
75  CalFormat::load()
76  */
77  bool load(const Calendar::Ptr &calendar, const QString &fileName) override;
78 
79  /**
80  @copydoc
81  CalFormat::save()
82  */
83  bool save(const Calendar::Ptr &calendar, const QString &fileName) override;
84 
85 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 97)
86  /**
87  @copydoc
88  CalFormat::fromString()
89  */
90  KCALENDARCORE_DEPRECATED_VERSION(5, 97, "use fromString(const Calendar::Ptr &calendar, const QString &string, const QString &notebook)")
91  bool fromString(const Calendar::Ptr &calendar, const QString &string, bool deleted, const QString &notebook = QString()) override;
93 #endif
94 
95  /**
96  @copydoc
97  CalFormat::toString()
98  */
99  Q_REQUIRED_RESULT QString toString(const Calendar::Ptr &calendar, const QString &notebook = QString(), bool deleted = false) override;
100 
101  /**
102  @copydoc
103  CalFormat::fromRawString()
104  */
105  Q_REQUIRED_RESULT bool
106  fromRawString(const Calendar::Ptr &calendar, const QByteArray &string, bool deleted = false, const QString &notebook = QString()) override;
107 
108 protected:
109  /**
110  Translates a VObject of the TODO type into an Event.
111  @param vtodo is a pointer to a valid VObject object.
112  */
113  Todo::Ptr VTodoToEvent(VObject *vtodo);
114 
115  /**
116  Translates a VObject into a Event and returns a pointer to it.
117  @param vevent is a pointer to a valid VObject object.
118  */
119  Event::Ptr VEventToEvent(VObject *vevent);
120 
121  /**
122  Parse TZ tag from vtimezone.
123  */
124  QString parseTZ(const QByteArray &timezone) const;
125 
126  /**
127  Parse DAYLIGHT tag from vtimezone.
128  */
129  QString parseDst(QByteArray &timezone) const;
130 
131  /**
132  Takes a QDate and returns a string in the format YYYYMMDDTHHMMSS.
133  @param date is the date to format.
134  */
135  QString qDateToISO(const QDate &date);
136 
137  /**
138  Takes a QDateTime and returns a string in format YYYYMMDDTHHMMSS.
139  @param date is the date to format.
140  @param zulu if true, then shift the date to UTC.
141  */
142  QString qDateTimeToISO(const QDateTime &date, bool zulu = true);
143 
144  /**
145  Takes a string in YYYYMMDDTHHMMSS format and returns a valid QDateTime.
146  @param dtStr is a QString containing the date to convert. If this value
147  is invalid, then QDateTime() is returned.
148  */
149  QDateTime ISOToQDateTime(const QString &dtStr);
150 
151  /**
152  Takes a string in the YYYYMMDD format and returns a valid QDate.
153  @param dtStr is a QString containing the date to convert. If this value
154  is invalid, then QDateTime() is returned.
155  */
156  QDate ISOToQDate(const QString &dtStr);
157 
158  /**
159  Parse one of the myriad of ISO8601 timezone offset formats, e.g.
160  +- hh : mm
161  +- hh mm
162  +- hh
163 
164  @param s string to be parsed.
165  @param result timezone offset in seconds, if parse succeeded.
166  @return Whether the parse succeeded or not.
167  */
168  bool parseTZOffsetISO8601(const QString &s, int &result);
169 
170  /**
171  Takes a vCalendar tree of VObjects, and puts all of them that have the
172  "event" property into the dictionary, todos in the todo-list, etc.
173  */
174  void populate(VObject *vcal, bool deleted = false, const QString &notebook = QString());
175 
176  /**
177  Converts a two letter representation of the day (i.e. MO, TU, WE, etc) and
178  returns a number 0-6 corresponding to that ordinal day of the week.
179  @param day is the QString containing the two letter day representation.
180  */
181  int numFromDay(const QString &day);
182 
183  /**
184  Converts a status string into an Attendee::PartStat.
185  @param s is a null-terminated character string containing the status to convert.
186 
187  @return a valid Attendee::PartStat. If the string provided is empty, null,
188  or the contents are unrecognized, then Attendee::NeedsAction is returned.
189  */
190  Attendee::PartStat readStatus(const char *s) const;
191 
192  /**
193  Converts an Attendee::PartStat into a QByteArray string.
194  @param status is the Attendee::PartStat to convert.
195 
196  @return a QByteArray containing the status string.
197  */
198  QByteArray writeStatus(Attendee::PartStat status) const;
199 
200  void readCustomProperties(VObject *o, const Incidence::Ptr &i);
201  void writeCustomProperties(VObject *o, const Incidence::Ptr &i);
202 
203 protected:
204 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 96)
205  /**
206  @copydoc
207  IncidenceBase::virtual_hook()
208  */
209  void virtual_hook(int id, void *data) override;
210 #endif
211 
212 private:
213  //@cond PRIVATE
214  Q_DISABLE_COPY(VCalFormat)
215  Q_DECLARE_PRIVATE(VCalFormat)
216 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 96)
217  void *unused; // former dptr, just kept for ABI compatibility
218 #endif
219  //@endcond
220 };
221 
222 }
223 
224 #endif
Namespace for all KCalendarCore types.
Definition: alarm.h:36
Q_SCRIPTABLE CaptureState status()
PartStat
The different types of participant status.
Definition: attendee.h:64
vCalendar format implementation.
Definition: vcalformat.h:60
An abstract base class that provides an interface to various calendar formats.
Definition: calformat.h:38
virtual bool fromString(const Calendar::Ptr &calendar, const QString &string, bool deleted, const QString &notebook={})=0
Loads a calendar from a string.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 21 2023 04:00:46 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.