File indexing completed on 2024-05-12 05:10:44
0001 /* 0002 SPDX-FileCopyrightText: 2011 Grégory Oestreicher <greg@kamago.net> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #pragma once 0008 0009 #include "akonadi-calendar_export.h" 0010 0011 #include <QString> 0012 0013 #include <memory> 0014 0015 class QDateTime; 0016 0017 namespace Akonadi 0018 { 0019 class FreeBusyProviderBasePrivate; 0020 0021 /** 0022 * @short Base class for resources providing free-busy information 0023 * 0024 * This class must be inherited by resources that are able to provide 0025 * free-busy information for a given contact on request. A resource 0026 * will thus inherit from ResourceBase and FreeBusyProvider. 0027 * 0028 * Resources that provide FB info must declare it by adding 0029 * 'FreeBusyProvider' in the X-Akonadi-Capabilities field of their 0030 * .desktop file: 0031 \code 0032 X-Akonadi-Capabilities=Resource,FreeBusyProvider 0033 \endcode 0034 * 0035 * Resource inheriting from this class must implement lastCacheUpdate(), 0036 * canHandleFreeBusy() and retrieveFreeBusy(). 0037 * 0038 * @since 4.7 0039 */ 0040 0041 class AKONADI_CALENDAR_EXPORT FreeBusyProviderBase 0042 { 0043 public: 0044 /** 0045 * Creates a new FreeBusyProvider 0046 */ 0047 FreeBusyProviderBase(); 0048 0049 /** 0050 * Destroys a FreeBusyProvider 0051 */ 0052 virtual ~FreeBusyProviderBase(); 0053 0054 /** 0055 * Returns the last time the free-busy information was 0056 * fetched from the server. This can be used for example 0057 * to issue a warning to the user that this information 0058 * may not be accurate and must be refreshed; pretty useful 0059 * when the resource was offline for too long. 0060 * 0061 * @return The date and time the cache was last updated. 0062 */ 0063 virtual QDateTime lastCacheUpdate() const = 0; 0064 0065 /** 0066 * This method is called to find out is the resource 0067 * handle free-busy information for the contact with 0068 * email address @p email. 0069 * 0070 * The caller will not wait for the result. Once the 0071 * decision is known, the resource must call 0072 * handlesFreeBusy(). 0073 * 0074 * @param email The email address of the contact we want 0075 * the free-busy info. This is a simple email 0076 * address, in the form foo@bar.com (no display 0077 * name or quoting). 0078 * @see handlesFreeBusy() 0079 * 0080 */ 0081 virtual void canHandleFreeBusy(const QString &email) const = 0; 0082 0083 /** 0084 * Derivate classes must call this method once they know 0085 * if they handle free-busy information for the contact 0086 * with email address @p email. 0087 * 0088 * @param email The email address of the contact we give the 0089 * response for. This is a simple email 0090 * address, in the form foo@bar.com (no display 0091 * name or quoting). 0092 * @param handles Whether this resource handles free-busy (true) 0093 * or not (false). 0094 */ 0095 void handlesFreeBusy(const QString &email, bool handles) const; 0096 0097 /** 0098 * This method is called when the resource must do the real 0099 * work and fetch the free-busy information for the contact 0100 * with email address @p email. 0101 * 0102 * As with canHandleFreeBusy() the caller will not wait for 0103 * the result and the resource must call freeBusyRetrieved() 0104 * once done. 0105 * 0106 * @param email The email address of the contact we want 0107 * the free-busy info. This is a simple email 0108 * address, in the form foo@bar.com (no display 0109 * name or quoting). 0110 * @param start The start of the period the free-busy request covers 0111 * @param end The end of the free-busy period 0112 * @see freeBusyRetrieved() 0113 */ 0114 virtual void retrieveFreeBusy(const QString &email, const QDateTime &start, const QDateTime &end) = 0; 0115 0116 /** 0117 * Derivate classes must call this method to notify the requestor 0118 * that the result is here. 0119 * 0120 * The @p freeBusy is expected to be an iTIP request containing 0121 * the free-busy data. The simplest way to generate this is 0122 * to use KCalendarCore::ICalFormat::createScheduleMessage() 0123 * with the method KCalendarCore::iTIPRequest. 0124 * 0125 * @param email The email address of the contact we give the 0126 * response for. This is a simple email 0127 * address, in the form foo@bar.com (no display 0128 * name or quoting). 0129 * @param freeBusy The free-busy data. 0130 * @param success Whether the retrieval was successful or not. 0131 * @param errorText An optional error message that can be displayed back 0132 * to the user. 0133 */ 0134 void freeBusyRetrieved(const QString &email, const QString &freeBusy, bool success, const QString &errorText = QString()); 0135 0136 private: 0137 //@cond PRIVATE 0138 Q_DISABLE_COPY(FreeBusyProviderBase) 0139 std::unique_ptr<FreeBusyProviderBasePrivate> const d; 0140 //@endcond 0141 }; 0142 }