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