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