KCalendarCore

icalformat.h
Go to the documentation of this file.
1/*
2 This file is part of the kcalcore library.
3
4 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8/**
9 @file
10 This file is part of the API for handling calendar data and
11 defines the ICalFormat class.
12
13 @author Cornelius Schumacher <schumacher@kde.org>
14*/
15#ifndef KCALCORE_ICALFORMAT_H
16#define KCALCORE_ICALFORMAT_H
17
18#include "calformat.h"
19#include "freebusy.h"
20#include "incidence.h"
21#include "kcalendarcore_export.h"
22#include "schedulemessage.h"
23
24namespace KCalendarCore
25{
26class FreeBusy;
27class ICalFormatPrivate;
28class Incidence;
29class IncidenceBase;
30class RecurrenceRule;
31
32/**
33 @brief
34 iCalendar format implementation.
35
36 This class implements the iCalendar format. It provides methods for
37 loading/saving/converting iCalendar format data into the internal
38 representation as Calendar and Incidences.
39
40 @warning When importing/loading to a Calendar, there is only duplicate
41 check if those Incidences are loaded into the Calendar. If they are not
42 loaded it will create duplicates.
43*/
44class KCALENDARCORE_EXPORT ICalFormat : public CalFormat
45{
46public:
47 /**
48 Constructor a new iCalendar Format object.
49 */
50 ICalFormat();
51
52 /**
53 Destructor.
54 */
55 ~ICalFormat() override;
56
57 /**
58 @copydoc
59 CalFormat::load()
60 */
61 bool load(const Calendar::Ptr &calendar, const QString &fileName) override;
62
63 /**
64 @copydoc
65 CalFormat::save()
66 */
67 bool save(const Calendar::Ptr &calendar, const QString &fileName) override;
68
69 // make CalFromat::fromString(const Calendar::Ptr &calendar, const QString&, const QString&) visible here as well
70 using CalFormat::fromString;
71
72 /**
73 Parses a string, returning the first iCal component as an Incidence.
74
75 @param string is a QString containing the data to be parsed.
76
77 @return non-zero pointer if the parsing was successful; 0 otherwise.
78 @see fromString(const Calendar::Ptr &, const QString &), fromRawString()
79 */
80 Incidence::Ptr fromString(const QString &string);
81
82 /**
83 Parses a bytearray, returning the first iCal component as an Incidence, ignoring timezone information.
84
85 This function is significantly faster than fromString by avoiding the overhead of parsing timezone information.
86 Timezones are instead solely interpreted by using system-timezones.
87
88 @param string is a utf8 QByteArray containing the data to be parsed.
89
90 @return non-zero pointer if the parsing was successful; 0 otherwise.
91 @see fromString(const QString &), fromRawString()
92 */
93 Incidence::Ptr readIncidence(const QByteArray &string);
94
95 /**
96 Parses a string and fills a RecurrenceRule object with the information.
97
98 @param rule is a pointer to a RecurrenceRule object.
99 @param string is a QString containing the data to be parsed.
100 @return true if successful; false otherwise.
101 */
102 Q_REQUIRED_RESULT bool fromString(RecurrenceRule *rule, const QString &string);
103
104 /**
105 Parses a string representation of a duration.
106
107 @param duration iCal representation of a duration.
108 @since 5.95
109 */
110 Q_REQUIRED_RESULT Duration durationFromString(const QString &duration) const;
111
112 /**
113 @copydoc
114 CalFormat::fromRawString()
115 */
116 Q_REQUIRED_RESULT bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string) override;
117
118 /**
119 @copydoc
120 CalFormat::toString()
121 */
122 Q_REQUIRED_RESULT QString toString(const Calendar::Ptr &calendar) override;
123
124 /**
125 Converts an Incidence to a QString.
126 @param incidence is a pointer to an Incidence object to be converted
127 into a QString.
128
129 @return the QString will be Null if the conversion was unsuccessful.
130 */
131 Q_REQUIRED_RESULT QString toString(const Incidence::Ptr &incidence);
132
133 /**
134 Converts an Incidence to a QByteArray.
135 @param incidence is a pointer to an Incidence object to be converted
136 into a QByteArray.
137
138 @return the QString will be Null if the conversion was unsuccessful.
139 @since 4.7
140 */
141 Q_REQUIRED_RESULT QByteArray toRawString(const Incidence::Ptr &incidence);
142
143 /**
144 Converts a RecurrenceRule to a QString.
145 @param rule is a pointer to a RecurrenceRule object to be converted
146 into a QString.
147
148 @return the QString will be Null if the conversion was unsuccessful.
149 */
150 Q_REQUIRED_RESULT QString toString(RecurrenceRule *rule);
151
152 /**
153 Converts a Duration to an iCal string.
154 @param duration a Duration object.
155 @return iCal formatted duration
156 @since 5.95
157 */
158 Q_REQUIRED_RESULT QString toString(const Duration &duration) const;
159
160 /**
161 Converts an Incidence to iCalendar formatted text.
162
163 @param incidence is a pointer to an Incidence object to be converted
164 into iCal formatted text.
165 @return the QString will be Null if the conversion was unsuccessful.
166 */
167 Q_REQUIRED_RESULT QString toICalString(const Incidence::Ptr &incidence);
168
169 /**
170 Creates a scheduling message string for an Incidence.
171
172 @param incidence is a pointer to an IncidenceBase object to be scheduled.
173 @param method is a Scheduler::Method
174
175 @return a QString containing the message if successful; 0 otherwise.
176 */
177 Q_REQUIRED_RESULT QString createScheduleMessage(const IncidenceBase::Ptr &incidence, iTIPMethod method);
178
179 /**
180 Parses a Calendar scheduling message string into ScheduleMessage object.
181
182 @param calendar is a pointer to a Calendar object associated with the
183 scheduling message.
184 @param string is a QString containing the data to be parsed.
185
186 @return a pointer to a ScheduleMessage object if successful; 0 otherwise.
187 The calling routine may later free the return memory.
188 */
189 ScheduleMessage::Ptr parseScheduleMessage(const Calendar::Ptr &calendar, const QString &string);
190
191 /**
192 Converts a QString into a FreeBusy object.
193
194 @param string is a QString containing the data to be parsed.
195 @return a pointer to a FreeBusy object if successful; 0 otherwise.
196
197 @note Do not attempt to free the FreeBusy memory from the calling routine.
198 */
199 FreeBusy::Ptr parseFreeBusy(const QString &string);
200
201 /**
202 Sets the iCalendar time zone.
203 @param timeZone is the time zone to set.
204 @see timeZone().
205 */
206 void setTimeZone(const QTimeZone &timeZone);
207
208 /**
209 Returns the iCalendar time zone.
210 @see setTimeZone().
211 */
212 Q_REQUIRED_RESULT QTimeZone timeZone() const;
213
214 /**
215 Returns the timezone id string used by the iCalendar; an empty string
216 if the iCalendar does not have a timezone.
217 */
218 Q_REQUIRED_RESULT QByteArray timeZoneId() const;
219
220private:
221 //@cond PRIVATE
222 Q_DISABLE_COPY(ICalFormat)
223 Q_DECLARE_PRIVATE(ICalFormat)
224 //@endcond
225};
226
227}
228
229#endif
This file is part of the API for handling calendar data and defines the CalFormat abstract base class...
An abstract base class that provides an interface to various calendar formats.
Definition calformat.h:39
Represents a span of time measured in seconds or days.
Definition duration.h:44
iCalendar format implementation.
Definition icalformat.h:45
This class represents a recurrence rule for a calendar incidence.
This file is part of the API for handling calendar data and defines the FreeBusy class.
This file is part of the API for handling calendar data and defines the Incidence class.
Namespace for all KCalendarCore types.
Definition alarm.h:37
iTIPMethod
iTIP methods.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:39:07 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.