1 /* 2 kopetepassword.h - Kopete Password 3 4 Copyright (c) 2004 by Richard Smith <kde@metafoo.co.uk> 5 Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org> 6 7 ************************************************************************* 8 * * 9 * This library is free software; you can redistribute it and/or * 10 * modify it under the terms of the GNU Lesser General Public * 11 * License as published by the Free Software Foundation; either * 12 * version 2 of the License, or (at your option) any later version. * 13 * * 14 ************************************************************************* 15 */ 16 17 #ifndef KOPETEPASSWORD_H 18 #define KOPETEPASSWORD_H 19 20 #include <QObject> 21 #include <QPixmap> 22 23 #include "libkopete_export.h" 24 25 namespace KWallet { 26 class Wallet; 27 } 28 29 class QPixmap; 30 31 /** @internal */ 32 class KopetePasswordGetRequest; 33 /** @internal */ 34 class KopetePasswordSetRequest; 35 /** @internal */ 36 class KopetePasswordClearRequest; 37 38 namespace Kopete { 39 /** 40 * @author Richard Smith <kde@metafoo.co.uk> 41 * 42 * The Kopete::Password object is responsible for storing and retrieving a 43 * password for a plugin or account object. 44 * 45 * If the KWallet is active, passwords will be stored in it, otherwise, they 46 * will be stored in the KConfig, in a slightly mangled form. 47 */ 48 class LIBKOPETE_EXPORT Password : public QObject 49 { 50 Q_OBJECT 51 52 public: 53 /** 54 * Create a new Kopete::Password object. 55 * 56 * @param configGroup The configuration group to save passwords in. 57 * @param allowBlankPassword If this password is allowed to be blank 58 */ 59 explicit Password(const QString &configGroup, bool allowBlankPassword = false); 60 61 /** 62 * Create a shallow copy of this object 63 */ 64 Password(const Password &other); 65 ~Password(); 66 67 /** 68 * Assignment operator for passwords: make this object represent a different password 69 */ 70 Password &operator=(Password &other); 71 72 /** 73 * Returns the preferred size for images passed to the retrieve and request functions. 74 */ 75 static int preferredImageSize(); 76 77 /** 78 * @brief Returns whether the password currently stored by this object is known to be incorrect. 79 * This flag gets reset whenever the user enters a new password, and is 80 * expected to be set by the user of this class if it is detected that the 81 * password the user entered is wrong. 82 */ 83 bool isWrong(); 84 /** 85 * Flag the password as being incorrect. 86 * @see isWrong 87 */ 88 void setWrong(bool bWrong = true); 89 90 /** 91 * Type of password request to perform: 92 * FromConfigOrUser : get the password from the config file, or from the user 93 * if no password in config. 94 * FromUser : always ask the user for a password (ie, if last password was 95 * wrong or you know the password has changed). 96 */ 97 enum PasswordSource { 98 FromConfigOrUser, FromUser 99 }; 100 101 /** 102 * @brief Start an asynchronous call to get the password. 103 * Causes a password entry dialog to appear if the password is not set. Triggers 104 * a provided slot when done, but not until after this function has returned (you 105 * don't need to worry about reentrancy or nested event loops). 106 * 107 * @param receiver The object to notify when the password request finishes 108 * @param slot The slot on receiver to call at the end of the request. The signature 109 * of this function should be slot( const QString &password ). password will 110 * be the password if successful, or QString() if failed. 111 * @param image The icon to display in the dialog when asking for the password 112 * @param prompt The message to display to the user, asking for a 113 * password. Can be any Qt RichText string. 114 * @param source The source the password is taken from if a wrong or 115 * invalid password is entered or the password could not be found in the wallet 116 */ 117 void request(QObject *receiver, const char *slot, const QPixmap &image, const QString &prompt, PasswordSource source = FromConfigOrUser); 118 119 /** 120 * @brief Start an asynchronous password request without a prompt 121 * 122 * Starts an asynchronous password request. Does not pop up a password entry dialog 123 * if there is no password. 124 * @see request(QObject*,const char*,const QPixmap&,const QString&,bool,unsigned int) 125 * The password given to the provided slot will be NULL if no password could be retrieved for 126 * some reason, such as the user declining to open the wallet, or no password being found. 127 */ 128 void requestWithoutPrompt(QObject *receiver, const char *slot); 129 130 /** 131 * @return true if the password is remembered, false otherwise. 132 * 133 * If it returns false, calling @ref request() will 134 * pop up an Enter Password window. 135 */ 136 bool remembered(); 137 138 /** 139 * @return true if you are allowed to have a blank password 140 */ 141 bool allowBlankPassword(); 142 143 /** 144 * When a password request succeeds, the password is cached. This function 145 * returns the cached password, if there is one, or QString() if there 146 * is not. 147 */ 148 QString cachedValue(); 149 150 public Q_SLOTS: 151 /** 152 * Set the password for this account. 153 * @param pass If set to QString(), the password is forgotten unless you 154 * specified to allow blank passwords. Otherwise, sets the password to 155 * this value. 156 * 157 * Note: this function is asynchronous; changes will not be instant. 158 */ 159 void set(const QString &pass = QString()); 160 161 /** 162 * Unconditionally clears the stored password 163 */ 164 void clear(); 165 166 private: 167 void readConfig(); 168 void writeConfig(); 169 170 class Private; 171 Private *d; 172 173 //TODO: can we rearrange things so these aren't friends? 174 friend class ::KopetePasswordGetRequest; 175 friend class ::KopetePasswordSetRequest; 176 friend class ::KopetePasswordClearRequest; 177 }; 178 } 179 180 /** 181 * This class is an implementation detail of KopetePassword. 182 * @internal 183 * @see KopetePassword 184 */ 185 class KopetePasswordRequestBase : public QObject 186 { 187 Q_OBJECT 188 public: KopetePasswordRequestBase(QObject * parent)189 KopetePasswordRequestBase(QObject *parent) 190 : QObject(parent) 191 { 192 } 193 194 Q_SIGNALS: 195 void requestFinished(const QString &password); 196 public Q_SLOTS: 197 virtual void walletReceived(KWallet::Wallet *wallet) = 0; 198 virtual void gotPassword(const QString &, bool) = 0; 199 virtual void slotCancelPressed() = 0; 200 }; 201 202 #endif 203 204 // vim: set noet ts=4 sts=4 sw=4: 205