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 | |
39 | namespace KCalCore { |
40 | |
41 | class FreeBusy; |
42 | class Incidence; |
43 | class IncidenceBase; |
44 | class 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 | */ |
58 | class KCALCORE_EXPORT ICalFormat : public CalFormat |
59 | { |
60 | public: |
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 ¬ebook = 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 ¬ebook = QString()); |
117 | |
118 | /** |
119 | @copydoc |
120 | CalFormat::toString() |
121 | */ |
122 | QString toString(const Calendar::Ptr &calendar, |
123 | const QString ¬ebook = 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 | |
215 | protected: |
216 | /** |
217 | @copydoc |
218 | IncidenceBase::virtual_hook() |
219 | */ |
220 | virtual void virtual_hook(int id, void *data); |
221 | |
222 | private: |
223 | //@cond PRIVATE |
224 | Q_DISABLE_COPY(ICalFormat) |
225 | class Private; |
226 | Private *const d; |
227 | //@endcond |
228 | }; |
229 | |
230 | } |
231 | |
232 | #endif |
233 | |