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 MAILTRANSPORT_MESSAGEQUEUEJOB_H |
21 | #define MAILTRANSPORT_MESSAGEQUEUEJOB_H |
22 | |
23 | #include <mailtransport/mailtransport_export.h> |
24 | |
25 | #include "dispatchmodeattribute.h" |
26 | #include "sentactionattribute.h" |
27 | #include "sentbehaviourattribute.h" |
28 | #include "transportattribute.h" |
29 | |
30 | #include <QtCore/QDateTime> |
31 | #include <QtCore/QString> |
32 | #include <QtCore/QStringList> |
33 | |
34 | #include <KDE/KCompositeJob> |
35 | |
36 | #include <akonadi/collection.h> |
37 | #include <akonadi/kmime/addressattribute.h> |
38 | |
39 | #include <kmime/kmime_message.h> |
40 | #include <boost/shared_ptr.hpp> |
41 | |
42 | namespace MailTransport { |
43 | |
44 | /** |
45 | @short Provides an interface for sending email. |
46 | |
47 | This class takes a KMime::Message and some related info such as sender and |
48 | recipient addresses, and places the message in the outbox. The mail |
49 | dispatcher agent will then take it from there and send it. |
50 | |
51 | This is the preferred way for applications to send email. |
52 | |
53 | This job requires some options to be set before being started. Modify the |
54 | attributes of this job to change these options. |
55 | |
56 | You need to set the transport of the transport attribute, the from address of |
57 | the address attribute and one of the to, cc or bcc addresses of the address |
58 | attribute. Also, you need to call setMessage(). |
59 | Optionally, you can change the dispatch mode attribute or the sent behaviour |
60 | attribute. |
61 | |
62 | Example: |
63 | @code |
64 | |
65 | MessageQueueJob *job = new MessageQueueJob( this ); |
66 | job->setMessage( msg ); // msg is a Message::Ptr |
67 | job->transportAttribute().setTransportId( TransportManager::self()->defaultTransportId() ); |
68 | // Use the default dispatch mode. |
69 | // Use the default sent-behaviour. |
70 | job->addressAttribute().setFrom( from ); // from is a QString |
71 | job->addressAttribute().setTo( to ); // to is a QStringList |
72 | connect( job, SIGNAL(result(KJob*)), this, SLOT(jobResult(KJob*)) ); |
73 | job->start(); |
74 | |
75 | @endcode |
76 | |
77 | @see DispatchModeAttribute |
78 | @see SentActionAttribute |
79 | @see SentBehaviourAttribute |
80 | @see TransportAttribute |
81 | @see AddressAttribute |
82 | |
83 | @author Constantin Berzan <exit3219@gmail.com> |
84 | @since 4.4 |
85 | */ |
86 | class MAILTRANSPORT_EXPORT MessageQueueJob : public KCompositeJob |
87 | { |
88 | Q_OBJECT |
89 | |
90 | public: |
91 | /** |
92 | Creates a new MessageQueueJob. |
93 | @param parent the QObject parent |
94 | This is not an autostarting job; you need to call start() yourself. |
95 | */ |
96 | explicit MessageQueueJob( QObject *parent = 0 ); |
97 | |
98 | /** |
99 | Destroys the MessageQueueJob. |
100 | This job deletes itself after finishing. |
101 | */ |
102 | virtual ~MessageQueueJob(); |
103 | |
104 | /** |
105 | Returns the message to be sent. |
106 | */ |
107 | KMime::Message::Ptr message() const; |
108 | |
109 | /** |
110 | Returns a reference to the dispatch mode attribue for this message. |
111 | Modify the returned attribute to change the dispatch mode. |
112 | */ |
113 | DispatchModeAttribute &dispatchModeAttribute(); |
114 | |
115 | /** |
116 | Returns a reference to the address attribue for this message. |
117 | Modify the returned attribute to change the receivers or the from |
118 | address. |
119 | */ |
120 | Akonadi::AddressAttribute &addressAttribute(); |
121 | |
122 | /** |
123 | Returns a reference to the transport attribue for this message. |
124 | Modify the returned attribute to change the transport used for |
125 | sending the mail. |
126 | */ |
127 | TransportAttribute &transportAttribute(); |
128 | |
129 | /** |
130 | Returns a reference to the sent behaviour attribue for this message. |
131 | Modify the returned attribute to change the sent behaviour. |
132 | */ |
133 | SentBehaviourAttribute &sentBehaviourAttribute(); |
134 | |
135 | /** |
136 | Returns a reference to the sent action attribue for this message. |
137 | Modify the returned attribute to change the sent actions. |
138 | */ |
139 | SentActionAttribute &sentActionAttribute(); |
140 | |
141 | /** |
142 | Sets the message to be sent. |
143 | */ |
144 | void setMessage( KMime::Message::Ptr message ); |
145 | |
146 | /** |
147 | Creates the item and places it in the outbox. |
148 | It is now queued for sending by the mail dispatcher agent. |
149 | */ |
150 | virtual void start(); |
151 | |
152 | protected Q_SLOTS: |
153 | /** |
154 | Called when the ItemCreateJob subjob finishes. |
155 | |
156 | (reimplemented from KCompositeJob) |
157 | */ |
158 | virtual void slotResult( KJob * ); |
159 | |
160 | private: |
161 | class Private; |
162 | friend class Private; |
163 | Private *const d; |
164 | |
165 | Q_PRIVATE_SLOT( d, void outboxRequestResult( KJob* ) ) |
166 | |
167 | }; |
168 | |
169 | } // namespace MailTransport |
170 | |
171 | #endif // MAILTRANSPORT_MESSAGEQUEUEJOB_H |
172 | |