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
49class QDBusError;
50
51namespace 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 */
62class 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