1/*
2 This file is part of the kcalcore library.
3
4 Copyright (c) 2001-2003 Cornelius Schumacher <schumacher@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 @file
23 This file is part of the API for handling calendar data and
24 defines the ICalFormat class.
25
26 @author Cornelius Schumacher \<schumacher@kde.org\>
27*/
28#ifndef KCALCORE_ICALFORMAT_H
29#define KCALCORE_ICALFORMAT_H
30
31#include "incidence.h"
32#include "freebusy.h"
33#include "kcalcore_export.h"
34#include "calformat.h"
35#include "schedulemessage.h"
36
37#include <KDE/KDateTime>
38
39namespace KCalCore {
40
41class FreeBusy;
42class Incidence;
43class IncidenceBase;
44class RecurrenceRule;
45
46/**
47 @brief
48 iCalendar format implementation.
49
50 This class implements the iCalendar format. It provides methods for
51 loading/saving/converting iCalendar format data into the internal
52 representation as Calendar and Incidences.
53
54 @warning When importing/loading to a Calendar, there is only duplicate
55 check if those Incidences are loaded into the Calendar. If they are not
56 loaded it will create duplicates.
57*/
58class KCALCORE_EXPORT ICalFormat : public CalFormat
59{
60public:
61 /**
62 Constructor a new iCalendar Format object.
63 */
64 ICalFormat();
65
66 /**
67 Destructor.
68 */
69 virtual ~ICalFormat();
70
71 /**
72 @copydoc
73 CalFormat::load()
74 */
75 bool load(const Calendar::Ptr &calendar, const QString &fileName);
76
77 /**
78 @copydoc
79 CalFormat::save()
80 */
81 bool save(const Calendar::Ptr &calendar, const QString &fileName);
82
83 /**
84 @copydoc
85 CalFormat::fromString()
86
87 @note The notebook is ignored and the default one is used
88 */
89 bool fromString(const Calendar::Ptr &calendar, const QString &string,
90 bool deleted = false, const QString &notebook = QString());
91
92 /**
93 Parses a string, returning the first iCal component as an Incidence.
94
95 @param string is a QString containing the data to be parsed.
96
97 @return non-zero pointer if the parsing was successful; 0 otherwise.
98 @see fromString(const Calendar::Ptr &, const QString &), fromRawString()
99 */
100 Incidence::Ptr fromString(const QString &string);
101
102 /**
103 Parses a string and fills a RecurrenceRule object with the information.
104
105 @param rule is a pointer to a RecurrenceRule object.
106 @param string is a QString containing the data to be parsed.
107 @return true if successful; false otherwise.
108 */
109 bool fromString(RecurrenceRule *rule, const QString &string);
110
111 /**
112 @copydoc
113 CalFormat::fromRawString()
114 */
115 bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string,
116 bool deleted = false, const QString &notebook = QString());
117
118 /**
119 @copydoc
120 CalFormat::toString()
121 */
122 QString toString(const Calendar::Ptr &calendar,
123 const QString &notebook = QString(), bool deleted = false);
124
125 /**
126 Converts an Incidence to a QString.
127 @param incidence is a pointer to an Incidence object to be converted
128 into a QString.
129
130 @return the QString will be Null if the conversion was unsuccessful.
131 */
132 QString toString(const Incidence::Ptr &incidence);
133
134 /**
135 Converts an Incidence to a QByteArray.
136 @param incidence is a pointer to an Incidence object to be converted
137 into a QByteArray.
138
139 @return the QString will be Null if the conversion was unsuccessful.
140 @since 4.7
141 */
142 QByteArray toRawString(const Incidence::Ptr &incidence);
143
144 /**
145 Converts a RecurrenceRule to a QString.
146 @param rule is a pointer to a RecurrenceRule object to be converted
147 into a QString.
148
149 @return the QString will be Null if the conversion was unsuccessful.
150 */
151 QString toString(RecurrenceRule *rule);
152
153 /**
154 Converts an Incidence to iCalendar formatted text.
155
156 @param incidence is a pointer to an Incidence object to be converted
157 into iCal formatted text.
158 @return the QString will be Null if the conversion was unsuccessful.
159 */
160 QString toICalString(const Incidence::Ptr &incidence);
161
162 /**
163 Creates a scheduling message string for an Incidence.
164
165 @param incidence is a pointer to an IncidenceBase object to be scheduled.
166 @param method is a Scheduler::Method
167
168 @return a QString containing the message if successful; 0 otherwise.
169 */
170 QString createScheduleMessage(const IncidenceBase::Ptr &incidence,
171 iTIPMethod method);
172
173 /**
174 Parses a Calendar scheduling message string into ScheduleMessage object.
175
176 @param calendar is a pointer to a Calendar object associated with the
177 scheduling message.
178 @param string is a QString containing the data to be parsed.
179
180 @return a pointer to a ScheduleMessage object if successful; 0 otherwise.
181 The calling routine may later free the return memory.
182 */
183 ScheduleMessage::Ptr parseScheduleMessage(const Calendar::Ptr &calendar,
184 const QString &string);
185
186 /**
187 Converts a QString into a FreeBusy object.
188
189 @param string is a QString containing the data to be parsed.
190 @return a pointer to a FreeBusy object if successful; 0 otherwise.
191
192 @note Do not attempt to free the FreeBusy memory from the calling routine.
193 */
194 FreeBusy::Ptr parseFreeBusy(const QString &string);
195
196 /**
197 Sets the iCalendar time specification (time zone, etc.).
198 @param timeSpec is the time specification to set.
199 @see timeSpec().
200 */
201 void setTimeSpec(const KDateTime::Spec &timeSpec);
202
203 /**
204 Returns the iCalendar time specification.
205 @see setTimeSpec().
206 */
207 KDateTime::Spec timeSpec() const;
208
209 /**
210 Returns the timezone id string used by the iCalendar; an empty string
211 if the iCalendar does not have a timezone.
212 */
213 QString timeZoneId() const;
214
215protected:
216 /**
217 @copydoc
218 IncidenceBase::virtual_hook()
219 */
220 virtual void virtual_hook(int id, void *data);
221
222private:
223 //@cond PRIVATE
224 Q_DISABLE_COPY(ICalFormat)
225 class Private;
226 Private *const d;
227 //@endcond
228};
229
230}
231
232#endif
233