File indexing completed on 2024-03-24 03:55:34
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 // make CalFromat::fromString(const Calendar::Ptr &calendar, const QString&, const QString&) visible here as well 0070 using CalFormat::fromString; 0071 0072 /** 0073 Parses a string, returning the first iCal component as an Incidence. 0074 0075 @param string is a QString containing the data to be parsed. 0076 0077 @return non-zero pointer if the parsing was successful; 0 otherwise. 0078 @see fromString(const Calendar::Ptr &, const QString &), fromRawString() 0079 */ 0080 Incidence::Ptr fromString(const QString &string); 0081 0082 /** 0083 Parses a bytearray, returning the first iCal component as an Incidence, ignoring timezone information. 0084 0085 This function is significantly faster than fromString by avoiding the overhead of parsing timezone information. 0086 Timezones are instead solely interpreted by using system-timezones. 0087 0088 @param string is a utf8 QByteArray containing the data to be parsed. 0089 0090 @return non-zero pointer if the parsing was successful; 0 otherwise. 0091 @see fromString(const QString &), fromRawString() 0092 */ 0093 Incidence::Ptr readIncidence(const QByteArray &string); 0094 0095 /** 0096 Parses a string and fills a RecurrenceRule object with the information. 0097 0098 @param rule is a pointer to a RecurrenceRule object. 0099 @param string is a QString containing the data to be parsed. 0100 @return true if successful; false otherwise. 0101 */ 0102 Q_REQUIRED_RESULT bool fromString(RecurrenceRule *rule, const QString &string); 0103 0104 /** 0105 Parses a string representation of a duration. 0106 0107 @param duration iCal representation of a duration. 0108 @since 5.95 0109 */ 0110 Q_REQUIRED_RESULT Duration durationFromString(const QString &duration) const; 0111 0112 /** 0113 @copydoc 0114 CalFormat::fromRawString() 0115 */ 0116 Q_REQUIRED_RESULT bool fromRawString(const Calendar::Ptr &calendar, const QByteArray &string) override; 0117 0118 /** 0119 @copydoc 0120 CalFormat::toString() 0121 */ 0122 Q_REQUIRED_RESULT QString toString(const Calendar::Ptr &calendar) override; 0123 0124 /** 0125 Converts an Incidence to a QString. 0126 @param incidence is a pointer to an Incidence object to be converted 0127 into a QString. 0128 0129 @return the QString will be Null if the conversion was unsuccessful. 0130 */ 0131 Q_REQUIRED_RESULT QString toString(const Incidence::Ptr &incidence); 0132 0133 /** 0134 Converts an Incidence to a QByteArray. 0135 @param incidence is a pointer to an Incidence object to be converted 0136 into a QByteArray. 0137 0138 @return the QString will be Null if the conversion was unsuccessful. 0139 @since 4.7 0140 */ 0141 Q_REQUIRED_RESULT QByteArray toRawString(const Incidence::Ptr &incidence); 0142 0143 /** 0144 Converts a RecurrenceRule to a QString. 0145 @param rule is a pointer to a RecurrenceRule object to be converted 0146 into a QString. 0147 0148 @return the QString will be Null if the conversion was unsuccessful. 0149 */ 0150 Q_REQUIRED_RESULT QString toString(RecurrenceRule *rule); 0151 0152 /** 0153 Converts a Duration to an iCal string. 0154 @param duration a Duration object. 0155 @return iCal formatted duration 0156 @since 5.95 0157 */ 0158 Q_REQUIRED_RESULT QString toString(const Duration &duration) const; 0159 0160 /** 0161 Converts an Incidence to iCalendar formatted text. 0162 0163 @param incidence is a pointer to an Incidence object to be converted 0164 into iCal formatted text. 0165 @return the QString will be Null if the conversion was unsuccessful. 0166 */ 0167 Q_REQUIRED_RESULT QString toICalString(const Incidence::Ptr &incidence); 0168 0169 /** 0170 Creates a scheduling message string for an Incidence. 0171 0172 @param incidence is a pointer to an IncidenceBase object to be scheduled. 0173 @param method is a Scheduler::Method 0174 0175 @return a QString containing the message if successful; 0 otherwise. 0176 */ 0177 Q_REQUIRED_RESULT QString createScheduleMessage(const IncidenceBase::Ptr &incidence, iTIPMethod method); 0178 0179 /** 0180 Parses a Calendar scheduling message string into ScheduleMessage object. 0181 0182 @param calendar is a pointer to a Calendar object associated with the 0183 scheduling message. 0184 @param string is a QString containing the data to be parsed. 0185 0186 @return a pointer to a ScheduleMessage object if successful; 0 otherwise. 0187 The calling routine may later free the return memory. 0188 */ 0189 ScheduleMessage::Ptr parseScheduleMessage(const Calendar::Ptr &calendar, const QString &string); 0190 0191 /** 0192 Converts a QString into a FreeBusy object. 0193 0194 @param string is a QString containing the data to be parsed. 0195 @return a pointer to a FreeBusy object if successful; 0 otherwise. 0196 0197 @note Do not attempt to free the FreeBusy memory from the calling routine. 0198 */ 0199 FreeBusy::Ptr parseFreeBusy(const QString &string); 0200 0201 /** 0202 Sets the iCalendar time zone. 0203 @param timeZone is the time zone to set. 0204 @see timeZone(). 0205 */ 0206 void setTimeZone(const QTimeZone &timeZone); 0207 0208 /** 0209 Returns the iCalendar time zone. 0210 @see setTimeZone(). 0211 */ 0212 Q_REQUIRED_RESULT QTimeZone timeZone() const; 0213 0214 /** 0215 Returns the timezone id string used by the iCalendar; an empty string 0216 if the iCalendar does not have a timezone. 0217 */ 0218 Q_REQUIRED_RESULT QByteArray timeZoneId() const; 0219 0220 private: 0221 //@cond PRIVATE 0222 Q_DISABLE_COPY(ICalFormat) 0223 Q_DECLARE_PRIVATE(ICalFormat) 0224 //@endcond 0225 }; 0226 0227 } 0228 0229 #endif