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 CalFormat abstract base class.
25
26 @author Cornelius Schumacher \<schumacher@kde.org\>
27*/
28
29#ifndef KCALCORE_CALFORMAT_H
30#define KCALCORE_CALFORMAT_H
31
32#include "kcalcore_export.h"
33#include "calendar.h"
34
35#include <QtCore/QString>
36
37namespace KCalCore {
38
39class Exception;
40
41/**
42 @brief
43 An abstract base class that provides an interface to various calendar formats.
44
45 This is the base class for calendar formats. It provides an interface for the
46 generation/interpretation of a textual representation of a calendar.
47*/
48class KCALCORE_EXPORT CalFormat
49{
50public:
51 /**
52 Constructs a new Calendar Format object.
53 */
54 CalFormat();
55
56 /**
57 Destructor.
58 */
59 virtual ~CalFormat();
60
61 /**
62 Loads a calendar on disk into the calendar associated with this format.
63
64 @param calendar is the Calendar to be loaded.
65 @param fileName is the name of the disk file containing the Calendar data.
66
67 @return true if successful; false otherwise.
68 */
69 virtual bool load(const Calendar::Ptr &calendar, const QString &fileName) = 0;
70
71 /**
72 Writes the calendar to disk.
73
74 @param calendar is the Calendar containing the data to be saved.
75 @param fileName is the name of the file to write the calendar data.
76
77 @return true if successful; false otherwise.
78 */
79 virtual bool save(const Calendar::Ptr &calendar, const QString &fileName) = 0;
80
81 /**
82 Loads a calendar from a string
83
84 @param calendar is the Calendar to be loaded.
85 @param string is the QString containing the Calendar data.
86 @param deleted use deleted incidences
87 @param notebook notebook uid
88
89 @return true if successful; false otherwise.
90 @see fromRawString(), toString().
91 */
92 virtual bool fromString(const Calendar::Ptr &calendar, const QString &string,
93 bool deleted = false, const QString &notebook = QString()) = 0;
94
95 /**
96 Parses a utf8 encoded string, returning the first iCal component
97 encountered in that string. This is an overload used for efficient
98 reading to avoid utf8 conversions, which are expensive when reading
99 from disk.
100
101 @param calendar is the Calendar to be loaded.
102 @param string is the QByteArray containing the Calendar data.
103 @param deleted use deleted incidences
104 @param notebook notebook uid
105
106 @return true if successful; false otherwise.
107 @see fromString(), toString().
108 */
109 virtual bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string,
110 bool deleted = false, const QString &notebook = QString()) = 0;
111
112 /**
113 Returns the calendar as a string.
114 @param calendar is the Calendar containing the data to be saved.
115 @param notebook uid use only incidences with given notebook
116 @param deleted use deleted incidences
117
118 @return a QString containing the Calendar data if successful;
119 an empty string otherwise.
120 @see fromString(), fromRawString().
121 */
122 virtual QString toString(const Calendar::Ptr &calendar,
123 const QString &notebook = QString(), bool deleted = false) = 0;
124
125 /**
126 Clears the exception status.
127 */
128 void clearException();
129
130 /**
131 Returns an exception, if there is any, containing information about the
132 last error that occurred.
133 */
134 Exception *exception() const;
135
136 /**
137 Sets the application name for use in unique IDs and error messages,
138 and product ID for incidence PRODID property
139
140 @param application is a string containing the application name.
141 @param productID is a string containing the product identifier.
142 */
143 static void setApplication(const QString &application,
144 const QString &productID);
145
146 /**
147 Returns the application name used in unique IDs and error messages.
148 */
149 static const QString &application(); //krazy:exclude=constref
150
151 /**
152 Returns the our library's PRODID string to write into calendar files.
153 */
154 static const QString &productId(); //krazy:exclude=constref
155
156 /**
157 Returns the PRODID string loaded from calendar file.
158 @see setLoadedProductId()
159 */
160 QString loadedProductId();
161
162 /**
163 Creates a unique id string.
164 */
165 static QString createUniqueId();
166
167 /**
168 Sets an exception that is to be used by the functions of this class
169 to report errors.
170
171 @param error is a pointer to an Exception which contains the exception.
172 */
173 void setException(Exception *error);
174
175protected:
176 /**
177 Sets the PRODID string loaded from calendar file.
178 @param id is a pruduct Id string to set for the calendar file.
179 @see loadedProductId()
180 */
181 void setLoadedProductId(const QString &id);
182
183 /**
184 @copydoc
185 IncidenceBase::virtual_hook()
186 */
187 virtual void virtual_hook(int id, void *data);
188
189private:
190 //@cond PRIVATE
191 Q_DISABLE_COPY(CalFormat)
192 class Private;
193 Private *const d;
194 //@endcond
195};
196
197}
198
199#endif
200