1/*
2 This file is part of the kcal 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
29#ifndef KCAL_ICALFORMAT_H
30#define KCAL_ICALFORMAT_H
31
32#include "calformat.h"
33#include "scheduler.h"
34
35#include <kdatetime.h>
36
37#include <QtCore/QString>
38#include <QtCore/QByteArray>
39
40namespace KCal {
41
42class FreeBusy;
43
44/**
45 @brief
46 iCalendar format implementation.
47
48 This class implements the iCalendar format. It provides methods for
49 loading/saving/converting iCalendar format data into the internal
50 representation as Calendar and Incidences.
51*/
52class KCAL_DEPRECATED_EXPORT ICalFormat : public CalFormat
53{
54 public:
55 /**
56 Constructor a new iCalendar Format object.
57 */
58 ICalFormat();
59
60 /**
61 Destructor.
62 */
63 virtual ~ICalFormat();
64
65 /**
66 @copydoc
67 CalFormat::load()
68 */
69 bool load( Calendar *calendar, const QString &fileName );
70
71 /**
72 @copydoc
73 CalFormat::save()
74 */
75 bool save( Calendar *calendar, const QString &fileName );
76
77 /**
78 @copydoc
79 CalFormat::fromString()
80 */
81 bool fromString( Calendar *calendar, const QString &string );
82
83 /**
84 Parses a string, returning the first iCal component as an Incidence.
85
86 @param string is a QString containing the data to be parsed.
87
88 @return non-zero pointer if the parsing was successful; 0 otherwise.
89 @see fromString(Calendar *, const QString &), fromRawString()
90 */
91 Incidence *fromString( const QString &string );
92
93 /**
94 Parses a string and fills a RecurrenceRule object with the information.
95
96 @param rule is a pointer to a RecurrenceRule object.
97 @param string is a QString containing the data to be parsed.
98 @return true if successful; false otherwise.
99 */
100 bool fromString ( RecurrenceRule *rule, const QString &string );
101
102 /**
103 @copydoc
104 CalFormat::fromRawString()
105 */
106 bool fromRawString( Calendar *calendar, const QByteArray &string );
107
108 /**
109 @copydoc
110 CalFormat::toString()
111 */
112 QString toString( Calendar *calendar );
113
114 /**
115 Converts an Incidence to a QString.
116 @param incidence is a pointer to an Incidence object to be converted
117 into a QString.
118
119 @return the QString will be Null if the conversion was unsuccessful.
120 */
121 QString toString( Incidence *incidence );
122
123 /**
124 Converts a RecurrenceRule to a QString.
125 @param rule is a pointer to a RecurrenceRule object to be converted
126 into a QString.
127
128 @return the QString will be Null if the conversion was unsuccessful.
129 */
130 QString toString( RecurrenceRule *rule );
131
132 /**
133 Converts an Incidence to iCalendar formatted text.
134
135 @param incidence is a pointer to an Incidence object to be converted
136 into iCal formatted text.
137 @return the QString will be Null if the conversion was unsuccessful.
138 */
139 QString toICalString( Incidence *incidence );
140
141 /**
142 Creates a scheduling message string for an Incidence.
143
144 @param incidence is a pointer to an IncidenceBase object to be scheduled.
145 @param method is a Scheduler::Method
146
147 @return a QString containing the message if successful; 0 otherwise.
148 */
149 QString createScheduleMessage( IncidenceBase *incidence,
150 iTIPMethod method );
151
152 /**
153 Parses a Calendar scheduling message string into ScheduleMessage object.
154
155 @param calendar is a pointer to a Calendar object associated with the
156 scheduling message.
157 @param string is a QString containing the data to be parsed.
158
159 @return a pointer to a ScheduleMessage object if successful; 0 otherwise.
160 The calling routine may later free the return memory.
161 */
162 ScheduleMessage *parseScheduleMessage( Calendar *calendar, const QString &string );
163
164 /**
165 Converts a QString into a FreeBusy object.
166
167 @param string is a QString containing the data to be parsed.
168 @return a pointer to a FreeBusy object if successful; 0 otherwise.
169
170 @note Do not attempt to free the FreeBusy memory from the calling routine.
171 */
172 FreeBusy *parseFreeBusy( const QString &string );
173
174 /**
175 Sets the iCalendar time specification (time zone, etc.).
176 @param timeSpec is the time specification to set.
177 @see timeSpec().
178 */
179 void setTimeSpec( const KDateTime::Spec &timeSpec );
180
181 /**
182 Returns the iCalendar time specification.
183 @see setTimeSpec().
184 */
185 KDateTime::Spec timeSpec() const;
186
187 /**
188 Returns the timezone id string used by the iCalendar; an empty string
189 if the iCalendar does not have a timezone.
190 */
191 QString timeZoneId() const;
192
193 private:
194 //@cond PRIVATE
195 Q_DISABLE_COPY( ICalFormat )
196 class Private;
197 Private *const d;
198 //@endcond
199};
200
201}
202
203#endif
204