KCalendarCore

calformat.h
Go to the documentation of this file.
1/*
2 This file is part of the kcalcore library.
3
4 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8/**
9 @file
10 This file is part of the API for handling calendar data and
11 defines the CalFormat abstract base class.
12
13 @author Cornelius Schumacher <schumacher@kde.org>
14*/
15
16#ifndef KCALCORE_CALFORMAT_H
17#define KCALCORE_CALFORMAT_H
18
19#include "calendar.h"
20#include "kcalendarcore_export.h"
21
22#include <QString>
23
24#include <memory>
25
26namespace KCalendarCore
27{
28class CalFormatPrivate;
29class Exception;
30
31/**
32 @brief
33 An abstract base class that provides an interface to various calendar formats.
34
35 This is the base class for calendar formats. It provides an interface for the
36 generation/interpretation of a textual representation of a calendar.
37*/
38class KCALENDARCORE_EXPORT CalFormat
39{
40public:
41 /**
42 Destructor.
43 */
44 virtual ~CalFormat();
45
46 /**
47 Loads a calendar on disk into the calendar associated with this format.
48
49 @param calendar is the Calendar to be loaded.
50 @param fileName is the name of the disk file containing the Calendar data.
51
52 @return true if successful; false otherwise.
53 */
54 virtual bool load(const Calendar::Ptr &calendar, const QString &fileName) = 0;
55
56 /**
57 Writes the calendar to disk.
58
59 @param calendar is the Calendar containing the data to be saved.
60 @param fileName is the name of the file to write the calendar data.
61
62 @return true if successful; false otherwise.
63 */
64 virtual bool save(const Calendar::Ptr &calendar, const QString &fileName) = 0;
65
66 /**
67 Loads a calendar from a string.
68
69 @param calendar is the Calendar to be loaded.
70 @param string is the QString containing the Calendar data.
71
72 @return true if successful; false otherwise.
73 @see fromRawString(), toString().
74
75 @since 5.97
76 */
77 bool fromString(const Calendar::Ptr &calendar, const QString &string);
78
79 /**
80 Parses a utf8 encoded string, returning the first iCal component
81 encountered in that string. This is an overload used for efficient
82 reading to avoid utf8 conversions, which are expensive when reading
83 from disk.
84
85 @param calendar is the Calendar to be loaded.
86 @param string is the QByteArray containing the Calendar data.
87
88 @return true if successful; false otherwise.
89 @see fromString(), toString().
90 */
91 virtual bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string) = 0;
92
93 /**
94 Returns the calendar as a string.
95 @param calendar is the Calendar containing the data to be saved.
96
97 @return a QString containing the Calendar data if successful;
98 an empty string otherwise.
99 @see fromString(), fromRawString().
100 */
101 virtual QString toString(const Calendar::Ptr &calendar) = 0;
102
103 /**
104 Clears the exception status.
105 */
106 void clearException();
107
108 /**
109 Returns an exception, if there is any, containing information about the
110 last error that occurred.
111 */
112 Exception *exception() const;
113
114 /**
115 Sets the application name for use in unique IDs and error messages,
116 and product ID for incidence PRODID property
117
118 @param application is a string containing the application name.
119 @param productID is a string containing the product identifier.
120 */
121 static void setApplication(const QString &application, const QString &productID);
122
123 /**
124 Returns the application name used in unique IDs and error messages.
125 */
126 static const QString &application(); // krazy:exclude=constref
127
128 /**
129 Returns the our library's PRODID string to write into calendar files.
130 */
131 static const QString &productId(); // krazy:exclude=constref
132
133 /**
134 Returns the PRODID string loaded from calendar file.
135 @see setLoadedProductId()
136 */
137 QString loadedProductId();
138
139 /**
140 Creates a unique id string.
141 */
142 static QString createUniqueId();
143
144 /**
145 Sets an exception that is to be used by the functions of this class
146 to report errors.
147
148 @param error is a pointer to an Exception which contains the exception.
149 */
150 void setException(Exception *error);
151
152protected:
153 /**
154 Sets the PRODID string loaded from calendar file.
155 @param id is a pruduct Id string to set for the calendar file.
156 @see loadedProductId()
157 */
158 void setLoadedProductId(const QString &id);
159
160 //@cond PRIVATE
161 KCALENDARCORE_NO_EXPORT explicit CalFormat(CalFormatPrivate *dd);
162 std::unique_ptr<CalFormatPrivate> d_ptr;
163 //@endcond
164
165private:
166 //@cond PRIVATE
167 Q_DISABLE_COPY(CalFormat)
168 Q_DECLARE_PRIVATE(CalFormat)
169 //@endcond
170};
171
172}
173
174#endif
This file is part of the API for handling calendar data and defines the Calendar class.
An abstract base class that provides an interface to various calendar formats.
Definition calformat.h:39
virtual QString toString(const Calendar::Ptr &calendar)=0
Returns the calendar as a string.
virtual bool load(const Calendar::Ptr &calendar, const QString &fileName)=0
Loads a calendar on disk into the calendar associated with this format.
virtual bool save(const Calendar::Ptr &calendar, const QString &fileName)=0
Writes the calendar to disk.
virtual bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string)=0
Parses a utf8 encoded string, returning the first iCal component encountered in that string.
Exception base class, currently used as a fancy kind of error code and not as an C++ exception.
Definition exceptions.h:42
Namespace for all KCalendarCore types.
Definition alarm.h:37
typedef Exception
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:39:07 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.