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
25namespace KWallet { class Wallet; }
26
27class QPixmap;
28
29/** @internal */
30class KopetePasswordGetRequest;
31/** @internal */
32class KopetePasswordSetRequest;
33/** @internal */
34class KopetePasswordClearRequest;
35
36namespace 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 */
48class KOPETE_EXPORT Password : public QObject
49{
50 Q_OBJECT
51
52public:
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
150public 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
166private:
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 */
186class KopetePasswordRequestBase : public QObject
187{
188 Q_OBJECT
189public:
190 KopetePasswordRequestBase(QObject *parent)
191 :QObject(parent) {};
192signals:
193 void requestFinished( const QString &password );
194public 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