File: itiphandler.h

package info (click to toggle)
akonadi-calendar 4:18.08.3-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 3,808 kB
  • sloc: cpp: 14,079; xml: 36; makefile: 8; sh: 4
file content (359 lines) | stat: -rw-r--r-- 12,746 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
/*
  Copyright (c) 2002-2004 Klarälvdalens Datakonsult AB
        <info@klaralvdalens-datakonsult.se>

  Copyright (C) 2010 Bertjan Broeksema <broeksema@kde.org>
  Copyright (C) 2010 Klaralvdalens Datakonsult AB, a KDAB Group company <info@kdab.net>

  Copyright (C) 2012 SĂ©rgio Martins <iamsergio@gmail.com>

  This library is free software; you can redistribute it and/or modify it
  under the terms of the GNU Library General Public License as published by
  the Free Software Foundation; either version 2 of the License, or (at your
  option) any later version.

  This library is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  License for more details.

  You should have received a copy of the GNU Library General Public License
  along with this library; see the file COPYING.LIB.  If not, write to the
  Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  02110-1301, USA.
*/

#ifndef AKONADI_CALENDAR_ITIP_HANDLER_H
#define AKONADI_CALENDAR_ITIP_HANDLER_H

#include "akonadi-calendar_export.h"
#include "etmcalendar.h"

#include <kcalcore/incidence.h>
#include <kcalcore/schedulemessage.h>

#include <KGuiItem>
#include <KLocalizedString>

#include <QObject>
#include <QString>
#include <QWidget>

namespace MailTransport
{
class MessageQueueJob;
}

namespace KIdentityManagement
{
class Identity;
}

namespace Akonadi
{

/**
 * @short Ui delegate for editing counter proposals.
 * @since 4.11
 */
class AKONADI_CALENDAR_EXPORT GroupwareUiDelegate : public QObject
{
    Q_OBJECT
public:
    explicit GroupwareUiDelegate(QObject *parent = nullptr);
    ~GroupwareUiDelegate() override;

    virtual void requestIncidenceEditor(const Akonadi::Item &item) = 0;
    virtual void setCalendar(const Akonadi::ETMCalendar::Ptr &calendar) = 0;
    virtual void createCalendar() = 0;
};

/**
 * @short Ui delegate for dialogs raised by the ITIPHandler and IncidenceChanger.
 * @since 4.15
 */
class AKONADI_CALENDAR_EXPORT ITIPHandlerDialogDelegate : public QObject
{
    Q_OBJECT
public:
    // Possible default actions
    enum Action {
        ActionAsk,              /**< Ask the user for a descision */
        ActionSendMessage,      /**< Answer with Yes */
        ActionDontSendMessage   /**< Answer with No */
    };

    // How will reveive the mail afterwards
    enum Recipient {
        Organizer,              /**< the organizer of the incidence */
        Attendees               /**< the attendees of the incidence */
    };

    /**
     * Creates a new AskDelegator
     */
    explicit ITIPHandlerDialogDelegate(const KCalCore::Incidence::Ptr &incidence, KCalCore::iTIPMethod method, QWidget *parent = nullptr);

    /*
     * Opens a Dialog, when an incidence is created
     * The function must emit a dialogClosed signal with the user's answer
     *
     * @param recipient: to who the mail will be sent afterwards
     * @param question: dialog's question
     * @param action: Should the dialog been shown or should a default answer be returned
     * @param buttonYes: dialog's yes answer
     * @param buttonNo: dialog's no answer
     */
    virtual void openDialogIncidenceCreated(Recipient recipient,
                                            const QString &question,
                                            Action action = ActionAsk,
                                            const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
                                            const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));

