Akonadi Calendar

itiphandler.h
1 /*
2  SPDX-FileCopyrightText: 2002-2004 Klarälvdalens Datakonsult AB,
4 
5  SPDX-FileCopyrightText: 2010 Bertjan Broeksema <[email protected]>
6  SPDX-FileCopyrightText: 2010 Klaralvdalens Datakonsult AB, a KDAB Group company <[email protected]>
7 
8  SPDX-FileCopyrightText: 2012 Sérgio Martins <[email protected]>
9 
10  SPDX-License-Identifier: LGPL-2.0-or-later
11 */
12 
13 #pragma once
14 
15 #include "akonadi-calendar_export.h"
16 #include "etmcalendar.h"
17 
18 #include <KCalendarCore/Incidence>
19 #include <KCalendarCore/ScheduleMessage>
20 
21 #include <KGuiItem>
22 #include <KLocalizedString>
23 
24 #include <QObject>
25 #include <QString>
26 #include <QWidget>
27 
28 namespace MailTransport
29 {
30 class MessageQueueJob;
31 }
32 
33 namespace KIdentityManagement
34 {
35 class Identity;
36 }
37 
38 namespace Akonadi
39 {
40 /**
41  * @short Ui delegate for editing counter proposals.
42  * @since 4.11
43  */
44 class AKONADI_CALENDAR_EXPORT GroupwareUiDelegate : public QObject
45 {
46  Q_OBJECT
47 public:
48  explicit GroupwareUiDelegate(QObject *parent = nullptr);
49  ~GroupwareUiDelegate() override;
50 
51  virtual void requestIncidenceEditor(const Akonadi::Item &item) = 0;
52  virtual void setCalendar(const Akonadi::ETMCalendar::Ptr &calendar) = 0;
53  virtual void createCalendar() = 0;
54 };
55 
56 /**
57  * @short Ui delegate for dialogs raised by the ITIPHandler and IncidenceChanger.
58  * @since 4.15
59  */
60 class AKONADI_CALENDAR_EXPORT ITIPHandlerDialogDelegate : public QObject
61 {
62  Q_OBJECT
63 public:
64  // Possible default actions
65  enum Action {
66  ActionAsk, /**< Ask the user for a descision */
67  ActionSendMessage, /**< Answer with Yes */
68  ActionDontSendMessage /**< Answer with No */
69  };
70 
71  // How will reveive the mail afterwards
72  enum Recipient {
73  Organizer, /**< the organizer of the incidence */
74  Attendees /**< the attendees of the incidence */
75  };
76 
77  /**
78  * Creates a new AskDelegator
79  */
80  explicit ITIPHandlerDialogDelegate(const KCalendarCore::Incidence::Ptr &incidence, KCalendarCore::iTIPMethod method, QWidget *parent = nullptr);
81 
82  /*
83  * Opens a Dialog, when an incidence is created
84  * The function must emit a dialogClosed signal with the user's answer
85  *
86  * @param recipient: to who the mail will be sent afterwards
87  * @param question: dialog's question
88  * @param action: Should the dialog been shown or should a default answer be returned
89  * @param buttonYes: dialog's yes answer
90  * @param buttonNo: dialog's no answer
91  */
92  virtual void openDialogIncidenceCreated(Recipient recipient,
93  const QString &question,
94  Action action = ActionAsk,
95  const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
96  const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
97 
98  /*
99  * Opens a Dialog, when an incidence is modified
100  * The function must emit a dialogClosed signal with the user's answer
101  *
102  * @param attendeeStatusChanged: Only the status of the own attendeeStatus is changed
103  * @param recipient: to who the mail will be sent afterwards
104  * @param question: dialog's question
105  * @param action: Should the dialog been shown or should a default answer be returned
106  * @param buttonYes: dialog's yes answer
107  * @param buttonNo: dialog's no answer
108  */
109  virtual void openDialogIncidenceModified(bool attendeeStatusChanged,
110  Recipient recipient,
111  const QString &question,
112  Action action = ActionAsk,
113  const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
114  const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
115 
116  /*
117  * Opens a Dialog, when an incidence is deleted
118  * The function must emit a dialogClosed signal with the user's answer
119  *
120  * @param recipient: to who the mail will be sent afterwards
121  * @param question: dialog's question
122  * @param action: Should the dialog been shown or should a default answer be returned
123  * @param buttonYes: dialog's yes answer
124  * @param buttonNo: dialog's no answer
125  */
126  virtual void openDialogIncidenceDeleted(Recipient recipient,
127  const QString &question,
128  Action action = ActionAsk,
129  const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
130  const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
131  /*
132  * Opens a Dialog, when mail was sended
133  * The function must emit a dialogClosed signal with the user's answer
134  *
135  * @param question: dialog's question
136  * @param action: Should the dialog been shown or should a default answer be returned
137  * @param buttonYes: dialog's yes answer
138  * @param buttonNo: dialog's no answer
139  */
140  virtual void openDialogSchedulerFinished(const QString &question,
141  Action action = ActionAsk,
142  const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
143  const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
144 
145 Q_SIGNALS:
146  /*
147  * Signal is emitted, when the user has answered the dialog or the defaultAction is used
148  * @param answer: answer should be part of KMessageBox:ButtonCode, keep in mind that it is a YesNoDialog so normally it should be KMessageBox::Yes or
149  * KMessageBox::No
150  * @param method: itip method
151  * @param incidence: purpose of the dialog
152  */
153  void dialogClosed(int answer, KCalendarCore::iTIPMethod method, const KCalendarCore::Incidence::Ptr &incidence);
154 
155 protected:
156  /*
157  * Opens a KMessageBox::questionYesNo with the question
158  *
159  * @return KMessageBox::Yes or KMessageBox::No
160  *
161  * @param question: dialog's question
162  * @param action: Should the dialog been shown or should a default answer be returned
163  * @param buttonYes: dialog's yes answer
164  * @param buttonNo: dialog's no answer
165  */
166  int askUserIfNeeded(const QString &question, Action action, const KGuiItem &buttonYes, const KGuiItem &buttonNo) const;
167 
168  // parent of the dialog
169  QWidget *mParent = nullptr;
170 
171  // Incidence related to the dialog
173 
174  // ITIPMethod related to the dialog
176 };
177 
178 /**
179  * @short Factory to create MailTransport::MessageQueueJob jobs or ITIPHandlerDialogDelegate objects.
180  * @since 4.15
181  */
182 class AKONADI_CALENDAR_EXPORT ITIPHandlerComponentFactory : public QObject
183 {
184  Q_OBJECT
185 public:
186  /*
187  * Created a new ITIPHandlerComponentFactory object.
188  */
189  explicit ITIPHandlerComponentFactory(QObject *parent = nullptr);
190 
191  /*
192  * deletes the object.
193  */
194  ~ITIPHandlerComponentFactory() override;
195 
196  /*
197  * @return A new MailTransport::MessageQueueJob object
198  * @param incidence related to the mail
199  * @param identity that is the mail sender
200  * @param parent of the MailTransport::MessageQueueJob object
201  */
203  createMessageQueueJob(const KCalendarCore::IncidenceBase::Ptr &incidence, const KIdentityManagement::Identity &identity, QObject *parent = nullptr);
204 
205  /*
206  * @return A new ITIPHandlerDialogDelegate object
207  * @param incidence the purpose of the dialogs
208  * @param method the ITIPMethod
209  * @parent parent of the AskDelegator
210  *
211  */
212  virtual ITIPHandlerDialogDelegate *
213  createITIPHanderDialogDelegate(const KCalendarCore::Incidence::Ptr &incidence, KCalendarCore::iTIPMethod method, QWidget *parent = nullptr);
214 };
215 
216 /**
217  * @short Handles sending of iTip messages aswell as processing incoming ones.
218  * @since 4.11
219  */
220 class AKONADI_CALENDAR_EXPORT ITIPHandler : public QObject
221 {
222  Q_OBJECT
223 public:
224  enum Result {
225  ResultError, /**< An unexpected error occurred */
226  ResultSuccess, /**< The invitation was successfuly handled. */
227  ResultCancelled /**< User cancelled the operation. @since 4.12 */
228  };
229 
230  /**
231  * Creates a new ITIPHandler instance.
232  * creates a default ITIPHandlerComponentFactory object.
233  */
234  explicit ITIPHandler(QObject *parent = nullptr);
235 
236  /**
237  * Create a new ITIPHandler instance.
238  * @param factory is set to 0 a new factory is created.
239  * @since 4.15
240  */
241  explicit ITIPHandler(ITIPHandlerComponentFactory *factory, QObject *parent);
242  /**
243  * Destroys this instance.
244  */
245  ~ITIPHandler();
246 
247  /**
248  * Processes a received iTip message.
249  *
250  * @param receiver
251  * @param iCal
252  * @param type
253  *
254  * @see iTipMessageProcessed()
255  */
256  void processiTIPMessage(const QString &receiver, const QString &iCal, const QString &type);
257 
258  /**
259  * Sends an iTip message.
260  *
261  * @param method iTip method
262  * @param incidence Incidence for which we're sending the iTip message.
263  * Should contain a list of attendees.
264  * @param parentWidget
265  */
266  void sendiTIPMessage(KCalendarCore::iTIPMethod method, const KCalendarCore::Incidence::Ptr &incidence, QWidget *parentWidget = nullptr);
267 
268  /**
269  * Publishes incidence @p incidence.
270  * A publish dialog will prompt the user to input recipients.
271  * @see rfc2446 3.2.1
272  */
273  void publishInformation(const KCalendarCore::Incidence::Ptr &incidence, QWidget *parentWidget = nullptr);
274 
275  /**
276  * Sends an e-mail with the incidence attached as iCalendar source.
277  * A dialog will prompt the user to input recipients.
278  */
279  void sendAsICalendar(const KCalendarCore::Incidence::Ptr &incidence, QWidget *parentWidget = nullptr);
280 
281  /**
282  * Sets the UI delegate to edit counter proposals.
283  */
284  void setGroupwareUiDelegate(GroupwareUiDelegate *delegate);
285 
286  /**
287  * Sets the calendar that the itip handler should use.
288  * The calendar should already be loaded.
289  *
290  * If none is set, a FetchJobCalendar will be created internally.
291  */
292  void setCalendar(const Akonadi::CalendarBase::Ptr &calendar);
293 
294  /**
295  * Sets if the ITIP handler should show dialogs on error.
296  * Default is true, for compatibility reasons, but this will change in KDE5.
297  * TODO_KDE5: use message delegates
298  *
299  * @since 4.12
300  */
301  void setShowDialogsOnError(bool enable);
302 
303  /**
304  * Returns the calendar used by this itip handler.
305  */
306  Akonadi::CalendarBase::Ptr calendar() const;
307 
308 Q_SIGNALS:
309  /**
310  * Sent after processing an incoming iTip message.
311  *
312  * @param result success of the operation.
313  * @param errorMessage translated error message suitable for user dialogs.
314  * Empty if the operation was successul
315  */
316  void iTipMessageProcessed(Akonadi::ITIPHandler::Result result, const QString &errorMessage);
317 
318  /**
319  * Signal emitted after an iTip message was sent through sendiTIPMessage()
320  */
321  void iTipMessageSent(Akonadi::ITIPHandler::Result, const QString &errorMessage);
322 
323  /**
324  * Signal emitted after an incidence was published with publishInformation()
325  */
326  void informationPublished(Akonadi::ITIPHandler::Result, const QString &errorMessage);
327 
328  /**
329  * Signal emitted after an incidence was sent with sendAsICalendar()
330  */
331  void sentAsICalendar(Akonadi::ITIPHandler::Result, const QString &errorMessage);
332 
333 private:
334  Q_DISABLE_COPY(ITIPHandler)
335  class Private;
336  Private *const d;
337 };
338 }
339 
Factory to create MailTransport::MessageQueueJob jobs or ITIPHandlerDialogDelegate objects...
Definition: itiphandler.h:182
An unexpected error occurred.
Definition: itiphandler.h:225
The invitation was successfuly handled.
Definition: itiphandler.h:226
Ui delegate for dialogs raised by the ITIPHandler and IncidenceChanger.
Definition: itiphandler.h:60
Handles sending of iTip messages aswell as processing incoming ones.
Definition: itiphandler.h:220
the organizer of the incidence
Definition: itiphandler.h:73
QString i18nc(const char *context, const char *text, const TYPE &arg...)
Ask the user for a descision.
Definition: itiphandler.h:66
FreeBusyManager::Singleton.
Ui delegate for editing counter proposals.
Definition: itiphandler.h:44
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.