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 | |
37 | namespace KCalCore { |
38 | |
39 | class 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 | */ |
48 | class KCALCORE_EXPORT CalFormat |
49 | { |
50 | public: |
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 ¬ebook = 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 ¬ebook = 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 ¬ebook = 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 | |
175 | protected: |
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 | |
189 | private: |
190 | //@cond PRIVATE |
191 | Q_DISABLE_COPY(CalFormat) |
192 | class Private; |
193 | Private *const d; |
194 | //@endcond |
195 | }; |
196 | |
197 | } |
198 | |
199 | #endif |
200 | |