File indexing completed on 2024-06-23 05:15:12
0001 /* 0002 SPDX-FileCopyrightText: 2006-2007 Volker Krause <vkrause@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #pragma once 0008 0009 #include "mailtransport_export.h" 0010 #include "transporttype.h" 0011 0012 #include <QList> 0013 #include <QObject> 0014 0015 #include <memory> 0016 0017 namespace MailTransport 0018 { 0019 class Transport; 0020 class TransportJob; 0021 class TransportManagerPrivate; 0022 0023 /** 0024 @short Central transport management interface. 0025 0026 This class manages the creation, configuration, and removal of mail 0027 transports, as well as the loading and storing of mail transport settings. 0028 0029 It also handles the creation of transport jobs, although that behaviour is 0030 deprecated and you are encouraged to use MessageQueueJob. 0031 0032 @see MessageQueueJob. 0033 */ 0034 class MAILTRANSPORT_EXPORT TransportManager : public QObject 0035 { 0036 Q_OBJECT 0037 Q_CLASSINFO("D-Bus Interface", "org.kde.pim.TransportManager") 0038 0039 friend class Transport; 0040 friend class TransportManagerPrivate; 0041 0042 public: 0043 /** 0044 Destructor. 0045 */ 0046 ~TransportManager() override; 0047 0048 /** 0049 Returns the TransportManager instance. 0050 */ 0051 static TransportManager *self(); 0052 0053 /** 0054 Tries to load passwords asynchronously from KWallet if needed. 0055 The passwordsChanged() signal is emitted once the passwords have been loaded. 0056 Nothing happens if the passwords were already available. 0057 */ 0058 void loadPasswordsAsync(); 0059 0060 /** 0061 Returns the Transport object with the given id. 0062 @param id The identifier of the Transport. 0063 @param def if set to true, the default transport will be returned if the 0064 specified Transport object could not be found, 0 otherwise. 0065 @returns A Transport object for immediate use. It might become invalid as 0066 soon as the event loop is entered again due to remote changes. If you need 0067 to store a Transport object, store the transport identifier instead. 0068 */ 0069 Transport *transportById(Transport::Id id, bool def = true) const; 0070 0071 /** 0072 Returns the transport object with the given name. 0073 @param name The transport name. 0074 @param def if set to true, the default transport will be returned if the 0075 specified Transport object could not be found, 0 otherwise. 0076 @returns A Transport object for immediate use, see transportById() for 0077 limitations. 0078 */ 0079 Transport *transportByName(const QString &name, bool def = true) const; 0080 0081 /** 0082 Returns a list of all available transports. 0083 Note: The Transport objects become invalid as soon as a change occur, so 0084 they are only suitable for immediate use. 0085 */ 0086 [[nodiscard]] QList<Transport *> transports() const; 0087 0088 /** 0089 Returns a list of all available transport types. 0090 */ 0091 [[nodiscard]] TransportType::List types() const; 0092 0093 /** 0094 Creates a new, empty Transport object. The object is owned by the caller. 0095 If you want to add the Transport permanently (eg. after configuring it) 0096 call addTransport(). 0097 */ 0098 Transport *createTransport() const; 0099 0100 /** 0101 Adds the given transport. The object ownership is transferred to 0102 TransportMananger, ie. you must not delete @p transport. 0103 @param transport The Transport object to add. 0104 */ 0105 void addTransport(Transport *transport); 0106 0107 /** 0108 Creates a mail transport job for the given transport identifier. 0109 Returns 0 if the specified transport is invalid. 0110 @param transportId The transport identifier. 0111 0112 @deprecated use MessageQueueJob to queue messages 0113 and rely on the Dispatcher Agent to send them. 0114 */ 0115 MAILTRANSPORT_DEPRECATED TransportJob *createTransportJob(Transport::Id transportId); 0116 0117 /** 0118 Creates a mail transport job for the given transport identifier, 0119 or transport name. 0120 Returns 0 if the specified transport is invalid. 0121 @param transport A string defining a mail transport. 0122 0123 @deprecated use MessageQueueJob to queue messages 0124 and rely on the Dispatcher Agent to send them. 0125 */ 0126 MAILTRANSPORT_DEPRECATED TransportJob *createTransportJob(const QString &transport); 0127 0128 /** 0129 Executes the given transport job. This is the preferred way to start 0130 transport jobs. It takes care of asynchronously loading passwords from 0131 KWallet if necessary. 0132 @param job The completely configured transport job to execute. 0133 0134 @deprecated use MessageQueueJob to queue messages 0135 and rely on the Dispatcher Agent to send them. 0136 */ 0137 MAILTRANSPORT_DEPRECATED void schedule(TransportJob *job); 0138 0139 /// Describes when to show the transport creation dialog 0140 enum ShowCondition { 0141 Always, ///< Show the transport creation dialog unconditionally 0142 IfNoTransportExists ///< Only show the transport creation dialog if no transport currently 0143 /// exists. Ask the user if he wants to add a transport in 0144 /// the other case. 0145 }; 0146 0147 /** 0148 Shows a dialog for creating and configuring a new transport. 0149 @param parent Parent widget of the dialog. 0150 @param showCondition the condition under which the dialog is shown at all 0151 @return True if a new transport has been created and configured. 0152 @since 4.4 0153 */ 0154 bool showTransportCreationDialog(QWidget *parent, ShowCondition showCondition = Always); 0155 0156 /** 0157 Open a configuration dialog for an existing transport. 0158 @param identifier The identifier. 0159 @param transport The transport to configure. It can be a new transport, 0160 or one already managed by TransportManager. 0161 @param parent The parent widget for the dialog. 0162 @return True if the user clicked Ok, false if the user cancelled. 0163 @since 4.4 0164 */ 0165 bool configureTransport(const QString &identifier, Transport *transport, QWidget *parent); 0166 0167 void initializeTransport(const QString &identifier, Transport *transport); 0168 0169 public: 0170 /** 0171 Returns true if there are no mail transports at all. 0172 */ 0173 Q_SCRIPTABLE bool isEmpty() const; 0174 0175 /** 0176 Returns a list of transport identifiers. 0177 */ 0178 Q_SCRIPTABLE QList<int> transportIds() const; 0179 0180 /** 0181 Returns a list of transport names. 0182 */ 0183 Q_SCRIPTABLE QStringList transportNames() const; 0184 0185 /** 0186 Returns the default transport name. 0187 */ 0188 Q_SCRIPTABLE QString defaultTransportName() const; 0189 0190 /** 0191 Returns the default transport identifier. 0192 Invalid if there are no transports at all. 0193 */ 0194 Q_SCRIPTABLE int defaultTransportId() const; 0195 0196 /** 0197 Sets the default transport. The change will be in effect immediately. 0198 @param id The identifier of the new default transport. 0199 */ 0200 Q_SCRIPTABLE void setDefaultTransport(int id); 0201 0202 /** 0203 Deletes the specified transport. 0204 @param id The identifier of the mail transport to remove. 0205 */ 0206 Q_SCRIPTABLE void removeTransport(int id); 0207 0208 void removePasswordFromWallet(Transport::Id id); 0209 Q_SIGNALS: 0210 /** 0211 Emitted when transport settings have changed (by this or any other 0212 TransportManager instance). 0213 */ 0214 Q_SCRIPTABLE void transportsChanged(); 0215 0216 /** 0217 Internal signal to synchronize all TransportManager instances. 0218 This signal is emitted by the instance writing the changes. 0219 You probably want to use transportsChanged() instead. 0220 */ 0221 Q_SCRIPTABLE void changesCommitted(); 0222 0223 /** 0224 Emitted when passwords have been loaded from the wallet. 0225 If you made a deep copy of a transport, you should call updatePasswordState() 0226 for the cloned transport to ensure its password is updated as well. 0227 */ 0228 void passwordsChanged(); 0229 0230 /** 0231 Emitted when a transport is deleted. 0232 @param id The identifier of the deleted transport. 0233 @param name The name of the deleted transport. 0234 */ 0235 void transportRemoved(int id, const QString &name); 0236 0237 /** 0238 Emitted when a transport has been renamed. 0239 @param id The identifier of the renamed transport. 0240 @param oldName The old name. 0241 @param newName The new name. 0242 */ 0243 void transportRenamed(int id, const QString &oldName, const QString &newName); 0244 0245 protected: 0246 /** 0247 Loads all passwords synchronously. 0248 */ 0249 void loadPasswords(); 0250 0251 /** 0252 Singleton class, the only instance resides in the static object sSelf. 0253 */ 0254 TransportManager(); 0255 0256 private: 0257 // These are used by our friend, Transport 0258 void emitChangesCommitted(); 0259 void updatePluginList(); 0260 0261 private: 0262 std::unique_ptr<TransportManagerPrivate> const d; 0263 0264 Q_PRIVATE_SLOT(d, void slotTransportsChanged()) 0265 }; 0266 } // namespace MailTransport