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

KDE's Doxygen guidelines are available online.