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