1/*
2 Copyright (c) 2009 Constantin Berzan <exit3219@gmail.com>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_TRANSPORTRESOURCEBASE_H
21#define AKONADI_TRANSPORTRESOURCEBASE_H
22
23#include "akonadi_export.h"
24
25#include <QtCore/QString>
26
27#include <akonadi/item.h>
28
29class KJob;
30
31namespace Akonadi {
32
33class TransportResourceBasePrivate;
34
35/**
36 * @short Resource implementing mail transport capability.
37 *
38 * This class allows a resource to provide mail transport (i.e. sending
39 * mail). A resource than can provide mail transport inherits from both
40 * ResourceBase and TransportResourceBase, implements the virtual method
41 * sendItem(), and calls itemSent() when finished sending.
42 *
43 * The resource must also have the "MailTransport" capability flag. For example
44 * the desktop file may contain:
45 \code
46 X-Akonadi-Capabilities=Resource,MailTransport
47 \endcode
48 *
49 * For an example of a transport-enabled resource, see
50 * kdepim/runtime/resources/mailtransport_dummy
51 *
52 * @author Constantin Berzan <exit3219@gmail.com>
53 * @since 4.4
54 */
55class AKONADI_EXPORT TransportResourceBase
56{
57public:
58 /**
59 * Creates a new transport resource base.
60 */
61 TransportResourceBase();
62
63 /**
64 * Destroys the transport resource base.
65 */
66 virtual ~TransportResourceBase();
67
68 /**
69 * Describes the result of the transport process.
70 */
71 enum TransportResult {
72 TransportSucceeded, ///< The transport process succeeded.
73 TransportFailed ///< The transport process failed.
74 };
75
76 /**
77 * This method is called when the given @p item shall be send.
78 * When the sending is done or an error occurred during
79 * sending, call itemSent() with the appropriate result flag.
80 *
81 * @param item The message item to be send.
82 * @see itemSent().
83 */
84 virtual void sendItem(const Akonadi::Item &item) = 0;
85
86 /**
87 * This method marks the sending of the passed @p item
88 * as finished.
89 *
90 * @param item The item that was sent.
91 * @param result The result that indicates whether the sending
92 * was successful or not.
93 * @param message An optional text explanation of the result.
94 * @see Transport.
95 */
96 void itemSent(const Akonadi::Item &item, TransportResult result,
97 const QString &message = QString());
98
99private:
100 //@cond PRIVATE
101 TransportResourceBasePrivate *const d;
102 //@endcond
103};
104
105}
106
107#endif
108