diff options
Diffstat (limited to 'kwallet/client/kwallet.h')
| -rw-r--r-- | kwallet/client/kwallet.h | 520 |
1 files changed, 520 insertions, 0 deletions
diff --git a/kwallet/client/kwallet.h b/kwallet/client/kwallet.h new file mode 100644 index 000000000..e49839ddc --- /dev/null +++ b/kwallet/client/kwallet.h @@ -0,0 +1,520 @@ +/* This file is part of the KDE project + * + * Copyright (C) 2002-2004 George Staikos <staikos@kde.org> + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Library General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Library General Public License for more details. + * + * You should have received a copy of the GNU Library General Public License + * along with this library; see the file COPYING.LIB. If not, write to + * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + * Boston, MA 02110-1301, USA. + */ + + +#ifndef _KWALLET_H +#define _KWALLET_H + +#include <qglobal.h> +#ifdef Q_OS_UNIX + +#include <qstring.h> +#include <qstringlist.h> +#include <qobject.h> +#include <dcopobject.h> + +class DCOPRef; + +/** Namespace collecting all the Wallet-related classes. */ +namespace KWallet { + +/** + * KDE Wallet + * + * This class implements a generic system-wide Wallet for KDE. This is the + * ONLY public interface. The DCOP client is unsupported and considered to be + * private. + * + * @author George Staikos <staikos@kde.org> + * @short KDE Wallet Class + */ +class KIO_EXPORT Wallet : public QObject, public DCOPObject { + K_DCOP + Q_OBJECT + protected: + /** + * Construct a KWallet object. + * @internal + * @param handle The handle for the wallet. + * @param name The name of the wallet. + */ + Wallet(int handle, const QString& name); + /** + * Copy a KWallet object. + * @internal + */ + Wallet(const Wallet&); + + public: + enum EntryType { Unknown=0, Password, Stream, Map, Unused=0xffff }; + + /** + * Destroy a KWallet object. Closes the wallet. + */ + virtual ~Wallet(); + + /** + * List all the wallets available. + * @return Returns a list of the names of all wallets that are + * open. + */ + static QStringList walletList(); + + /** + * Determine if the KDE wallet is enabled. Normally you do + * not need to use this because open() will just fail. + * @return Returns true if the wallet enabled, else false. + */ + static bool isEnabled(); + + /** + * Determine if the wallet @p name is open by any application. + * @param name The name of the wallet to check. + * @return Returns true if the wallet is open, else false. + */ + static bool isOpen(const QString& name); + + /** + * Close the wallet @p name. The wallet will only be closed + * if it is open but not in use (rare), or if it is forced + * closed. + * @param name The name of the wallet to close. + * @param force Set true to force the wallet closed even if it + * is in use by others. + * @return Returns 0 on success, non-zero on error. + */ + static int closeWallet(const QString& name, bool force); + + /** + * Delete the wallet @p name. The wallet will be forced closed + * first. + * @param name The name of the wallet to delete. + * @return Returns 0 on success, non-zero on error. + */ + static int deleteWallet(const QString& name); + + /** + * Disconnect the application @p app from @p wallet. + * @param wallet The name of the wallet to disconnect. + * @param app The name of the application to disconnect. + * @return Returns true on success, false on error. + */ + static bool disconnectApplication(const QString& wallet, const QCString& app); + + enum OpenType { Synchronous=0, Asynchronous, Path, OpenTypeUnused=0xff }; + + /** + * Open the wallet @p name. The user will be prompted to + * allow your application to open the wallet, and may be + * prompted for a password. You are responsible for deleting + * this object when you are done with it. + * @param name The name of the wallet to open. + * @param ot If Asynchronous, the call will return + * immediately with a non-null pointer to an + * invalid wallet. You must immediately connect + * the walletOpened() signal to a slot so that + * you will know when it is opened, or when it + * fails. + * @param w The window id to associate any dialogs with. + * @return Returns a pointer to the wallet if successful, + * or a null pointer on error or if rejected. + */ + static Wallet* openWallet(const QString& name, WId w = 0, OpenType ot = Synchronous); + + /** + * List the applications that are using the wallet @p wallet. + * @param wallet The wallet to query. + * @return Returns a list of all DCOP application IDs using + * the wallet. + */ + static QStringList users(const QString& wallet); + + /** + * The name of the wallet used to store local passwords. + */ + static const QString LocalWallet(); + + /** + * The name of the wallet used to store network passwords. + */ + static const QString NetworkWallet(); + + /** + * The standardized name of the password folder. + * It is automatically created when a wallet is created, but + * the user may still delete it so you should check for its + * existence and recreate it if necessary and desired. + */ + static const QString PasswordFolder(); + + /** + * The standardized name of the form data folder. + * It is automatically created when a wallet is created, but + * the user may still delete it so you should check for its + * existence and recreate it if necessary and desired. + */ + static const QString FormDataFolder(); + + /** + * Request to the wallet service to change the password of + * the wallet @p name. + * @param name The the wallet to change the password of. + * @param w The window id to associate any dialogs with. + */ + static void changePassword(const QString& name, WId w = 0); + + /** + * This syncs the wallet file on disk with what is in memory. + * You don't normally need to use this. It happens + * automatically on close. + * @return Returns 0 on success, non-zero on error. + */ + virtual int sync(); + + /** + * This closes and locks the current wallet. It will + * disconnect all applications using the wallet. + * @return Returns 0 on success, non-zero on error. + */ + virtual int lockWallet(); + + /** + * The name of the current wallet. + */ + virtual const QString& walletName() const; + + /** + * Determine if the current wallet is open, and is a valid + * wallet handle. + * @return Returns true if the wallet handle is valid and open. + */ + virtual bool isOpen() const; + + /** + * Request to the wallet service to change the password of + * the current wallet. + * @param w The window id to associate any dialogs with. + */ + virtual void requestChangePassword(WId w = 0); + + /** + * Obtain the list of all folders contained in the wallet. + * @return Returns an empty list if the wallet is not open. + */ + virtual QStringList folderList(); + + /** + * Determine if the folder @p f exists in the wallet. + * @param f the name of the folder to check for + * @return Returns true if the folder exists in the wallet. + */ + virtual bool hasFolder(const QString& f); + + /** + * Set the current working folder to @p f. The folder must + * exist, or this call will fail. Create a folder with + * createFolder(). + * @param f the name of the folder to make the working folder + * @return Returns true if the folder was successfully set. + */ + virtual bool setFolder(const QString& f); + + /** + * Remove the folder @p f and all its entries from the wallet. + * @param f the name of the folder to remove + * @return Returns true if the folder was successfully removed. + */ + virtual bool removeFolder(const QString& f); + + /** + * Created the folder @p f. + * @param f the name of the folder to create + * @return Returns true if the folder was successfully created. + */ + virtual bool createFolder(const QString& f); + + /** + * Determine the current working folder in the wallet. + * If the folder name is empty, it is working in the global + * folder, which is valid but discouraged. + * @return Returns the current working folder. + */ + virtual const QString& currentFolder() const; + + /** + * Return the list of keys of all entries in this folder. + * @return Returns an empty list if the wallet is not open, or + * if the folder is empty. + */ + virtual QStringList entryList(); + + /** + * Rename the entry @p oldName to @p newName. + * @param oldName The original key of the entry. + * @param newName The new key of the entry. + * @return Returns 0 on success, non-zero on error. + */ + virtual int renameEntry(const QString& oldName, const QString& newName); + + /** + * Read the entry @p key from the current folder. + * The entry format is unknown except that it is either a + * QByteArray or a QDataStream, which effectively means that + * it is anything. + * @param key The key of the entry to read. + * @param value A buffer to fill with the value. + * @return Returns 0 on success, non-zero on error. + */ + virtual int readEntry(const QString& key, QByteArray& value); + + /** + * Read the map entry @p key from the current folder. + * @param key The key of the entry to read. + * @param value A map buffer to fill with the value. + * @return Returns 0 on success, non-zero on error. Will + * return an error if the key was not originally + * written as a map. + */ + virtual int readMap(const QString& key, QMap<QString,QString>& value); + + /** + * Read the password entry @p key from the current folder. + * @param key The key of the entry to read. + * @param value A password buffer to fill with the value. + * @return Returns 0 on success, non-zero on error. Will + * return an error if the key was not originally + * written as a password. + */ + virtual int readPassword(const QString& key, QString& value); + + /** + * Read the entries matching @p key from the current folder. + * The entry format is unknown except that it is either a + * QByteArray or a QDataStream, which effectively means that + * it is anything. + * @param key The key of the entry to read. Wildcards + * are supported. + * @param value A buffer to fill with the value. The key in + * the map is the entry key. + * @return Returns 0 on success, non-zero on error. + * @since 3.4 + */ + int readEntryList(const QString& key, QMap<QString, QByteArray>& value); + + /** + * Read the map entry @p key from the current folder. + * @param key The key of the entry to read. Wildcards + * are supported. + * @param value A buffer to fill with the value. The key in + * the map is the entry key. + * @return Returns 0 on success, non-zero on error. Will + * return an error if the key was not originally + * written as a map. + * @since 3.4 + */ + int readMapList(const QString& key, QMap<QString, QMap<QString, QString> >& value); + + /** + * Read the password entry @p key from the current folder. + * @param key The key of the entry to read. Wildcards + * are supported. + * @param value A buffer to fill with the value. The key in + * the map is the entry key. + * @return Returns 0 on success, non-zero on error. Will + * return an error if the key was not originally + * written as a password. + * @since 3.4 + */ + int readPasswordList(const QString& key, QMap<QString, QString>& value); + + /** + * Write @p key = @p value as a binary entry to the current + * folder. Be careful with this, it could cause inconsistency + * in the future since you can put an arbitrary entry type in + * place. + * @param key The key of the new entry. + * @param value The value of the entry. + * @param entryType The type of the entry. + * @return Returns 0 on success, non-zero on error. + */ + virtual int writeEntry(const QString& key, const QByteArray& value, EntryType entryType); + + /** + * Write @p key = @p value as a binary entry to the current + * folder. + * @param key The key of the new entry. + * @param value The value of the entry. + * @return Returns 0 on success, non-zero on error. + */ + virtual int writeEntry(const QString& key, const QByteArray& value); + + /** + * Write @p key = @p value as a map to the current folder. + * @param key The key of the new entry. + * @param value The value of the map. + * @return Returns 0 on success, non-zero on error. + */ + virtual int writeMap(const QString& key, const QMap<QString,QString>& value); + + /** + * Write @p key = @p value as a password to the current folder. + * @param key The key of the new entry. + * @param value The value of the password. + * @return Returns 0 on success, non-zero on error. + */ + virtual int writePassword(const QString& key, const QString& value); + + /** + * Determine if the current folder has they entry @p key. + * @param key The key to search for. + * @return Returns true if the folder contains @p key. + */ + virtual bool hasEntry(const QString& key); + + /** + * Remove the entry @p key from the current folder. + * @param key The key to remove. + * @return Returns 0 on success, non-zero on error. + */ + virtual int removeEntry(const QString& key); + + /** + * Determine the type of the entry @p key in this folder. + * @param key The key to look up. + * @return Returns an enumerated type representing the type + * of the entry. + */ + virtual EntryType entryType(const QString& key); + + /** + * Determine if a folder does not exist in a wallet. This + * does not require decryption of the wallet. + * This is a handy optimization to avoid prompting the user + * if your data is certainly not in the wallet. + * @param wallet The wallet to look in. + * @param folder The folder to look up. + * @return Returns true if the folder does NOT exist in the + * wallet, or the wallet does not exist. + */ + static bool folderDoesNotExist(const QString& wallet, const QString& folder); + + /** + * Determine if an entry in a folder does not exist in a + * wallet. This does not require decryption of the wallet. + * This is a handy optimization to avoid prompting the user + * if your data is certainly not in the wallet. + * @param wallet The wallet to look in. + * @param folder The folder to look in. + * @param key The key to look up. + * @return Returns true if the key does NOT exist in the + * wallet, or the folder or wallet does not exist. + */ + static bool keyDoesNotExist(const QString& wallet, const QString& folder, + const QString& key); + + signals: + /** + * Emitted when this wallet is closed. + */ + void walletClosed(); + + /** + * Emitted when a folder in this wallet is updated. + * @param folder The folder that was updated. + */ + void folderUpdated(const QString& folder); + + /** + * Emitted when the folder list is changed in this wallet. + */ + void folderListUpdated(); + + /** + * Emitted when a folder in this wallet is removed. + * @param folder The folder that was removed. + */ + void folderRemoved(const QString& folder); + + /** + * Emitted when a wallet is opened in asynchronous mode. + * @param success True if the wallet was opened successfully. + */ + void walletOpened(bool success); + + private: + k_dcop: + /** + * @internal + * DCOP slot for signals emitted by the wallet service. + */ + ASYNC slotWalletClosed(int handle); + + /** + * @internal + * DCOP slot for signals emitted by the wallet service. + */ + ASYNC slotFolderUpdated(const QString& wallet, const QString& folder); + + /** + * @internal + * DCOP slot for signals emitted by the wallet service. + */ + ASYNC slotFolderListUpdated(const QString& wallet); + + /** + * @internal + * DCOP slot for signals emitted by the wallet service. + */ + ASYNC slotApplicationDisconnected(const QString& wallet, const QCString& application); + + /** + * @internal + * Callback for kwalletd + */ + ASYNC walletOpenResult(int rc); + + private slots: + /** + * @internal + * Used to detect when the wallet service dies. + */ + void slotAppUnregistered(const QCString&); + + private: + class WalletPrivate; + WalletPrivate *d; + QString _name; + QString _folder; + int _handle; + DCOPRef *_dcopRef; + + protected: + /** + * @internal + */ + virtual void virtual_hook(int id, void *data); +}; + +} + +#endif //Q_OS_UNIX + +#endif //_KWALLET_H + |