MailTransport

transportmanager.h
1 /*
2  SPDX-FileCopyrightText: 2006-2007 Volker Krause <[email protected]>
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 MailTransport
18 {
19 class Transport;
20 class TransportJob;
21 class 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 */
34 class 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 
42 public:
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(int 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  Q_REQUIRED_RESULT QList<Transport *> transports() const;
87 
88  /**
89  Returns a list of all available transport types.
90  */
91  Q_REQUIRED_RESULT 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(int 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  /**
140  Tries to create a transport based on KEMailSettings.
141  If the data in KEMailSettings is incomplete, no transport is created.
142  */
143  void createDefaultTransport();
144 
145  /// Describes when to show the transport creation dialog
147  Always, ///< Show the transport creation dialog unconditionally
148  IfNoTransportExists ///< Only show the transport creation dialog if no transport currently
149  /// exists. Ask the user if he wants to add a transport in
150  /// the other case.
151  };
152 
153  /**
154  Shows a dialog for creating and configuring a new transport.
155  @param parent Parent widget of the dialog.
156  @param showCondition the condition under which the dialog is shown at all
157  @return True if a new transport has been created and configured.
158  @since 4.4
159  */
160  bool showTransportCreationDialog(QWidget *parent, ShowCondition showCondition = Always);
161 
162  /**
163  Open a configuration dialog for an existing transport.
164  @param identifier The identifier.
165  @param transport The transport to configure. It can be a new transport,
166  or one already managed by TransportManager.
167  @param parent The parent widget for the dialog.
168  @return True if the user clicked Ok, false if the user cancelled.
169  @since 4.4
170  */
171  bool configureTransport(const QString &identifier, Transport *transport, QWidget *parent);
172 
173  void initializeTransport(const QString &identifier, Transport *transport);
174 
175 public:
176  /**
177  Returns true if there are no mail transports at all.
178  */
179  Q_SCRIPTABLE bool isEmpty() const;
180 
181  /**
182  Returns a list of transport identifiers.
183  */
184  Q_SCRIPTABLE QVector<int> transportIds() const;
185 
186  /**
187  Returns a list of transport names.
188  */
189  Q_SCRIPTABLE QStringList transportNames() const;
190 
191  /**
192  Returns the default transport name.
193  */
194  Q_SCRIPTABLE QString defaultTransportName() const;
195 
196  /**
197  Returns the default transport identifier.
198  Invalid if there are no transports at all.
199  */
200  Q_SCRIPTABLE int defaultTransportId() const;
201 
202  /**
203  Sets the default transport. The change will be in effect immediately.
204  @param id The identifier of the new default transport.
205  */
206  Q_SCRIPTABLE void setDefaultTransport(int id);
207 
208  /**
209  Deletes the specified transport.
210  @param id The identifier of the mail transport to remove.
211  */
212  Q_SCRIPTABLE void removeTransport(int id);
213 
214  void removePasswordFromWallet(int id);
215 Q_SIGNALS:
216  /**
217  Emitted when transport settings have changed (by this or any other
218  TransportManager instance).
219  */
220  Q_SCRIPTABLE void transportsChanged();
221 
222  /**
223  Internal signal to synchronize all TransportManager instances.
224  This signal is emitted by the instance writing the changes.
225  You probably want to use transportsChanged() instead.
226  */
227  Q_SCRIPTABLE void changesCommitted();
228 
229  /**
230  Emitted when passwords have been loaded from the wallet.
231  If you made a deep copy of a transport, you should call updatePasswordState()
232  for the cloned transport to ensure its password is updated as well.
233  */
234  void passwordsChanged();
235 
236  /**
237  Emitted when a transport is deleted.
238  @param id The identifier of the deleted transport.
239  @param name The name of the deleted transport.
240  */
241  void transportRemoved(int id, const QString &name);
242 
243  /**
244  Emitted when a transport has been renamed.
245  @param id The identifier of the renamed transport.
246  @param oldName The old name.
247  @param newName The new name.
248  */
249  void transportRenamed(int id, const QString &oldName, const QString &newName);
250 
251 protected:
252  /**
253  Loads all passwords synchronously.
254  */
255  void loadPasswords();
256 
257  /**
258  Singleton class, the only instance resides in the static object sSelf.
259  */
261 
262 private:
263  // These are used by our friend, Transport
264  void emitChangesCommitted();
265  void updatePluginList();
266 
267 private:
268  std::unique_ptr<TransportManagerPrivate> const d;
269 
270  Q_PRIVATE_SLOT(d, void slotTransportsChanged())
271 };
272 } // namespace MailTransport
Central transport management interface.
Abstract base class for all mail transport jobs.
Definition: transportjob.h:30
ShowCondition
Describes when to show the transport creation dialog.
@ Always
Show the transport creation dialog unconditionally.
Represents the settings of a specific mail transport.
Definition: transport.h:32
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Thu Mar 23 2023 04:19:12 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.