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

KDE's Doxygen guidelines are available online.