Akonadi Calendar

freebusyproviderbase.h
1 /*
2  SPDX-FileCopyrightText: 2011 GrĂ©gory Oestreicher <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadi-calendar_export.h"
10 
11 #include <QString>
12 
13 #include <memory>
14 
15 class QDateTime;
16 
17 namespace Akonadi
18 {
19 class FreeBusyProviderBasePrivate;
20 
21 /**
22  * @short Base class for resources providing free-busy information
23  *
24  * This class must be inherited by resources that are able to provide
25  * free-busy information for a given contact on request. A resource
26  * will thus inherit from ResourceBase and FreeBusyProvider.
27  *
28  * Resources that provide FB info must declare it by adding
29  * 'FreeBusyProvider' in the X-Akonadi-Capabilities field of their
30  * .desktop file:
31  \code
32  X-Akonadi-Capabilities=Resource,FreeBusyProvider
33  \endcode
34  *
35  * Resource inheriting from this class must implement lastCacheUpdate(),
36  * canHandleFreeBusy() and retrieveFreeBusy().
37  *
38  * @since 4.7
39  */
40 
41 class AKONADI_CALENDAR_EXPORT FreeBusyProviderBase
42 {
43 public:
44  /**
45  * Creates a new FreeBusyProvider
46  */
48 
49  /**
50  * Destroys a FreeBusyProvider
51  */
52  virtual ~FreeBusyProviderBase();
53 
54  /**
55  * Returns the last time the free-busy information was
56  * fetched from the server. This can be used for example
57  * to issue a warning to the user that this information
58  * may not be accurate and must be refreshed; pretty useful
59  * when the resource was offline for too long.
60  *
61  * @return The date and time the cache was last updated.
62  */
63  virtual QDateTime lastCacheUpdate() const = 0;
64 
65  /**
66  * This method is called to find out is the resource
67  * handle free-busy information for the contact with
68  * email address @p email.
69  *
70  * The caller will not wait for the result. Once the
71  * decision is known, the resource must call
72  * handlesFreeBusy().
73  *
74  * @param email The email address of the contact we want
75  * the free-busy info. This is a simple email
76  * address, in the form [email protected] (no display
77  * name or quoting).
78  * @see handlesFreeBusy()
79  *
80  */
81  virtual void canHandleFreeBusy(const QString &email) const = 0;
82 
83  /**
84  * Derivate classes must call this method once they know
85  * if they handle free-busy information for the contact
86  * with email address @p email.
87  *
88  * @param email The email address of the contact we give the
89  * response for. This is a simple email
90  * address, in the form [email protected] (no display
91  * name or quoting).
92  * @param handles Whether this resource handles free-busy (true)
93  * or not (false).
94  */
95  void handlesFreeBusy(const QString &email, bool handles) const;
96 
97  /**
98  * This method is called when the resource must do the real
99  * work and fetch the free-busy information for the contact
100  * with email address @p email.
101  *
102  * As with canHandleFreeBusy() the caller will not wait for
103  * the result and the resource must call freeBusyRetrieved()
104  * once done.
105  *
106  * @param email The email address of the contact we want
107  * the free-busy info. This is a simple email
108  * address, in the form [email protected] (no display
109  * name or quoting).
110  * @param start The start of the period the free-busy request covers
111  * @param end The end of the free-busy period
112  * @see freeBusyRetrieved()
113  */
114  virtual void retrieveFreeBusy(const QString &email, const QDateTime &start, const QDateTime &end) = 0;
115 
116  /**
117  * Derivate classes must call this method to notify the requestor
118  * that the result is here.
119  *
120  * The @p freeBusy is expected to be an iTIP request containing
121  * the free-busy data. The simplest way to generate this is
122  * to use KCalendarCore::ICalFormat::createScheduleMessage()
123  * with the method KCalendarCore::iTIPRequest.
124  *
125  * @param email The email address of the contact we give the
126  * response for. This is a simple email
127  * address, in the form [email protected] (no display
128  * name or quoting).
129  * @param freeBusy The free-busy data.
130  * @param success Whether the retrieval was successful or not.
131  * @param errorText An optional error message that can be displayed back
132  * to the user.
133  */
134  void freeBusyRetrieved(const QString &email, const QString &freeBusy, bool success, const QString &errorText = QString());
135 
136 private:
137  //@cond PRIVATE
138  Q_DISABLE_COPY(FreeBusyProviderBase)
139  std::unique_ptr<FreeBusyProviderBasePrivate> const d;
140  //@endcond
141 };
142 }
Q_SCRIPTABLE Q_NOREPLY void start()
Base class for resources providing free-busy information.
FreeBusyManager::Singleton.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Oct 6 2022 03:57:05 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.