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 #include <memory>
25 
26 namespace KCalendarCore
27 {
28 class CalFormatPrivate;
29 class 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 */
38 class KCALENDARCORE_EXPORT CalFormat
39 {
40 public:
41 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 96)
42  /**
43  Constructs a new Calendar Format object.
44  @deprecated since 5.96, unused with the move to hierarchical dptrs.
45  */
46  KCALENDARCORE_DEPRECATED_VERSION(5, 96, "unused, see API docs")
47  CalFormat();
48 #endif
49 
50  /**
51  Destructor.
52  */
53  virtual ~CalFormat();
54 
55  /**
56  Loads a calendar on disk into the calendar associated with this format.
57 
58  @param calendar is the Calendar to be loaded.
59  @param fileName is the name of the disk file containing the Calendar data.
60 
61  @return true if successful; false otherwise.
62  */
63  virtual bool load(const Calendar::Ptr &calendar, const QString &fileName) = 0;
64 
65  /**
66  Writes the calendar to disk.
67 
68  @param calendar is the Calendar containing the data to be saved.
69  @param fileName is the name of the file to write the calendar data.
70 
71  @return true if successful; false otherwise.
72  */
73  virtual bool save(const Calendar::Ptr &calendar, const QString &fileName) = 0;
74 
75 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 97)
76  /**
77  Loads a calendar from a string. When a notebook is given, incidences are added to this
78  notebook, otherwise no notebook is associated to loaded incidences. The notebook
79  should already be added to the calendar, see Calendar::addNotebook().
80 
81  @param calendar is the Calendar to be loaded.
82  @param string is the QString containing the Calendar data.
83  @param deleted use deleted incidences
84  @param notebook notebook uid
85 
86  @return true if successful; false otherwise.
87  @see fromRawString(), toString().
88 
89  @deprecated since 5.97, use fromString(const Calendar::Ptr &calendar, const QString &string, const QString &notebook) instead.
90  */
91  KCALENDARCORE_DEPRECATED_VERSION(5, 97, "use fromString(const Calendar::Ptr &calendar, const QString &string, const QString &notebook)")
92  virtual bool fromString(const Calendar::Ptr &calendar, const QString &string, bool deleted, const QString &notebook = {}) = 0;
93 #endif
94  /**
95  Loads a calendar from a string. When a notebook is given, incidences are added to this
96  notebook, otherwise no notebook is associated to loaded incidences. The notebook
97  should already be added to the calendar, see Calendar::addNotebook().
98 
99  @param calendar is the Calendar to be loaded.
100  @param string is the QString containing the Calendar data.
101  @param notebook notebook uid
102 
103  @return true if successful; false otherwise.
104  @see fromRawString(), toString().
105 
106  @since 5.97
107  */
108  bool fromString(const Calendar::Ptr &calendar, const QString &string, const QString &notebook = {});
109 
110  /**
111  Parses a utf8 encoded string, returning the first iCal component
112  encountered in that string. This is an overload used for efficient
113  reading to avoid utf8 conversions, which are expensive when reading
114  from disk.
115 
116  @param calendar is the Calendar to be loaded.
117  @param string is the QByteArray containing the Calendar data.
118  @param deleted use deleted incidences
119  @param notebook notebook uid
120 
121  @return true if successful; false otherwise.
122  @see fromString(), toString().
123  */
124  virtual bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string, bool deleted = false, const QString &notebook = QString()) = 0;
125 
126  /**
127  Returns the calendar as a string.
128  @param calendar is the Calendar containing the data to be saved.
129  @param notebook uid use only incidences with given notebook
130  @param deleted use deleted incidences
131 
132  @return a QString containing the Calendar data if successful;
133  an empty string otherwise.
134  @see fromString(), fromRawString().
135  */
136  virtual QString toString(const Calendar::Ptr &calendar, const QString &notebook = QString(), bool deleted = false) = 0;
137 
138  /**
139  Clears the exception status.
140  */
141  void clearException();
142 
143  /**
144  Returns an exception, if there is any, containing information about the
145  last error that occurred.
146  */
147  Exception *exception() const;
148 
149  /**
150  Sets the application name for use in unique IDs and error messages,
151  and product ID for incidence PRODID property
152 
153  @param application is a string containing the application name.
154  @param productID is a string containing the product identifier.
155  */
156  static void setApplication(const QString &application, const QString &productID);
157 
158  /**
159  Returns the application name used in unique IDs and error messages.
160  */
161  static const QString &application(); // krazy:exclude=constref
162 
163  /**
164  Returns the our library's PRODID string to write into calendar files.
165  */
166  static const QString &productId(); // krazy:exclude=constref
167 
168  /**
169  Returns the PRODID string loaded from calendar file.
170  @see setLoadedProductId()
171  */
172  QString loadedProductId();
173 
174  /**
175  Creates a unique id string.
176  */
177  static QString createUniqueId();
178 
179  /**
180  Sets an exception that is to be used by the functions of this class
181  to report errors.
182 
183  @param error is a pointer to an Exception which contains the exception.
184  */
185  void setException(Exception *error);
186 
187 protected:
188  /**
189  Sets the PRODID string loaded from calendar file.
190  @param id is a pruduct Id string to set for the calendar file.
191  @see loadedProductId()
192  */
193  void setLoadedProductId(const QString &id);
194 
195 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 96)
196  /**
197  @copydoc
198  IncidenceBase::virtual_hook()
199  @deprecated since 5.96 unused, hierarchical dptrs provide the same ABI compatible extension vector
200  as this class is not intended to be inherited externally.
201  */
202  KCALENDARCORE_DEPRECATED_VERSION(5, 96, "unused, see API docs")
203  virtual void virtual_hook(int id, void *data);
204 #endif
205 
206  //@cond PRIVATE
207  KCALENDARCORE_NO_EXPORT explicit CalFormat(CalFormatPrivate *dd);
208  std::unique_ptr<CalFormatPrivate> d_ptr;
209  //@endcond
210 
211 private:
212  //@cond PRIVATE
213  Q_DISABLE_COPY(CalFormat)
214  Q_DECLARE_PRIVATE(CalFormat)
215  //@endcond
216 };
217 
218 }
219 
220 #endif
Namespace for all KCalendarCore types.
Definition: alarm.h:36
virtual bool setException(ScriptableExtension *callerPrincipal, const QString &message)
Exception base class, currently used as a fancy kind of error code and not as an C++ exception.
Definition: exceptions.h:41
typedef Exception
An abstract base class that provides an interface to various calendar formats.
Definition: calformat.h:38
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Sep 21 2023 04:00:45 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.