1/*
2 Copyright (c) 2006 - 2007 Volker Krause <vkrause@kde.org>
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_TRANSPORTMANAGER_H
21#define MAILTRANSPORT_TRANSPORTMANAGER_H
22
23#include <mailtransport/mailtransport_export.h>
24#include <mailtransport/transporttype.h>
25
26#include <QtCore/QList>
27#include <QtCore/QObject>
28
29#include <akonadi/agenttype.h>
30
31class KJob;
32
33namespace KWallet {
34 class Wallet;
35}
36
37namespace MailTransport {
38
39class Transport;
40class TransportJob;
41class TransportManagerPrivate;
42
43/**
44 @short Central transport management interface.
45
46 This class manages the creation, configuration, and removal of mail
47 transports, as well as the loading and storing of mail transport settings.
48
49 It also handles the creation of transport jobs, although that behaviour is
50 deprecated and you are encouraged to use MessageQueueJob.
51
52 @see MessageQueueJob.
53*/
54class MAILTRANSPORT_EXPORT TransportManager : public QObject
55{
56 Q_OBJECT
57 Q_CLASSINFO( "D-Bus Interface", "org.kde.pim.TransportManager" )
58
59 friend class Transport;
60 friend class TransportManagerPrivate;
61
62 public:
63
64 /**
65 Destructor.
66 */
67 virtual ~TransportManager();
68
69 /**
70 Returns the TransportManager instance.
71 */
72 static TransportManager *self();
73
74 /**
75 Tries to load passwords asynchronously from KWallet if needed.
76 The passwordsChanged() signal is emitted once the passwords have been loaded.
77 Nothing happens if the passwords were already available.
78 */
79 void loadPasswordsAsync();
80
81 /**
82 Returns the Transport object with the given id.
83 @param id The identifier of the Transport.
84 @param def if set to true, the default transport will be returned if the
85 specified Transport object could not be found, 0 otherwise.
86 @returns A Transport object for immediate use. It might become invalid as
87 soon as the event loop is entered again due to remote changes. If you need
88 to store a Transport object, store the transport identifier instead.
89 */
90 Transport *transportById( int id, bool def = true ) const;
91
92 /**
93 Returns the transport object with the given name.
94 @param name The transport name.
95 @param def if set to true, the default transport will be returned if the
96 specified Transport object could not be found, 0 otherwise.
97 @returns A Transport object for immediate use, see transportById() for
98 limitations.
99 */
100 Transport *transportByName( const QString &name, bool def = true ) const;
101
102 /**
103 Returns a list of all available transports.
104 Note: The Transport objects become invalid as soon as a change occur, so
105 they are only suitable for immediate use.
106 */
107 QList<Transport *>transports() const;
108
109 /**
110 Returns a list of all available transport types.
111 */
112 TransportType::List types() const;
113
114 /**
115 Creates a new, empty Transport object. The object is owned by the caller.
116 If you want to add the Transport permanently (eg. after configuring it)
117 call addTransport().
118 */
119 Transport *createTransport() const;
120
121 /**
122 Adds the given transport. The object ownership is transferred to
123 TransportMananger, ie. you must not delete @p transport.
124 @param transport The Transport object to add.
125 */
126 void addTransport( Transport *transport );
127
128 /**
129 Creates a mail transport job for the given transport identifier.
130 Returns 0 if the specified transport is invalid.
131 @param transportId The transport identifier.
132
133 @deprecated use MessageQueueJob to queue messages
134 and rely on the Dispatcher Agent to send them.
135 */
136 MAILTRANSPORT_DEPRECATED TransportJob *createTransportJob( int transportId );
137
138 /**
139 Creates a mail transport job for the given transport identifer,
140 or transport name.
141 Returns 0 if the specified transport is invalid.
142 @param transport A string defining a mail transport.
143
144 @deprecated use MessageQueueJob to queue messages
145 and rely on the Dispatcher Agent to send them.
146 */
147 MAILTRANSPORT_DEPRECATED TransportJob *createTransportJob( const QString &transport );
148
149 /**
150 Executes the given transport job. This is the preferred way to start
151 transport jobs. It takes care of asynchronously loading passwords from
152 KWallet if necessary.
153 @param job The completely configured transport job to execute.
154
155 @deprecated use MessageQueueJob to queue messages
156 and rely on the Dispatcher Agent to send them.
157 */
158 MAILTRANSPORT_DEPRECATED void schedule( TransportJob *job );
159
160 /**
161 Tries to create a transport based on KEMailSettings.
162 If the data in KEMailSettings is incomplete, no transport is created.
163 */
164 void createDefaultTransport();
165
166 /// Describes when to show the transport creation dialog
167 enum ShowCondition {
168 Always, ///< Show the transport creation dialog unconditionally
169 IfNoTransportExists ///< Only show the transport creation dialog if no transport currently
170 /// exists. Ask the user if he wants to add a transport in
171 /// the other case.
172 };
173
174 /**
175 Shows a dialog for creating and configuring a new transport.
176 @param parent Parent widget of the dialog.
177 @param showCondition the condition under which the dialog is shown at all
178 @return True if a new transport has been created and configured.
179 @since 4.4
180 */
181 bool showTransportCreationDialog( QWidget *parent, ShowCondition showCondition = Always );
182
183 /**
184 Open a configuration dialog for an existing transport.
185 @param transport The transport to configure. It can be a new transport,
186 or one already managed by TransportManager.
187 @param parent The parent widget for the dialog.
188 @return True if the user clicked Ok, false if the user cancelled.
189 @since 4.4
190 */
191 bool configureTransport( Transport *transport, QWidget *parent );
192
193 public Q_SLOTS:
194 /**
195 Returns true if there are no mail transports at all.
196 */
197 Q_SCRIPTABLE bool isEmpty() const;
198
199 /**
200 Returns a list of transport identifiers.
201 */
202 Q_SCRIPTABLE QList<int> transportIds() const;
203
204 /**
205 Returns a list of transport names.
206 */
207 Q_SCRIPTABLE QStringList transportNames() const;
208
209 /**
210 Returns the default transport name.
211 */
212 Q_SCRIPTABLE QString defaultTransportName() const;
213
214 /**
215 Returns the default transport identifier.
216 Invalid if there are no transports at all.
217 */
218 Q_SCRIPTABLE int defaultTransportId() const;
219
220 /**
221 Sets the default transport. The change will be in effect immediately.
222 @param id The identifier of the new default transport.
223 */
224 Q_SCRIPTABLE void setDefaultTransport( int id );
225
226 /**
227 Deletes the specified transport.
228 @param id The identifier of the mail transport to remove.
229 */
230 Q_SCRIPTABLE void removeTransport( int id );
231
232 Q_SIGNALS:
233 /**
234 Emitted when transport settings have changed (by this or any other
235 TransportManager instance).
236 */
237 Q_SCRIPTABLE void transportsChanged();
238
239 /**
240 Internal signal to synchronize all TransportManager instances.
241 This signal is emitted by the instance writing the changes.
242 You probably want to use transportsChanged() instead.
243 */
244 Q_SCRIPTABLE void changesCommitted();
245
246 /**
247 Emitted when passwords have been loaded from the wallet.
248 If you made a deep copy of a transport, you should call updatePasswordState()
249 for the cloned transport to ensure its password is updated as well.
250 */
251 void passwordsChanged();
252
253 /**
254 Emitted when a transport is deleted.
255 @param id The identifier of the deleted transport.
256 @param name The name of the deleted transport.
257 */
258 void transportRemoved( int id, const QString &name );
259
260 /**
261 Emitted when a transport has been renamed.
262 @param id The identifier of the renamed transport.
263 @param oldName The old name.
264 @param newName The new name.
265 */
266 void transportRenamed( int id, const QString &oldName, const QString &newName );
267
268 protected:
269 /**
270 Returns a pointer to an open wallet if available, 0 otherwise.
271 The wallet is opened synchronously if necessary.
272 */
273 KWallet::Wallet *wallet();
274
275 /**
276 Loads all passwords synchronously.
277 */
278 void loadPasswords();
279
280 /**
281 Singleton class, the only instance resides in the static object sSelf.
282 */
283 TransportManager();
284
285 private:
286
287 // These are used by our friend, Transport
288 void emitChangesCommitted();
289
290 private:
291 TransportManagerPrivate *const d;
292
293 Q_PRIVATE_SLOT( d, void slotTransportsChanged() )
294 Q_PRIVATE_SLOT( d, void slotWalletOpened( bool success ) )
295 Q_PRIVATE_SLOT( d, void dbusServiceUnregistered() )
296 Q_PRIVATE_SLOT( d, void agentTypeAdded( const Akonadi::AgentType &atype ) )
297 Q_PRIVATE_SLOT( d, void agentTypeRemoved( const Akonadi::AgentType &atype ) )
298 Q_PRIVATE_SLOT( d, void jobResult( KJob *job ) )
299};
300
301} // namespace MailTransport
302
303#endif // MAILTRANSPORT_TRANSPORTMANAGER_H
304