File indexing completed on 2024-05-05 16:05:31
0001 /* 0002 This file is part of the kcalcore library. 0003 0004 SPDX-FileCopyrightText: 2001-2003 Cornelius Schumacher <schumacher@kde.org> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 /** 0009 @file 0010 This file is part of the API for handling calendar data and 0011 defines the CalFormat abstract base class. 0012 0013 @author Cornelius Schumacher \<schumacher@kde.org\> 0014 */ 0015 0016 #ifndef KCALCORE_CALFORMAT_H 0017 #define KCALCORE_CALFORMAT_H 0018 0019 #include "calendar.h" 0020 #include "kcalendarcore_export.h" 0021 0022 #include <QString> 0023 0024 #include <memory> 0025 0026 namespace KCalendarCore 0027 { 0028 class CalFormatPrivate; 0029 class Exception; 0030 0031 /** 0032 @brief 0033 An abstract base class that provides an interface to various calendar formats. 0034 0035 This is the base class for calendar formats. It provides an interface for the 0036 generation/interpretation of a textual representation of a calendar. 0037 */ 0038 class KCALENDARCORE_EXPORT CalFormat 0039 { 0040 public: 0041 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 96) 0042 /** 0043 Constructs a new Calendar Format object. 0044 @deprecated since 5.96, unused with the move to hierarchical dptrs. 0045 */ 0046 KCALENDARCORE_DEPRECATED_VERSION(5, 96, "unused, see API docs") 0047 CalFormat(); 0048 #endif 0049 0050 /** 0051 Destructor. 0052 */ 0053 virtual ~CalFormat(); 0054 0055 /** 0056 Loads a calendar on disk into the calendar associated with this format. 0057 0058 @param calendar is the Calendar to be loaded. 0059 @param fileName is the name of the disk file containing the Calendar data. 0060 0061 @return true if successful; false otherwise. 0062 */ 0063 virtual bool load(const Calendar::Ptr &calendar, const QString &fileName) = 0; 0064 0065 /** 0066 Writes the calendar to disk. 0067 0068 @param calendar is the Calendar containing the data to be saved. 0069 @param fileName is the name of the file to write the calendar data. 0070 0071 @return true if successful; false otherwise. 0072 */ 0073 virtual bool save(const Calendar::Ptr &calendar, const QString &fileName) = 0; 0074 0075 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 97) 0076 /** 0077 Loads a calendar from a string. When a notebook is given, incidences are added to this 0078 notebook, otherwise no notebook is associated to loaded incidences. The notebook 0079 should already be added to the calendar, see Calendar::addNotebook(). 0080 0081 @param calendar is the Calendar to be loaded. 0082 @param string is the QString containing the Calendar data. 0083 @param deleted use deleted incidences 0084 @param notebook notebook uid 0085 0086 @return true if successful; false otherwise. 0087 @see fromRawString(), toString(). 0088 0089 @deprecated since 5.97, use fromString(const Calendar::Ptr &calendar, const QString &string, const QString ¬ebook) instead. 0090 */ 0091 KCALENDARCORE_DEPRECATED_VERSION(5, 97, "use fromString(const Calendar::Ptr &calendar, const QString &string, const QString ¬ebook)") 0092 virtual bool fromString(const Calendar::Ptr &calendar, const QString &string, bool deleted, const QString ¬ebook = {}) = 0; 0093 #endif 0094 /** 0095 Loads a calendar from a string. When a notebook is given, incidences are added to this 0096 notebook, otherwise no notebook is associated to loaded incidences. The notebook 0097 should already be added to the calendar, see Calendar::addNotebook(). 0098 0099 @param calendar is the Calendar to be loaded. 0100 @param string is the QString containing the Calendar data. 0101 @param notebook notebook uid 0102 0103 @return true if successful; false otherwise. 0104 @see fromRawString(), toString(). 0105 0106 @since 5.97 0107 */ 0108 bool fromString(const Calendar::Ptr &calendar, const QString &string, const QString ¬ebook = {}); 0109 0110 /** 0111 Parses a utf8 encoded string, returning the first iCal component 0112 encountered in that string. This is an overload used for efficient 0113 reading to avoid utf8 conversions, which are expensive when reading 0114 from disk. 0115 0116 @param calendar is the Calendar to be loaded. 0117 @param string is the QByteArray containing the Calendar data. 0118 @param deleted use deleted incidences 0119 @param notebook notebook uid 0120 0121 @return true if successful; false otherwise. 0122 @see fromString(), toString(). 0123 */ 0124 virtual bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string, bool deleted = false, const QString ¬ebook = QString()) = 0; 0125 0126 /** 0127 Returns the calendar as a string. 0128 @param calendar is the Calendar containing the data to be saved. 0129 @param notebook uid use only incidences with given notebook 0130 @param deleted use deleted incidences 0131 0132 @return a QString containing the Calendar data if successful; 0133 an empty string otherwise. 0134 @see fromString(), fromRawString(). 0135 */ 0136 virtual QString toString(const Calendar::Ptr &calendar, const QString ¬ebook = QString(), bool deleted = false) = 0; 0137 0138 /** 0139 Clears the exception status. 0140 */ 0141 void clearException(); 0142 0143 /** 0144 Returns an exception, if there is any, containing information about the 0145 last error that occurred. 0146 */ 0147 Exception *exception() const; 0148 0149 /** 0150 Sets the application name for use in unique IDs and error messages, 0151 and product ID for incidence PRODID property 0152 0153 @param application is a string containing the application name. 0154 @param productID is a string containing the product identifier. 0155 */ 0156 static void setApplication(const QString &application, const QString &productID); 0157 0158 /** 0159 Returns the application name used in unique IDs and error messages. 0160 */ 0161 static const QString &application(); // krazy:exclude=constref 0162 0163 /** 0164 Returns the our library's PRODID string to write into calendar files. 0165 */ 0166 static const QString &productId(); // krazy:exclude=constref 0167 0168 /** 0169 Returns the PRODID string loaded from calendar file. 0170 @see setLoadedProductId() 0171 */ 0172 QString loadedProductId(); 0173 0174 /** 0175 Creates a unique id string. 0176 */ 0177 static QString createUniqueId(); 0178 0179 /** 0180 Sets an exception that is to be used by the functions of this class 0181 to report errors. 0182 0183 @param error is a pointer to an Exception which contains the exception. 0184 */ 0185 void setException(Exception *error); 0186 0187 protected: 0188 /** 0189 Sets the PRODID string loaded from calendar file. 0190 @param id is a pruduct Id string to set for the calendar file. 0191 @see loadedProductId() 0192 */ 0193 void setLoadedProductId(const QString &id); 0194 0195 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 96) 0196 /** 0197 @copydoc 0198 IncidenceBase::virtual_hook() 0199 @deprecated since 5.96 unused, hierarchical dptrs provide the same ABI compatible extension vector 0200 as this class is not intended to be inherited externally. 0201 */ 0202 KCALENDARCORE_DEPRECATED_VERSION(5, 96, "unused, see API docs") 0203 virtual void virtual_hook(int id, void *data); 0204 #endif 0205 0206 //@cond PRIVATE 0207 KCALENDARCORE_NO_EXPORT explicit CalFormat(CalFormatPrivate *dd); 0208 std::unique_ptr<CalFormatPrivate> d_ptr; 0209 //@endcond 0210 0211 private: 0212 //@cond PRIVATE 0213 Q_DISABLE_COPY(CalFormat) 0214 Q_DECLARE_PRIVATE(CalFormat) 0215 //@endcond 0216 }; 0217 0218 } 0219 0220 #endif