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 <[email protected]>
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 <[email protected]>
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 namespace KCalendarCore
25 {
26 class Exception;
27 
28 /**
29  @brief
30  An abstract base class that provides an interface to various calendar formats.
31 
32  This is the base class for calendar formats. It provides an interface for the
33  generation/interpretation of a textual representation of a calendar.
34 */
35 class KCALENDARCORE_EXPORT CalFormat
36 {
37 public:
38  /**
39  Constructs a new Calendar Format object.
40  */
41  CalFormat();
42 
43  /**
44  Destructor.
45  */
46  virtual ~CalFormat();
47 
48  /**
49  Loads a calendar on disk into the calendar associated with this format.
50 
51  @param calendar is the Calendar to be loaded.
52  @param fileName is the name of the disk file containing the Calendar data.
53 
54  @return true if successful; false otherwise.
55  */
56  virtual bool load(const Calendar::Ptr &calendar, const QString &fileName) = 0;
57 
58  /**
59  Writes the calendar to disk.
60 
61  @param calendar is the Calendar containing the data to be saved.
62  @param fileName is the name of the file to write the calendar data.
63 
64  @return true if successful; false otherwise.
65  */
66  virtual bool save(const Calendar::Ptr &calendar, const QString &fileName) = 0;
67 
68  /**
69  Loads a calendar from a string
70 
71  @param calendar is the Calendar to be loaded.
72  @param string is the QString containing the Calendar data.
73  @param deleted use deleted incidences
74  @param notebook notebook uid
75 
76  @return true if successful; false otherwise.
77  @see fromRawString(), toString().
78  */
79  virtual bool fromString(const Calendar::Ptr &calendar, const QString &string, bool deleted = false, const QString &notebook = QString()) = 0;
80 
81  /**
82  Parses a utf8 encoded string, returning the first iCal component
83  encountered in that string. This is an overload used for efficient
84  reading to avoid utf8 conversions, which are expensive when reading
85  from disk.
86 
87  @param calendar is the Calendar to be loaded.
88  @param string is the QByteArray containing the Calendar data.
89  @param deleted use deleted incidences
90  @param notebook notebook uid
91 
92  @return true if successful; false otherwise.
93  @see fromString(), toString().
94  */
95  virtual bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string, bool deleted = false, const QString &notebook = QString()) = 0;
96 
97  /**
98  Returns the calendar as a string.
99  @param calendar is the Calendar containing the data to be saved.
100  @param notebook uid use only incidences with given notebook
101  @param deleted use deleted incidences
102 
103  @return a QString containing the Calendar data if successful;
104  an empty string otherwise.
105  @see fromString(), fromRawString().
106  */
107  virtual QString toString(const Calendar::Ptr &calendar, const QString &notebook = QString(), bool deleted = false) = 0;
108 
109  /**
110  Clears the exception status.
111  */
112  void clearException();
113 
114  /**
115  Returns an exception, if there is any, containing information about the
116  last error that occurred.
117  */
118  Exception *exception() const;
119 
120  /**
121  Sets the application name for use in unique IDs and error messages,
122  and product ID for incidence PRODID property
123 
124  @param application is a string containing the application name.
125  @param productID is a string containing the product identifier.
126  */
127  static void setApplication(const QString &application, const QString &productID);
128 
129  /**
130  Returns the application name used in unique IDs and error messages.
131  */
132  static const QString &application(); // krazy:exclude=constref
133 
134  /**
135  Returns the our library's PRODID string to write into calendar files.
136  */
137  static const QString &productId(); // krazy:exclude=constref
138 
139  /**
140  Returns the PRODID string loaded from calendar file.
141  @see setLoadedProductId()
142  */
143  QString loadedProductId();
144 
145  /**
146  Creates a unique id string.
147  */
148  static QString createUniqueId();
149 
150  /**
151  Sets an exception that is to be used by the functions of this class
152  to report errors.
153 
154  @param error is a pointer to an Exception which contains the exception.
155  */
156  void setException(Exception *error);
157 
158 protected:
159  /**
160  Sets the PRODID string loaded from calendar file.
161  @param id is a pruduct Id string to set for the calendar file.
162  @see loadedProductId()
163  */
164  void setLoadedProductId(const QString &id);
165 
166  /**
167  @copydoc
168  IncidenceBase::virtual_hook()
169  */
170  virtual void virtual_hook(int id, void *data);
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
typedef Exception
An abstract base class that provides an interface to various calendar formats.
Definition: calformat.h:35
This file is part of the API for handling calendar data and defines the Calendar class.
Exception base class, currently used as a fancy kind of error code and not as an C++ exception...
Definition: exceptions.h:41
Namespace for all KCalendarCore types.
Definition: alarm.h:36
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Sep 26 2021 22:51:52 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.