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