summaryrefslogtreecommitdiffstats
path: root/kopete/libkopete/kopetepassword.h
blob: de2f96c1a4579486dbd7d186abab3692d9054e9f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
/*
    kopetepassword.h - Kopete Password

    Copyright (c) 2004      by Richard Smith         <kde@metafoo.co.uk>
    Kopete    (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>

    *************************************************************************
    *                                                                       *
    * This library is free software; you can redistribute it and/or         *
    * modify it under the terms of the GNU Lesser General Public            *
    * License as published by the Free Software Foundation; either          *
    * version 2 of the License, or (at your option) any later version.      *
    *                                                                       *
    *************************************************************************
*/

#ifndef KOPETEPASSWORD_H
#define KOPETEPASSWORD_H

#include <tqobject.h>
#include "kopete_export.h"

namespace KWallet { class Wallet; }

class QPixmap;

/** @internal */
class KopetePasswordGetRequest;
/** @internal */
class KopetePasswordSetRequest;
/** @internal */
class KopetePasswordClearRequest;

namespace Kopete
{

/**
 * @author Richard Smith       <kde@metafoo.co.uk>
 *
 * The Kopete::Password object is responsible for storing and retrieving a
 * password for a plugin or account object.
 *
 * If the KWallet is active, passwords will be stored in it, otherwise, they
 * will be stored in the KConfig, in a slightly mangled form.
 */
class KOPETE_EXPORT Password : public QObject
{
	Q_OBJECT

public:
	/**
	 * Create a new Kopete::Password object.
	 *
	 * @param configGroup The configuration group to save passwords in.
	 * @param maxLength The maximum length of the password, or 0 if no maximum exists.
	 * @param name The name for this object
	 *
	 * @deprecated Use the constructor that specifies if a blank password is allowed
	 */
	explicit Password( const TQString &configGroup, uint maxLength = 0, const char *name = 0 );

	/**
	 * Create a new Kopete::Password object.
	 *
	 * @param configGroup The configuration group to save passwords in.
	 * @param maxLength The maximum length of the password, or 0 if no maximum exists.
	 * @param allowBlankPassword If this password is allowed to be blank
	 * @param name The name for this object
	 */
	explicit Password( const TQString &configGroup, uint maxLength = 0,
		bool allowBlankPassword = false, const char *name = 0 );

	/**
	 * Create a shallow copy of this object
	 */
	Password( Password &other, const char *name = 0 );
	~Password();

	/**
	 * Assignment operator for passwords: make this object represent a different password
	 */
	Password &operator=( Password &other );

	/**
	 * Returns the preferred size for images passed to the retrieve and request functions.
	 */
	static int preferredImageSize();

	/**
	 * @brief Returns the maximum allowed length of the password, or 0 if there is no maximum.
	 */
	uint maximumLength();
	/**
	 * Sets the maximum allowed length of the password.
	 * @param max The new maximum allowed length, or 0 if there is no maximum.
	 */
	void setMaximumLength( uint max );

	/**
	 * @brief Returns whether the password currently stored by this object is known to be incorrect.
	 * This flag gets reset whenever the user enters a new password, and is
	 * expected to be set by the user of this class if it is detected that the
	 * password the user entered is wrong.
	 */
	bool isWrong();
	/**
	 * Flag the password as being incorrect.
	 * @see isWrong
	 */
	void setWrong( bool bWrong = true );

	/**
	 * Type of password request to perform:
	 * FromConfigOrUser : get the password from the config file, or from the user
	 * if no password in config.
	 * FromUser : always ask the user for a password (ie, if last password was
	 * wrong or you know the password has changed).
	 */
	enum PasswordSource { FromConfigOrUser, FromUser };

	/**
	 * @brief Start an asynchronous call to get the password.
	 * Causes a password entry dialog to appear if the password is not set. Triggers
	 * a provided slot when done, but not until after this function has returned (you
	 * don't need to worry about reentrancy or nested event loops).
	 *
	 * @param receiver The object to notify when the password request finishes
	 * @param slot The slot on receiver to call at the end of the request. The signature
	 *        of this function should be slot( const TQString &password ). password will
	 *        be the password if successful, or TQString::null if failed.
	 * @param image The icon to display in the dialog when asking for the password
	 * @param prompt The message to display to the user, asking for a
	 *        password. Can be any Qt RichText string.
	 * @param source The source the password is taken from if a wrong or
	 *        invalid password is entered or the password could not be found in the wallet
	 */
	void request( TQObject *receiver, const char *slot, const TQPixmap &image,
		const TQString &prompt, PasswordSource source = FromConfigOrUser );

	/**
	 * @brief Start an asynchronous password request without a prompt
	 *
	 * Starts an asynchronous password request. Does not pop up a password entry dialog
	 * if there is no password.
	 * @see request(TQObject*,const char*,const TQPixmap&,const TQString&,bool,unsigned int)
	 * The password given to the provided slot will be NULL if no password could be retrieved for
	 * some reason, such as the user declining to open the wallet, or no password being found.
	 */
	void requestWithoutPrompt( TQObject *receiver, const char *slot );

	/**
	 * @return true if the password is remembered, false otherwise.
	 *
	 * If it returns false, calling @ref request() will
	 * pop up an Enter Password window.
	 */
	bool remembered();

	/**
	 * @return true if you are allowed to have a blank password
	 */
	bool allowBlankPassword();

	/**
	 * When a password request succeeds, the password is cached. This function
	 * returns the cached password, if there is one, or TQString::null if there
	 * is not.
	 */
	TQString cachedValue();

public slots:
	/**
	 * Set the password for this account.
	 * @param pass If set to TQString::null, the password is forgotten unless you
	 *	specified to allow blank passwords. Otherwise, sets the password to
	 *	this value.
	 *
	 * Note: this function is asynchronous; changes will not be instant.
	 */
	void set( const TQString &pass = TQString::null );

	/**
	 * Unconditionally clears the stored password
	 */
	void clear();

private:
	void readConfig();
	void writeConfig();

	class Private;
	Private *d;

	//TODO: can we rearrange things so these aren't friends?
	friend class ::KopetePasswordGetRequest;
	friend class ::KopetePasswordSetRequest;
	friend class ::KopetePasswordClearRequest;
};

}

/**
 * This class is an implementation detail of KopetePassword.
 * @internal
 * @see KopetePassword
 */
class KopetePasswordRequestBase : public virtual QObject
{
	Q_OBJECT
signals:
	void requestFinished( const TQString &password );
public slots:
	virtual void walletReceived( KWallet::Wallet *wallet ) = 0;
	virtual void slotOkPressed() = 0;
	virtual void slotCancelPressed() = 0;
};

#endif

// vim: set noet ts=4 sts=4 sw=4: