1 | /* This file is part of the KDE project |
2 | * |
3 | * Copyright (C) 2002-2004 George Staikos <staikos@kde.org> |
4 | * |
5 | * This library is free software; you can redistribute it and/or |
6 | * modify it under the terms of the GNU Library General Public |
7 | * License as published by the Free Software Foundation; either |
8 | * version 2 of the License, or (at your option) any later version. |
9 | * |
10 | * This library is distributed in the hope that it will be useful, |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | * Library General Public License for more details. |
14 | * |
15 | * You should have received a copy of the GNU Library General Public License |
16 | * along with this library; see the file COPYING.LIB. If not, write to |
17 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | * Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | |
22 | #ifndef _KWALLET_H |
23 | #define _KWALLET_H |
24 | |
25 | #include <QtCore/QStringList> |
26 | #include <QtCore/QObject> |
27 | #include <QtGui/qwindowdefs.h> // krazy:exclude=includes (for WId) |
28 | |
29 | #include <kdeui_export.h> |
30 | |
31 | /** |
32 | * NOTE: KSecretsService folder semantics |
33 | * The KWallet API uses folders for organising items. KSecretsService does not |
34 | * have this notion. But it uses attributes that can be applied arbitrarily on |
35 | * all the items. The KWallet code that maps to KSecretsService applies an special |
36 | * attribute KSS_ATTR_ENTRYFOLDER to all items with the currentFolder() value. |
37 | * The KWallet folder API's calls will always succeed and they'll only change the |
38 | * current folder value. The folderList() call will scan all the collection |
39 | * items and collect the KSS_ATTR_ENTRYFOLDER attributes into a list. |
40 | */ |
41 | |
42 | /** |
43 | * NOTE: KWalet API distinguish KSecretsService collection items by attaching |
44 | * them some specific attributes, defined below |
45 | */ |
46 | #define KSS_ATTR_ENTRYFOLDER "kwallet.folderName" |
47 | #define KSS_ATTR_WALLETTYPE "kwallet.type" |
48 | |
49 | class QDBusError; |
50 | |
51 | namespace KWallet { |
52 | |
53 | /** |
54 | * KDE Wallet |
55 | * |
56 | * This class implements a generic system-wide Wallet for KDE. This is the |
57 | * ONLY public interface. |
58 | * |
59 | * @author George Staikos <staikos@kde.org> |
60 | * @short KDE Wallet Class |
61 | */ |
62 | class KDEUI_EXPORT Wallet : public QObject |
63 | { |
64 | Q_OBJECT |
65 | protected: |
66 | /** |
67 | * Construct a KWallet object. |
68 | * @internal |
69 | * @param handle The handle for the wallet. |
70 | * @param name The name of the wallet. |
71 | */ |
72 | Wallet(int handle, const QString& name); |
73 | /** |
74 | * Copy a KWallet object. |
75 | * @internal |
76 | */ |
77 | Wallet(const Wallet&); |
78 | |
79 | public: |
80 | enum EntryType { Unknown=0, Password, Stream, Map, Unused=0xffff }; |
81 | |
82 | /** |
83 | * Destroy a KWallet object. Closes the wallet. |
84 | */ |
85 | virtual ~Wallet(); |
86 | |
87 | /** |
88 | * List all the wallets available. |
89 | * @return Returns a list of the names of all wallets that are |
90 | * open. |
91 | */ |
92 | static QStringList walletList(); |
93 | |
94 | /** |
95 | * Determine if the KDE wallet is enabled. Normally you do |
96 | * not need to use this because openWallet() will just fail. |
97 | * @return Returns true if the wallet enabled, else false. |
98 | */ |
99 | static bool isEnabled(); |
100 | |
101 | /** |
102 | * Determine if the wallet @p name is open by any application. |
103 | * @param name The name of the wallet to check. |
104 | * @return Returns true if the wallet is open, else false. |
105 | */ |
106 | static bool isOpen(const QString& name); |
107 | |
108 | /** |
109 | * Close the wallet @p name. The wallet will only be closed |
110 | * if it is open but not in use (rare), or if it is forced |
111 | * closed. |
112 | * @param name The name of the wallet to close. |
113 | * @param force Set true to force the wallet closed even if it |
114 | * is in use by others. |
115 | * @return Returns 0 on success, non-zero on error. |
116 | */ |
117 | static int closeWallet(const QString& name, bool force); |
118 | |
119 | /** |
120 | * Delete the wallet @p name. The wallet will be forced closed |
121 | * first. |
122 | * @param name The name of the wallet to delete. |
123 | * @return Returns 0 on success, non-zero on error. |
124 | */ |
125 | static int deleteWallet(const QString& name); |
126 | |
127 | /** |
128 | * Disconnect the application @p app from @p wallet. |
129 | * @param wallet The name of the wallet to disconnect. |
130 | * @param app The name of the application to disconnect. |
131 | * @return Returns true on success, false on error. |
132 | */ |
133 | static bool disconnectApplication(const QString& wallet, const QString& app); |
134 | |
135 | enum OpenType { Synchronous=0, Asynchronous, Path, OpenTypeUnused=0xff }; |
136 | |
137 | /** |
138 | * Open the wallet @p name. The user will be prompted to |
139 | * allow your application to open the wallet, and may be |
140 | * prompted for a password. You are responsible for deleting |
141 | * this object when you are done with it. |
142 | * @param name The name of the wallet to open. |
143 | * @param ot If Asynchronous, the call will return |
144 | * immediately with a non-null pointer to an |
145 | * invalid wallet. You must immediately connect |
146 | * the walletOpened() signal to a slot so that |
147 | * you will know when it is opened, or when it |
148 | * fails. |
149 | * @param w The window id to associate any dialogs with. You can pass |
150 | * 0 if you don't have a window the password dialog should |
151 | * associate with. |
152 | * @return Returns a pointer to the wallet if successful, |
153 | * or a null pointer on error or if rejected. |
154 | */ |
155 | static Wallet* openWallet(const QString& name, WId w, OpenType ot = Synchronous); |
156 | |
157 | /** |
158 | * List the applications that are using the wallet @p wallet. |
159 | * @param wallet The wallet to query. |
160 | * @return Returns a list of all DCOP application IDs using |
161 | * the wallet. |
162 | */ |
163 | static QStringList users(const QString& wallet); |
164 | |
165 | /** |
166 | * The name of the wallet used to store local passwords. |
167 | */ |
168 | static const QString LocalWallet(); |
169 | |
170 | /** |
171 | * The name of the wallet used to store network passwords. |
172 | */ |
173 | static const QString NetworkWallet(); |
174 | |
175 | /** |
176 | * The standardized name of the password folder. |
177 | * It is automatically created when a wallet is created, but |
178 | * the user may still delete it so you should check for its |
179 | * existence and recreate it if necessary and desired. |
180 | */ |
181 | static const QString PasswordFolder(); |
182 | |
183 | /** |
184 | * The standardized name of the form data folder. |
185 | * It is automatically created when a wallet is created, but |
186 | * the user may still delete it so you should check for its |
187 | * existence and recreate it if necessary and desired. |
188 | */ |
189 | static const QString FormDataFolder(); |
190 | |
191 | /** |
192 | * Request to the wallet service to change the password of |
193 | * the wallet @p name. |
194 | * @param name The the wallet to change the password of. |
195 | * @param w The window id to associate any dialogs with. You can pass |
196 | * 0 if you don't have a window the password dialog should |
197 | * associate with. |
198 | */ |
199 | static void changePassword(const QString& name, WId w); |
200 | |
201 | /** |
202 | * This syncs the wallet file on disk with what is in memory. |
203 | * You don't normally need to use this. It happens |
204 | * automatically on close. |
205 | * @return Returns 0 on success, non-zero on error. |
206 | */ |
207 | virtual int sync(); |
208 | |
209 | /** |
210 | * This closes and locks the current wallet. It will |
211 | * disconnect all applications using the wallet. |
212 | * @return Returns 0 on success, non-zero on error. |
213 | */ |
214 | virtual int lockWallet(); |
215 | |
216 | /** |
217 | * The name of the current wallet. |
218 | */ |
219 | virtual const QString& walletName() const; |
220 | |
221 | /** |
222 | * Determine if the current wallet is open, and is a valid |
223 | * wallet handle. |
224 | * @return Returns true if the wallet handle is valid and open. |
225 | */ |
226 | virtual bool isOpen() const; |
227 | |
228 | /** |
229 | * Request to the wallet service to change the password of |
230 | * the current wallet. |
231 | * @param w The window id to associate any dialogs with. You can pass |
232 | * 0 if you don't have a window the password dialog should |
233 | * associate with. |
234 | */ |
235 | virtual void requestChangePassword(WId w); |
236 | |
237 | /** |
238 | * Obtain the list of all folders contained in the wallet. |
239 | * @return Returns an empty list if the wallet is not open. |
240 | */ |
241 | virtual QStringList folderList(); |
242 | |
243 | /** |
244 | * Determine if the folder @p f exists in the wallet. |
245 | * @param f the name of the folder to check for |
246 | * @return Returns true if the folder exists in the wallet. |
247 | */ |
248 | virtual bool hasFolder(const QString& f); |
249 | |
250 | /** |
251 | * Set the current working folder to @p f. The folder must |
252 | * exist, or this call will fail. Create a folder with |
253 | * createFolder(). |
254 | * @param f the name of the folder to make the working folder |
255 | * @return Returns true if the folder was successfully set. |
256 | */ |
257 | virtual bool setFolder(const QString& f); |
258 | |
259 | /** |
260 | * Remove the folder @p f and all its entries from the wallet. |
261 | * @param f the name of the folder to remove |
262 | * @return Returns true if the folder was successfully removed. |
263 | */ |
264 | virtual bool removeFolder(const QString& f); |
265 | |
266 | /** |
267 | * Created the folder @p f. |
268 | * @param f the name of the folder to create |
269 | * @return Returns true if the folder was successfully created. |
270 | */ |
271 | virtual bool createFolder(const QString& f); |
272 | |
273 | /** |
274 | * Determine the current working folder in the wallet. |
275 | * If the folder name is empty, it is working in the global |
276 | * folder, which is valid but discouraged. |
277 | * @return Returns the current working folder. |
278 | */ |
279 | virtual const QString& currentFolder() const; |
280 | |
281 | /** |
282 | * Return the list of keys of all entries in this folder. |
283 | * @return Returns an empty list if the wallet is not open, or |
284 | * if the folder is empty. |
285 | */ |
286 | virtual QStringList entryList(); |
287 | |
288 | /** |
289 | * Rename the entry @p oldName to @p newName. |
290 | * @param oldName The original key of the entry. |
291 | * @param newName The new key of the entry. |
292 | * @return Returns 0 on success, non-zero on error. |
293 | */ |
294 | virtual int renameEntry(const QString& oldName, const QString& newName); |
295 | |
296 | /** |
297 | * Read the entry @p key from the current folder. |
298 | * The entry format is unknown except that it is either a |
299 | * QByteArray or a QDataStream, which effectively means that |
300 | * it is anything. |
301 | * @param key The key of the entry to read. |
302 | * @param value A buffer to fill with the value. |
303 | * @return Returns 0 on success, non-zero on error. |
304 | */ |
305 | virtual int readEntry(const QString& key, QByteArray& value); |
306 | |
307 | /** |
308 | * Read the map entry @p key from the current folder. |
309 | * @param key The key of the entry to read. |
310 | * @param value A map buffer to fill with the value. |
311 | * @return Returns 0 on success, non-zero on error. Will |
312 | * return an error if the key was not originally |
313 | * written as a map. |
314 | */ |
315 | virtual int readMap(const QString& key, QMap<QString,QString>& value); |
316 | |
317 | /** |
318 | * Read the password entry @p key from the current folder. |
319 | * @param key The key of the entry to read. |
320 | * @param value A password buffer to fill with the value. |
321 | * @return Returns 0 on success, non-zero on error. Will |
322 | * return an error if the key was not originally |
323 | * written as a password. |
324 | */ |
325 | virtual int readPassword(const QString& key, QString& value); |
326 | |
327 | /** |
328 | * Read the entries matching @p key from the current folder. |
329 | * The entry format is unknown except that it is either a |
330 | * QByteArray or a QDataStream, which effectively means that |
331 | * it is anything. |
332 | * @param key The key of the entry to read. Wildcards |
333 | * are supported. |
334 | * @param value A buffer to fill with the value. The key in |
335 | * the map is the entry key. |
336 | * @return Returns 0 on success, non-zero on error. |
337 | */ |
338 | int readEntryList(const QString& key, QMap<QString, QByteArray>& value); |
339 | |
340 | /** |
341 | * Read the map entry @p key from the current folder. |
342 | * @param key The key of the entry to read. Wildcards |
343 | * are supported. |
344 | * @param value A buffer to fill with the value. The key in |
345 | * the map is the entry key. |
346 | * @return Returns 0 on success, non-zero on error. Will |
347 | * return an error if the key was not originally |
348 | * written as a map. |
349 | */ |
350 | int readMapList(const QString& key, QMap<QString, QMap<QString, QString> >& value); |
351 | |
352 | /** |
353 | * Read the password entry @p key from the current folder. |
354 | * @param key The key of the entry to read. Wildcards |
355 | * are supported. |
356 | * @param value A buffer to fill with the value. The key in |
357 | * the map is the entry key. |
358 | * @return Returns 0 on success, non-zero on error. Will |
359 | * return an error if the key was not originally |
360 | * written as a password. |
361 | */ |
362 | int readPasswordList(const QString& key, QMap<QString, QString>& value); |
363 | |
364 | /** |
365 | * Write @p key = @p value as a binary entry to the current |
366 | * folder. Be careful with this, it could cause inconsistency |
367 | * in the future since you can put an arbitrary entry type in |
368 | * place. |
369 | * @param key The key of the new entry. |
370 | * @param value The value of the entry. |
371 | * @param entryType The type of the entry. |
372 | * @return Returns 0 on success, non-zero on error. |
373 | */ |
374 | virtual int writeEntry(const QString& key, const QByteArray& value, EntryType entryType); |
375 | |
376 | /** |
377 | * Write @p key = @p value as a binary entry to the current |
378 | * folder. |
379 | * @param key The key of the new entry. |
380 | * @param value The value of the entry. |
381 | * @return Returns 0 on success, non-zero on error. |
382 | */ |
383 | virtual int writeEntry(const QString& key, const QByteArray& value); |
384 | |
385 | /** |
386 | * Write @p key = @p value as a map to the current folder. |
387 | * @param key The key of the new entry. |
388 | * @param value The value of the map. |
389 | * @return Returns 0 on success, non-zero on error. |
390 | */ |
391 | virtual int writeMap(const QString& key, const QMap<QString,QString>& value); |
392 | |
393 | /** |
394 | * Write @p key = @p value as a password to the current folder. |
395 | * @param key The key of the new entry. |
396 | * @param value The value of the password. |
397 | * @return Returns 0 on success, non-zero on error. |
398 | */ |
399 | virtual int writePassword(const QString& key, const QString& value); |
400 | |
401 | /** |
402 | * Determine if the current folder has they entry @p key. |
403 | * @param key The key to search for. |
404 | * @return Returns true if the folder contains @p key. |
405 | */ |
406 | virtual bool hasEntry(const QString& key); |
407 | |
408 | /** |
409 | * Remove the entry @p key from the current folder. |
410 | * @param key The key to remove. |
411 | * @return Returns 0 on success, non-zero on error. |
412 | */ |
413 | virtual int removeEntry(const QString& key); |
414 | |
415 | /** |
416 | * Determine the type of the entry @p key in this folder. |
417 | * @param key The key to look up. |
418 | * @return Returns an enumerated type representing the type |
419 | * of the entry. |
420 | */ |
421 | virtual EntryType entryType(const QString& key); |
422 | |
423 | /** |
424 | * Determine if a folder does not exist in a wallet. This |
425 | * does not require decryption of the wallet. |
426 | * This is a handy optimization to avoid prompting the user |
427 | * if your data is certainly not in the wallet. |
428 | * @param wallet The wallet to look in. |
429 | * @param folder The folder to look up. |
430 | * @return Returns true if the folder does NOT exist in the |
431 | * wallet, or the wallet does not exist. |
432 | */ |
433 | static bool folderDoesNotExist(const QString& wallet, const QString& folder); |
434 | |
435 | /** |
436 | * Determine if an entry in a folder does not exist in a |
437 | * wallet. This does not require decryption of the wallet. |
438 | * This is a handy optimization to avoid prompting the user |
439 | * if your data is certainly not in the wallet. |
440 | * @param wallet The wallet to look in. |
441 | * @param folder The folder to look in. |
442 | * @param key The key to look up. |
443 | * @return Returns true if the key does NOT exist in the |
444 | * wallet, or the folder or wallet does not exist. |
445 | */ |
446 | static bool keyDoesNotExist(const QString& wallet, const QString& folder, |
447 | const QString& key); |
448 | |
449 | /** |
450 | * Determine if the KWallet API is using the KSecretsService infrastructure |
451 | * This can ben changed in system settings |
452 | * @return Returns true if the KSecretsService infrastructure is active |
453 | */ |
454 | static bool isUsingKSecretsService(); |
455 | |
456 | Q_SIGNALS: |
457 | /** |
458 | * Emitted when this wallet is closed. |
459 | */ |
460 | void walletClosed(); |
461 | |
462 | /** |
463 | * Emitted when a folder in this wallet is updated. |
464 | * @param folder The folder that was updated. |
465 | */ |
466 | void folderUpdated(const QString& folder); |
467 | |
468 | /** |
469 | * Emitted when the folder list is changed in this wallet. |
470 | */ |
471 | void folderListUpdated(); |
472 | |
473 | /** |
474 | * Emitted when a folder in this wallet is removed. |
475 | * @param folder The folder that was removed. |
476 | */ |
477 | void folderRemoved(const QString& folder); |
478 | |
479 | /** |
480 | * Emitted when a wallet is opened in asynchronous mode. |
481 | * @param success True if the wallet was opened successfully. |
482 | */ |
483 | void walletOpened(bool success); |
484 | |
485 | private Q_SLOTS: |
486 | /** |
487 | * @internal |
488 | * DBUS slot for signals emitted by the wallet service. |
489 | */ |
490 | void slotWalletClosed(int handle); |
491 | |
492 | /** |
493 | * @internal |
494 | * DBUS slot for signals emitted by the wallet service. |
495 | */ |
496 | void slotFolderUpdated(const QString& wallet, const QString& folder); |
497 | |
498 | /** |
499 | * @internal |
500 | * DBUS slot for signals emitted by the wallet service. |
501 | */ |
502 | void slotFolderListUpdated(const QString& wallet); |
503 | |
504 | /** |
505 | * @internal |
506 | * DBUS slot for signals emitted by the wallet service. |
507 | */ |
508 | void slotApplicationDisconnected(const QString& wallet, const QString& application); |
509 | |
510 | /** |
511 | * @internal |
512 | * Callback for kwalletd |
513 | * @param tId identifer for the open transaction |
514 | * @param handle the wallet's handle |
515 | */ |
516 | void walletAsyncOpened(int tId, int handle); |
517 | |
518 | /** |
519 | * @internal |
520 | * DBUS error slot. |
521 | */ |
522 | void emitWalletAsyncOpenError(); |
523 | |
524 | /** |
525 | * @internal |
526 | * Emits wallet opening success. |
527 | */ |
528 | void emitWalletOpened(); |
529 | |
530 | /** |
531 | * @internal |
532 | * Receives status changed notifications from KSecretsService infrastructure |
533 | */ |
534 | void slotCollectionStatusChanged( int ); |
535 | /** |
536 | * @internal |
537 | * Received delete notification from KSecretsService infrastructure |
538 | */ |
539 | void slotCollectionDeleted(); |
540 | |
541 | private: |
542 | class WalletPrivate; |
543 | WalletPrivate* const d; |
544 | Q_PRIVATE_SLOT(d, void walletServiceUnregistered()) |
545 | |
546 | protected: |
547 | /** |
548 | * @internal |
549 | */ |
550 | virtual void virtual_hook(int id, void *data); |
551 | }; |
552 | |
553 | } |
554 | |
555 | #endif //_KWALLET_H |
556 | |
557 | |