Akonadi Calendar

freebusyproviderbase.h
1/*
2 SPDX-FileCopyrightText: 2011 Grégory Oestreicher <greg@kamago.net>
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
15class QDateTime;
16
17namespace Akonadi
18{
19class 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
41class AKONADI_CALENDAR_EXPORT FreeBusyProviderBase
42{
43public:
44 /**
45 * Creates a new FreeBusyProvider
46 */
48
49 /**
50 * Destroys a FreeBusyProvider
51 */
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 foo@bar.com (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 foo@bar.com (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 foo@bar.com (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 foo@bar.com (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
136private:
137 //@cond PRIVATE
138 Q_DISABLE_COPY(FreeBusyProviderBase)
139 std::unique_ptr<FreeBusyProviderBasePrivate> const d;
140 //@endcond
141};
142}
Base class for resources providing free-busy information.
virtual ~FreeBusyProviderBase()
Destroys a FreeBusyProvider.
virtual QDateTime lastCacheUpdate() const =0
Returns the last time the free-busy information was fetched from the server.
virtual void retrieveFreeBusy(const QString &email, const QDateTime &start, const QDateTime &end)=0
This method is called when the resource must do the real work and fetch the free-busy information for...
virtual void canHandleFreeBusy(const QString &email) const =0
This method is called to find out is the resource handle free-busy information for the contact with e...
Q_SCRIPTABLE Q_NOREPLY void start()
FreeBusyManager::Singleton.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 18 2024 12:14:27 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.