File indexing completed on 2024-04-21 03:52:45
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 /** 0042 Destructor. 0043 */ 0044 virtual ~CalFormat(); 0045 0046 /** 0047 Loads a calendar on disk into the calendar associated with this format. 0048 0049 @param calendar is the Calendar to be loaded. 0050 @param fileName is the name of the disk file containing the Calendar data. 0051 0052 @return true if successful; false otherwise. 0053 */ 0054 virtual bool load(const Calendar::Ptr &calendar, const QString &fileName) = 0; 0055 0056 /** 0057 Writes the calendar to disk. 0058 0059 @param calendar is the Calendar containing the data to be saved. 0060 @param fileName is the name of the file to write the calendar data. 0061 0062 @return true if successful; false otherwise. 0063 */ 0064 virtual bool save(const Calendar::Ptr &calendar, const QString &fileName) = 0; 0065 0066 /** 0067 Loads a calendar from a string. 0068 0069 @param calendar is the Calendar to be loaded. 0070 @param string is the QString containing the Calendar data. 0071 0072 @return true if successful; false otherwise. 0073 @see fromRawString(), toString(). 0074 0075 @since 5.97 0076 */ 0077 bool fromString(const Calendar::Ptr &calendar, const QString &string); 0078 0079 /** 0080 Parses a utf8 encoded string, returning the first iCal component 0081 encountered in that string. This is an overload used for efficient 0082 reading to avoid utf8 conversions, which are expensive when reading 0083 from disk. 0084 0085 @param calendar is the Calendar to be loaded. 0086 @param string is the QByteArray containing the Calendar data. 0087 0088 @return true if successful; false otherwise. 0089 @see fromString(), toString(). 0090 */ 0091 virtual bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string) = 0; 0092 0093 /** 0094 Returns the calendar as a string. 0095 @param calendar is the Calendar containing the data to be saved. 0096 0097 @return a QString containing the Calendar data if successful; 0098 an empty string otherwise. 0099 @see fromString(), fromRawString(). 0100 */ 0101 virtual QString toString(const Calendar::Ptr &calendar) = 0; 0102 0103 /** 0104 Clears the exception status. 0105 */ 0106 void clearException(); 0107 0108 /** 0109 Returns an exception, if there is any, containing information about the 0110 last error that occurred. 0111 */ 0112 Exception *exception() const; 0113 0114 /** 0115 Sets the application name for use in unique IDs and error messages, 0116 and product ID for incidence PRODID property 0117 0118 @param application is a string containing the application name. 0119 @param productID is a string containing the product identifier. 0120 */ 0121 static void setApplication(const QString &application, const QString &productID); 0122 0123 /** 0124 Returns the application name used in unique IDs and error messages. 0125 */ 0126 static const QString &application(); // krazy:exclude=constref 0127 0128 /** 0129 Returns the our library's PRODID string to write into calendar files. 0130 */ 0131 static const QString &productId(); // krazy:exclude=constref 0132 0133 /** 0134 Returns the PRODID string loaded from calendar file. 0135 @see setLoadedProductId() 0136 */ 0137 QString loadedProductId(); 0138 0139 /** 0140 Creates a unique id string. 0141 */ 0142 static QString createUniqueId(); 0143 0144 /** 0145 Sets an exception that is to be used by the functions of this class 0146 to report errors. 0147 0148 @param error is a pointer to an Exception which contains the exception. 0149 */ 0150 void setException(Exception *error); 0151 0152 protected: 0153 /** 0154 Sets the PRODID string loaded from calendar file. 0155 @param id is a pruduct Id string to set for the calendar file. 0156 @see loadedProductId() 0157 */ 0158 void setLoadedProductId(const QString &id); 0159 0160 //@cond PRIVATE 0161 KCALENDARCORE_NO_EXPORT explicit CalFormat(CalFormatPrivate *dd); 0162 std::unique_ptr<CalFormatPrivate> d_ptr; 0163 //@endcond 0164 0165 private: 0166 //@cond PRIVATE 0167 Q_DISABLE_COPY(CalFormat) 0168 Q_DECLARE_PRIVATE(CalFormat) 0169 //@endcond 0170 }; 0171 0172 } 0173 0174 #endif