Akonadi Calendar

freebusymanager.h
1/*
2 Requires the Qt and KDE widget libraries, available at no cost at
3 http://www.trolltech.com and http://www.kde.org respectively
4
5 SPDX-FileCopyrightText: 2002-2004 Klarälvdalens Datakonsult AB,
6 <info@klaralvdalens-datakonsult.se>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10#pragma once
11
12#include "akonadi-calendar_export.h"
13#include "etmcalendar.h"
14
15#include <KCalendarCore/FreeBusyCache>
16
17#include <memory>
18
19// TODO: document
20namespace Akonadi
21{
22class FreeBusyManagerPrivate;
23class FreeBusyManagerStatic;
24
25class AKONADI_CALENDAR_EXPORT FreeBusyManager : public QObject, public KCalendarCore::FreeBusyCache
26{
27 Q_OBJECT
28public:
29 /**
30 * Returns the FreeBusyManager
31 */
32 static FreeBusyManager *self();
33
34 void setCalendar(const Akonadi::ETMCalendar::Ptr &calendar);
35
36 /**
37 Publishes the owners freebusy information from the current calendar
38 starting from the current date/time to current date/time + freeBusyPublishDays.
39 If an upload is already in progress nothing happens.
40
41 @see KCalPrefBase::freeBusyPublishUrl()
42 @see KCalPrefBase::freeBusyPublishDays();
43 */
44 Q_INVOKABLE void publishFreeBusy(QWidget *parentWidget = nullptr);
45
46 /**
47 Mail the freebusy information.
48 */
49 Q_INVOKABLE void mailFreeBusy(int daysToPublish = 30, QWidget *parentWidget = nullptr);
50
51 /**
52 Retrieve the freebusy information of somebody else, i.e. it will not try
53 to download our own freebusy information.
54
55 This method will first try to find Akonadi resource that have the
56 'FreeBusyProvider' capability set. If none is found then there is a fallback
57 on the URL mechanism (see below). If at least one is found then it will
58 be first queried over D-Bus to know if it can handle free-busy information
59 for that email address. If true then it will be queried for the free-busy
60 data for a period ranging from today to today plus 14 days, defined in
61 FreeBusyManagerPrivate::FreeBusyProvidersRequestsQueue::FreeBusyProvidersRequestsQueue()
62 as hard-coded magic value. If the Akonadi resource responds successfully
63 (still over D-Bus) then the freeBusyRetrieved signal is emitted. If any
64 of those steps then the URL mechanism will be used as a fallback.
65
66 The URL mechanism makes use of a local cache, if the information
67 for a given email is already downloaded it will return the information
68 from the cache. The free-busy information must be accessible using HTTP
69 and the URL is build dynamically from the email address and the global
70 groupware settings.
71
72 The call is asynchronous, a download is started in the background (if
73 needed) and freeBusyRetrieved will be emitted when the download is finished.
74
75 @see KCalPrefs::thatIsMe( const QString &email );
76 @see Akonadi::FreeBusyProviderBase
77
78 @param email Address of the person for which the F/B list should be
79 retrieved.
80 @param forceDownload Set to true to trigger a download even when automatic
81 retrieval of freebusy information is disabled in the configuration.
82 @return true if a download is initiated, and false otherwise
83 */
84 Q_INVOKABLE bool retrieveFreeBusy(const QString &email, bool forceDownload, QWidget *parentWidget = nullptr);
85
86 /**
87 Clears the retrieval queue, i.e. all retrieval request that are not started
88 yet will not start at all. The freebusy retrieval that currently is
89 downloading (if one) will not be canceled.
90
91 @see retrieveFreeBusy
92 */
93 void cancelRetrieval();
94
95 /**
96 Load freebusy information belonging to an email. The information is loaded
97 from a local file. If the file does not exists or doesn't contain valid
98 information 0 is returned. In that case the information should be retrieved
99 again by calling retrieveFreeBusy.
100
101 Implements KCalendarCore::FreeBusyCache::loadFreeBusy
102
103 @param email is a QString containing a email string in the
104 "FirstName LastName <emailaddress>" format.
105 */
106 [[nodiscard]] KCalendarCore::FreeBusy::Ptr loadFreeBusy(const QString &email) override;
107
108 /**
109 Save freebusy information belonging to an email.
110
111 Implements KCalendarCore::FreeBusyCache::saveFreeBusy
112
113 @param freebusy is a pointer to a valid FreeBusy instance.
114 @param person is a valid Person instance.
115 */
116 bool saveFreeBusy(const KCalendarCore::FreeBusy::Ptr &freebusy, const KCalendarCore::Person &person) override;
117
118Q_SIGNALS:
119 /**
120 This signal is emitted to return results of free/busy requests.
121 */
122 void freeBusyRetrieved(const KCalendarCore::FreeBusy::Ptr &fb, const QString &email);
123
124protected:
125 /** React on timer events, used for delayed freebusy list uploading */
126 void timerEvent(QTimerEvent *event) override;
127
128private:
129 /**
130 Creates a new FreeBusyManager, private because FreeBusyManager is a
131 Singleton
132 */
133 AKONADI_CALENDAR_NO_EXPORT FreeBusyManager();
134 ~FreeBusyManager() override;
135
136 friend class FreeBusyManagerStatic;
137
138 std::unique_ptr<FreeBusyManagerPrivate> const d_ptr;
139 Q_DECLARE_PRIVATE(FreeBusyManager)
140 Q_DISABLE_COPY(FreeBusyManager)
141 Q_PRIVATE_SLOT(d_ptr, void checkFreeBusyUrl())
142 Q_PRIVATE_SLOT(d_ptr, void processFreeBusyDownloadResult(KJob *))
143 Q_PRIVATE_SLOT(d_ptr, void processFreeBusyUploadResult(KJob *))
144 Q_PRIVATE_SLOT(d_ptr, void processRetrieveQueue())
145 Q_PRIVATE_SLOT(d_ptr, void uploadFreeBusy())
146};
147}
FreeBusyManager::Singleton.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 19 2024 11:52:11 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.