MailTransport

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

KDE's Doxygen guidelines are available online.