File indexing completed on 2024-04-28 11:34:06
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 ICalFormat class. 0012 0013 @author Cornelius Schumacher \<schumacher@kde.org\> 0014 */ 0015 #ifndef KCALCORE_ICALFORMAT_H 0016 #define KCALCORE_ICALFORMAT_H 0017 0018 #include "calformat.h" 0019 #include "freebusy.h" 0020 #include "incidence.h" 0021 #include "kcalendarcore_export.h" 0022 #include "schedulemessage.h" 0023 0024 namespace KCalendarCore 0025 { 0026 class FreeBusy; 0027 class ICalFormatPrivate; 0028 class Incidence; 0029 class IncidenceBase; 0030 class RecurrenceRule; 0031 0032 /** 0033 @brief 0034 iCalendar format implementation. 0035 0036 This class implements the iCalendar format. It provides methods for 0037 loading/saving/converting iCalendar format data into the internal 0038 representation as Calendar and Incidences. 0039 0040 @warning When importing/loading to a Calendar, there is only duplicate 0041 check if those Incidences are loaded into the Calendar. If they are not 0042 loaded it will create duplicates. 0043 */ 0044 class KCALENDARCORE_EXPORT ICalFormat : public CalFormat 0045 { 0046 public: 0047 /** 0048 Constructor a new iCalendar Format object. 0049 */ 0050 ICalFormat(); 0051 0052 /** 0053 Destructor. 0054 */ 0055 ~ICalFormat() override; 0056 0057 /** 0058 @copydoc 0059 CalFormat::load() 0060 */ 0061 bool load(const Calendar::Ptr &calendar, const QString &fileName) override; 0062 0063 /** 0064 @copydoc 0065 CalFormat::save() 0066 */ 0067 bool save(const Calendar::Ptr &calendar, const QString &fileName) override; 0068 0069 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 97) 0070 /** 0071 @copydoc 0072 CalFormat::fromString() 0073 */ 0074 KCALENDARCORE_DEPRECATED_VERSION(5, 97, "use fromString(const Calendar::Ptr &calendar, const QString &string, const QString ¬ebook)") 0075 bool fromString(const Calendar::Ptr &calendar, const QString &string, bool deleted, const QString ¬ebook) override; 0076 #endif 0077 // make CalFromat::fromString(const Calendar::Ptr &calendar, const QString&, const QString&) visible here as well 0078 using CalFormat::fromString; 0079 0080 /** 0081 Parses a string, returning the first iCal component as an Incidence. 0082 0083 @param string is a QString containing the data to be parsed. 0084 0085 @return non-zero pointer if the parsing was successful; 0 otherwise. 0086 @see fromString(const Calendar::Ptr &, const QString &), fromRawString() 0087 */ 0088 Incidence::Ptr fromString(const QString &string); 0089 0090 /** 0091 Parses a bytearray, returning the first iCal component as an Incidence, ignoring timezone information. 0092 0093 This function is significantly faster than fromString by avoiding the overhead of parsing timezone information. 0094 Timezones are instead solely interpreted by using system-timezones. 0095 0096 @param string is a utf8 QByteArray containing the data to be parsed. 0097 0098 @return non-zero pointer if the parsing was successful; 0 otherwise. 0099 @see fromString(const QString &), fromRawString() 0100 */ 0101 Incidence::Ptr readIncidence(const QByteArray &string); 0102 0103 /** 0104 Parses a string and fills a RecurrenceRule object with the information. 0105 0106 @param rule is a pointer to a RecurrenceRule object. 0107 @param string is a QString containing the data to be parsed. 0108 @return true if successful; false otherwise. 0109 */ 0110 Q_REQUIRED_RESULT bool fromString(RecurrenceRule *rule, const QString &string); 0111 0112 /** 0113 Parses a string representation of a duration. 0114 0115 @param duration iCal representation of a duration. 0116 @since 5.95 0117 */ 0118 Q_REQUIRED_RESULT Duration durationFromString(const QString &duration) const; 0119 0120 /** 0121 @copydoc 0122 CalFormat::fromRawString() 0123 */ 0124 Q_REQUIRED_RESULT bool 0125 fromRawString(const Calendar::Ptr &calendar, const QByteArray &string, bool deleted = false, const QString ¬ebook = QString()) override; 0126 0127 /** 0128 @copydoc 0129 CalFormat::toString() 0130 */ 0131 Q_REQUIRED_RESULT QString toString(const Calendar::Ptr &calendar, const QString ¬ebook = QString(), bool deleted = false) override; 0132 0133 /** 0134 Converts an Incidence to a QString. 0135 @param incidence is a pointer to an Incidence object to be converted 0136 into a QString. 0137 0138 @return the QString will be Null if the conversion was unsuccessful. 0139 */ 0140 Q_REQUIRED_RESULT QString toString(const Incidence::Ptr &incidence); 0141 0142 /** 0143 Converts an Incidence to a QByteArray. 0144 @param incidence is a pointer to an Incidence object to be converted 0145 into a QByteArray. 0146 0147 @return the QString will be Null if the conversion was unsuccessful. 0148 @since 4.7 0149 */ 0150 Q_REQUIRED_RESULT QByteArray toRawString(const Incidence::Ptr &incidence); 0151 0152 /** 0153 Converts a RecurrenceRule to a QString. 0154 @param rule is a pointer to a RecurrenceRule object to be converted 0155 into a QString. 0156 0157 @return the QString will be Null if the conversion was unsuccessful. 0158 */ 0159 Q_REQUIRED_RESULT QString toString(RecurrenceRule *rule); 0160 0161 /** 0162 Converts a Duration to an iCal string. 0163 @param duration a Duration object. 0164 @return iCal formatted duration 0165 @since 5.95 0166 */ 0167 Q_REQUIRED_RESULT QString toString(const Duration &duration) const; 0168 0169 /** 0170 Converts an Incidence to iCalendar formatted text. 0171 0172 @param incidence is a pointer to an Incidence object to be converted 0173 into iCal formatted text. 0174 @return the QString will be Null if the conversion was unsuccessful. 0175 */ 0176 Q_REQUIRED_RESULT QString toICalString(const Incidence::Ptr &incidence); 0177 0178 /** 0179 Creates a scheduling message string for an Incidence. 0180 0181 @param incidence is a pointer to an IncidenceBase object to be scheduled. 0182 @param method is a Scheduler::Method 0183 0184 @return a QString containing the message if successful; 0 otherwise. 0185 */ 0186 Q_REQUIRED_RESULT QString createScheduleMessage(const IncidenceBase::Ptr &incidence, iTIPMethod method); 0187 0188 /** 0189 Parses a Calendar scheduling message string into ScheduleMessage object. 0190 0191 @param calendar is a pointer to a Calendar object associated with the 0192 scheduling message. 0193 @param string is a QString containing the data to be parsed. 0194 0195 @return a pointer to a ScheduleMessage object if successful; 0 otherwise. 0196 The calling routine may later free the return memory. 0197 */ 0198 ScheduleMessage::Ptr parseScheduleMessage(const Calendar::Ptr &calendar, const QString &string); 0199 0200 /** 0201 Converts a QString into a FreeBusy object. 0202 0203 @param string is a QString containing the data to be parsed. 0204 @return a pointer to a FreeBusy object if successful; 0 otherwise. 0205 0206 @note Do not attempt to free the FreeBusy memory from the calling routine. 0207 */ 0208 FreeBusy::Ptr parseFreeBusy(const QString &string); 0209 0210 /** 0211 Sets the iCalendar time zone. 0212 @param timeZone is the time zone to set. 0213 @see timeZone(). 0214 */ 0215 void setTimeZone(const QTimeZone &timeZone); 0216 0217 /** 0218 Returns the iCalendar time zone. 0219 @see setTimeZone(). 0220 */ 0221 Q_REQUIRED_RESULT QTimeZone timeZone() const; 0222 0223 /** 0224 Returns the timezone id string used by the iCalendar; an empty string 0225 if the iCalendar does not have a timezone. 0226 */ 0227 Q_REQUIRED_RESULT QByteArray timeZoneId() const; 0228 0229 protected: 0230 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 96) 0231 /** 0232 @copydoc 0233 IncidenceBase::virtual_hook() 0234 */ 0235 void virtual_hook(int id, void *data) override; 0236 #endif 0237 0238 private: 0239 //@cond PRIVATE 0240 Q_DISABLE_COPY(ICalFormat) 0241 Q_DECLARE_PRIVATE(ICalFormat) 0242 #if KCALENDARCORE_BUILD_DEPRECATED_SINCE(5, 96) 0243 void *unused; // former dptr, just kept for ABI compatibility 0244 #endif 0245 //@endcond 0246 }; 0247 0248 } 0249 0250 #endif