    /*
     * Opens a Dialog, when an incidence is modified
     * The function must emit a dialogClosed signal with the user's answer
     *
     * @param attendeeStatusChanged: Only the status of the own attendeeStatus is changed
     * @param recipient: to who the mail will be sent afterwards
     * @param question: dialog's question
     * @param action: Should the dialog been shown or should a default answer be returned
     * @param buttonYes: dialog's yes answer
     * @param buttonNo: dialog's no answer
     */
    virtual void openDialogIncidenceModified(bool attendeeStatusChanged,
            Recipient recipient,
            const QString &question,
            Action action = ActionAsk,
            const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
            const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));

    /*
     * Opens a Dialog, when an incidence is deleted
     * The function must emit a dialogClosed signal with the user's answer
     *
     * @param recipient: to who the mail will be sent afterwards
     * @param question: dialog's question
     * @param action: Should the dialog been shown or should a default answer be returned
     * @param buttonYes: dialog's yes answer
     * @param buttonNo: dialog's no answer
     */
    virtual void openDialogIncidenceDeleted(Recipient recipient,
                                            const QString &question,
                                            Action action = ActionAsk,
                                            const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
                                            const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));
    /*
     * Opens a Dialog, when mail was sended
     * The function must emit a dialogClosed signal with the user's answer
     *
     * @param question: dialog's question
     * @param action: Should the dialog been shown or should a default answer be returned
     * @param buttonYes: dialog's yes answer
     * @param buttonNo: dialog's no answer
     */
    virtual void openDialogSchedulerFinished(const QString &question,
            Action action = ActionAsk,
            const KGuiItem &buttonYes = KGuiItem(i18nc("@action:button dialog positive answer", "Send Email")),
            const KGuiItem &buttonNo = KGuiItem(i18nc("@action:button dialog negative answer", "Do Not Send")));

Q_SIGNALS:
    /*
     * Signal is emitted, when the user has answered the dialog or the defaultAction is used
     * @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 KMessageBox::No
     * @param method: itip method
     * @param incidence: purpose of the dialog
     */
    void dialogClosed(int answer, KCalCore::iTIPMethod method, const KCalCore::Incidence::Ptr &incidence);

protected:
    /*
     * Opens a KMessageBox::questionYesNo with the question
     *
     * @return KMessageBox::Yes or KMessageBox::No
     *
     * @param question: dialog's question
     * @param action: Should the dialog been shown or should a default answer be returned
     * @param buttonYes: dialog's yes answer
     * @param buttonNo: dialog's no answer
     */
    int askUserIfNeeded(const QString &question,
                        Action action,
                        const KGuiItem &buttonYes,
                        const KGuiItem &buttonNo) const;

    // parent of the dialog
    QWidget *mParent = nullptr;

    // Incidence related to the dialog
    KCalCore::Incidence::Ptr mIncidence;

    // ITIPMethod related to the dialog
    KCalCore::iTIPMethod mMethod;
};

/**
 * @short Factory to create MailTransport::MessageQueueJob jobs or ITIPHandlerDialogDelegate objects.
 * @since 4.15
 */
class AKONADI_CALENDAR_EXPORT ITIPHandlerComponentFactory : public QObject
{
    Q_OBJECT
public:
    /*
     * Created a new ITIPHandlerComponentFactory object.
     */
    explicit ITIPHandlerComponentFactory(QObject *parent = nullptr);

    /*
     * deletes the object.
     */
    ~ITIPHandlerComponentFactory() override;

    /*
     * @return A new MailTransport::MessageQueueJob object
     * @param incidence related to the mail
     * @param identity that is the mail sender
     * @param parent of the MailTransport::MessageQueueJob object
     */
    virtual MailTransport::MessageQueueJob *createMessageQueueJob(const KCalCore::IncidenceBase::Ptr &incidence, const KIdentityManagement::Identity &identity, QObject *parent = nullptr);

    /*
     * @return A new ITIPHandlerDialogDelegate object
     * @param incidence the purpose of the dialogs
     * @param method the ITIPMethod
     * @parent parent of the AskDelegator
     *
     */
    virtual ITIPHandlerDialogDelegate *createITIPHanderDialogDelegate(const KCalCore::Incidence::Ptr &incidence, KCalCore::iTIPMethod method, QWidget *parent = nullptr);
};

