KWallet

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

KDE's Doxygen guidelines are available online.