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