/**
 * @short Handles sending of iTip messages aswell as processing incoming ones.
 * @since 4.11
 */
class AKONADI_CALENDAR_EXPORT ITIPHandler : public QObject
{
    Q_OBJECT
public:
    enum Result {
        ResultError,      /**< An unexpected error occurred */
        ResultSuccess,    /**< The invitation was successfuly handled. */
        ResultCancelled   /**< User cancelled the operation. @since 4.12 */
    };

    /**
     * Creates a new ITIPHandler instance.
     * creates a default ITIPHandlerComponentFactory object.
     */
    explicit ITIPHandler(QObject *parent = nullptr);

    /**
     * Create a new ITIPHandler instance.
     * @param factory is set to 0 a new factory is created.
     * @since 4.15
     */
    explicit ITIPHandler(ITIPHandlerComponentFactory *factory, QObject *parent);
    /**
     * Destroys this instance.
     */
    ~ITIPHandler();

    /**
     * Processes a received iTip message.
     *
     * @param receiver
     * @param iCal
     * @param type
     *
     * @see iTipMessageProcessed()
     */
    void processiTIPMessage(const QString &receiver, const QString &iCal, const QString &type);

    /**
     * Sends an iTip message.
     *
     * @param method iTip method
     * @param incidence Incidence for which we're sending the iTip message.
     *                  Should contain a list of attendees.
     * @param parentWidget
     */
    void sendiTIPMessage(KCalCore::iTIPMethod method,
                         const KCalCore::Incidence::Ptr &incidence,
                         QWidget *parentWidget = nullptr);

    /**
     * Publishes incidence @p incidence.
     * A publish dialog will prompt the user to input recipients.
     * @see rfc2446 3.2.1
     */
    void publishInformation(const KCalCore::Incidence::Ptr &incidence, QWidget *parentWidget = nullptr);

    /**
     * Sends an e-mail with the incidence attached as iCalendar source.
     * A dialog will prompt the user to input recipients.
     */
    void sendAsICalendar(const KCalCore::Incidence::Ptr &incidence, QWidget *parentWidget = nullptr);

    /**
     * Sets the UI delegate to edit counter proposals.
     */
    void setGroupwareUiDelegate(GroupwareUiDelegate *delegate);

    /**
     * Sets the calendar that the itip handler should use.
     * The calendar should already be loaded.
     *
     * If none is set, a FetchJobCalendar will be created internally.
     */
    void setCalendar(const Akonadi::CalendarBase::Ptr &calendar);

    /**
     * Sets if the ITIP handler should show dialogs on error.
     * Default is true, for compatibility reasons, but this will change in KDE5.
     * TODO_KDE5: use message delegates
     *
     * @since 4.12
     */
    void setShowDialogsOnError(bool enable);

    /**
     * Returns the calendar used by this itip handler.
     */
    Akonadi::CalendarBase::Ptr calendar() const;

Q_SIGNALS:
    /**
     * Sent after processing an incoming iTip message.
     *
     * @param result success of the operation.
     * @param errorMessage translated error message suitable for user dialogs.
     *                     Empty if the operation was successul
     */
    void iTipMessageProcessed(Akonadi::ITIPHandler::Result result,
                              const QString &errorMessage);

    /**
     * Signal emitted after an iTip message was sent through sendiTIPMessage()
     */
    void iTipMessageSent(Akonadi::ITIPHandler::Result, const QString &errorMessage);

    /**
     * Signal emitted after an incidence was published with publishInformation()
     */
    void informationPublished(Akonadi::ITIPHandler::Result, const QString &errorMessage);

    /**
     * Signal emitted after an incidence was sent with sendAsICalendar()
     */
    void sentAsICalendar(Akonadi::ITIPHandler::Result, const QString &errorMessage);

private:
    Q_DISABLE_COPY(ITIPHandler)
    class Private;
    Private *const d;
};

}

#endif