1/*
2 This file is part of the kcalcore library.
3
4 Copyright (c) 1998 Preston Brown <pbrown@kde.org>
5 Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@kde.org>
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this library; see the file COPYING.LIB. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA.
21*/
22/**
23 @file
24 This file is part of the API for handling calendar data and
25 defines the VCalFormat base class.
26
27 This class implements the vCalendar format. It provides methods for
28 loading/saving/converting vCalendar format data into the internal
29 representation as Calendar and Incidences.
30
31 @brief
32 vCalendar format implementation.
33
34 @author Preston Brown \<pbrown@kde.org\>
35 @author Cornelius Schumacher \<schumacher@kde.org\>
36*/
37
38#ifndef KCALCORE_VCALFORMAT_H
39#define KCALCORE_VCALFORMAT_H
40
41#include "kcalcore_export.h"
42#include "attendee.h"
43#include "calformat.h"
44#include "event.h"
45#include "todo.h"
46#include "journal.h"
47
48struct VObject;
49
50class KDateTime;
51
52class QDate;
53
54#define _VCAL_VERSION "1.0"
55
56namespace KCalCore {
57
58class Event;
59class Todo;
60
61/**
62 @brief
63 vCalendar format implementation.
64
65 This class implements the vCalendar format. It provides methods for
66 loading/saving/converting vCalendar format data into the internal
67 representation as Calendar and Incidences.
68*/
69class KCALCORE_EXPORT VCalFormat : public CalFormat
70{
71public:
72 /**
73 Constructor a new vCalendar Format object.
74 */
75 VCalFormat();
76
77 /**
78 Destructor.
79 */
80 virtual ~VCalFormat();
81
82 /**
83 @copydoc
84 CalFormat::load()
85 */
86 bool load(const Calendar::Ptr &calendar, const QString &fileName);
87
88 /**
89 @copydoc
90 CalFormat::save()
91 */
92 bool save(const Calendar::Ptr &calendar, const QString &fileName);
93
94 /**
95 @copydoc
96 CalFormat::fromString()
97 */
98 bool fromString(const Calendar::Ptr &calendar, const QString &string,
99 bool deleted = false, const QString &notebook = QString());
100
101 /**
102 @copydoc
103 CalFormat::toString()
104 */
105 QString toString(const Calendar::Ptr &calendar, const QString &notebook = QString(),
106 bool deleted = false);
107
108 /**
109 @copydoc
110 CalFormat::fromRawString()
111 */
112 bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string,
113 bool deleted = false, const QString &notebook = QString());
114
115protected:
116 /**
117 Translates a VObject of the TODO type into an Event.
118 @param vtodo is a pointer to a valid VObject object.
119 */
120 Todo::Ptr VTodoToEvent(VObject *vtodo);
121
122 /**
123 Translates a VObject into a Event and returns a pointer to it.
124 @param vevent is a pointer to a valid VObject object.
125 */
126 Event::Ptr VEventToEvent(VObject *vevent);
127
128 /**
129 Translates an Event into a VEvent-type VObject and returns a pointer to it.
130 @param event is a pointer to a valid Event object.
131 */
132 VObject *eventToVEvent(const Event::Ptr &event);
133
134 /**
135 Parse TZ tag from vtimezone.
136 */
137 QString parseTZ(const QByteArray &timezone) const;
138
139 /**
140 Parse DAYLIGHT tag from vtimezone.
141 */
142 QString parseDst(QByteArray &timezone) const;
143
144 /**
145 Translates a Todo into a VTodo-type VObject and return pointer.
146 @param todo is a pointer to a valid Todo object.
147 */
148 VObject *eventToVTodo(const Todo::Ptr &todo);
149
150 /**
151 Takes a QDate and returns a string in the format YYYYMMDDTHHMMSS.
152 @param date is the date to format.
153 */
154 QString qDateToISO(const QDate &date);
155
156 /**
157 Takes a KDateTime and returns a string in format YYYYMMDDTHHMMSS.
158 @param date is the date to format.
159 @param zulu if true, then shift the date to UTC.
160 */
161 QString kDateTimeToISO(const KDateTime &date, bool zulu = true);
162
163 /**
164 Takes a string in YYYYMMDDTHHMMSS format and returns a valid KDateTime.
165 @param dtStr is a QString containing the date to convert. If this value
166 is invalid, then KDateTime() is returned.
167 */
168 KDateTime ISOToKDateTime(const QString &dtStr);
169
170 /**
171 Takes a string in the YYYYMMDD format and returns a valid QDate.
172 @param dtStr is a QString containing the date to convert. If this value
173 is invalid, then KDateTime() is returned.
174 */
175 QDate ISOToQDate(const QString &dtStr);
176
177 /**
178 Parse one of the myriad of ISO8601 timezone offset formats, e.g.
179 +- hh : mm
180 +- hh mm
181 +- hh
182
183 @param s string to be parsed.
184 @param result timezone offset in seconds, if parse succeeded.
185 @return Whether the parse succeeded or not.
186 */
187 bool parseTZOffsetISO8601(const QString &s, int &result);
188
189 /**
190 Takes a vCalendar tree of VObjects, and puts all of them that have the
191 "event" property into the dictionary, todos in the todo-list, etc.
192 */
193 void populate(VObject *vcal, bool deleted = false, const QString &notebook = QString());
194
195 /**
196 Takes a number 0 - 6 and returns the two letter string of that day,
197 i.e. MO, TU, WE, etc.
198
199 @param day number of the day to get a two letter name for. Range @c 0 - @c 6
200 @see numFromDay().
201 */
202 const char *dayFromNum(int day);
203
204 /**
205 Converts a two letter representation of the day (i.e. MO, TU, WE, etc) and
206 returns a number 0-6 corresponding to that ordinal day of the week.
207 @param day is the QString containing the two letter day representation.
208 @see dayFromNum().
209 */
210 int numFromDay(const QString &day);
211
212 /**
213 Converts a status string into an Attendee::PartStat.
214 @param s is a null-terminated character string containing the status to convert.
215
216 @return a valid Attendee::PartStat. If the string provided is empty, null,
217 or the contents are unrecognized, then Attendee::NeedsAction is returned.
218 */
219 Attendee::PartStat readStatus(const char *s) const;
220
221 /**
222 Converts an Attendee::PartStat into a QByteArray string.
223 @param status is the Attendee::PartStat to convert.
224
225 @return a QByteArray containing the status string.
226 */
227 QByteArray writeStatus(Attendee::PartStat status) const;
228
229 void readCustomProperties(VObject *o, const Incidence::Ptr &i);
230 void writeCustomProperties(VObject *o, const Incidence::Ptr &i);
231
232protected:
233 /**
234 @copydoc
235 IncidenceBase::virtual_hook()
236 */
237 virtual void virtual_hook(int id, void *data);
238
239private:
240 /**
241 The Pilot synchronization states.
242 */
243 enum PilotState {
244 SYNCNONE = 0,
245 SYNCMOD = 1,
246 SYNCDEL = 3
247 };
248
249 //@cond PRIVATE
250 Q_DISABLE_COPY(VCalFormat)
251 class Private;
252 Private *const d;
253 //@endcond
254};
255
256}
257
258#endif
259