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
40namespace KCal {
41
42class 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*/
51class 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