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