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
42namespace 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*/
86class 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