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 <QtCore/QObject> |
21 | #include <QtGui/QPixmap> |
22 | |
23 | #include "kopete_export.h" |
24 | |
25 | namespace KWallet { class Wallet; } |
26 | |
27 | class QPixmap; |
28 | |
29 | /** @internal */ |
30 | class KopetePasswordGetRequest; |
31 | /** @internal */ |
32 | class KopetePasswordSetRequest; |
33 | /** @internal */ |
34 | class KopetePasswordClearRequest; |
35 | |
36 | namespace Kopete |
37 | { |
38 | |
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 KOPETE_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 | * @param name The name for this object |
59 | */ |
60 | explicit Password( const QString &configGroup, bool allowBlankPassword = false ); |
61 | |
62 | /** |
63 | * Create a shallow copy of this object |
64 | */ |
65 | Password( const Password &other ); |
66 | ~Password(); |
67 | |
68 | /** |
69 | * Assignment operator for passwords: make this object represent a different password |
70 | */ |
71 | Password &operator=( Password &other ); |
72 | |
73 | /** |
74 | * Returns the preferred size for images passed to the retrieve and request functions. |
75 | */ |
76 | static int preferredImageSize(); |
77 | |
78 | /** |
79 | * @brief Returns whether the password currently stored by this object is known to be incorrect. |
80 | * This flag gets reset whenever the user enters a new password, and is |
81 | * expected to be set by the user of this class if it is detected that the |
82 | * password the user entered is wrong. |
83 | */ |
84 | bool isWrong(); |
85 | /** |
86 | * Flag the password as being incorrect. |
87 | * @see isWrong |
88 | */ |
89 | void setWrong( bool bWrong = true ); |
90 | |
91 | /** |
92 | * Type of password request to perform: |
93 | * FromConfigOrUser : get the password from the config file, or from the user |
94 | * if no password in config. |
95 | * FromUser : always ask the user for a password (ie, if last password was |
96 | * wrong or you know the password has changed). |
97 | */ |
98 | enum PasswordSource { FromConfigOrUser, FromUser }; |
99 | |
100 | /** |
101 | * @brief Start an asynchronous call to get the password. |
102 | * Causes a password entry dialog to appear if the password is not set. Triggers |
103 | * a provided slot when done, but not until after this function has returned (you |
104 | * don't need to worry about reentrancy or nested event loops). |
105 | * |
106 | * @param receiver The object to notify when the password request finishes |
107 | * @param slot The slot on receiver to call at the end of the request. The signature |
108 | * of this function should be slot( const QString &password ). password will |
109 | * be the password if successful, or QString() if failed. |
110 | * @param image The icon to display in the dialog when asking for the password |
111 | * @param prompt The message to display to the user, asking for a |
112 | * password. Can be any Qt RichText string. |
113 | * @param source The source the password is taken from if a wrong or |
114 | * invalid password is entered or the password could not be found in the wallet |
115 | */ |
116 | void request( QObject *receiver, const char *slot, const QPixmap &image, |
117 | 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 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 | /** |
182 | * This class is an implementation detail of KopetePassword. |
183 | * @internal |
184 | * @see KopetePassword |
185 | */ |
186 | class KopetePasswordRequestBase : public QObject |
187 | { |
188 | Q_OBJECT |
189 | public: |
190 | KopetePasswordRequestBase(QObject *parent) |
191 | :QObject(parent) {}; |
192 | signals: |
193 | void requestFinished( const QString &password ); |
194 | public slots: |
195 | virtual void walletReceived( KWallet::Wallet *wallet ) = 0; |
196 | virtual void gotPassword(const QString&, bool) =0; |
197 | virtual void slotCancelPressed() =0; |
198 | |
199 | }; |
200 | |
201 | #endif |
202 | |
203 | // vim: set noet ts=4 sts=4 sw=4: |
204 | |