KIO

authinfo.h
1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000-2001 Dawit Alemayehu <adawit@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KIO_AUTHINFO_H
9#define KIO_AUTHINFO_H
10
11#include "kiocore_export.h"
12
13#include <QList>
14#include <QMap>
15#include <QStringList>
16#include <QUrl>
17#include <QVariant> // Q_DECLARE_METATYPE
18
19#include <memory>
20
21class QDBusArgument;
22
23namespace KIO
24{
25class AuthInfoPrivate;
26
27/**
28 * @class KIO::AuthInfo authinfo.h <KIO/AuthInfo>
29 *
30 * This class is intended to make it easier to prompt for, cache
31 * and retrieve authorization information.
32 *
33 * When using this class to cache, retrieve or prompt authentication
34 * information, you only need to set the necessary attributes. For
35 * example, to check whether a password is already cached, the only
36 * required information is the URL of the resource and optionally
37 * whether or not a path match should be performed. Similarly, to
38 * prompt for password you only need to optionally set the prompt,
39 * username (if already supplied), comment and commentLabel fields.
40 *
41 * <em>SPECIAL NOTE:</em> If you extend this class to add additional
42 * parameters do not forget to overload the stream insertion and
43 * extraction operators ("<<" and ">>") so that the added data can
44 * be correctly serialized.
45 *
46 * @short A two way messaging class for passing authentication information.
47 * @author Dawit Alemayehu <adawit@kde.org>
48 */
49class KIOCORE_EXPORT AuthInfo
50{
51 KIOCORE_EXPORT friend QDataStream &operator<<(QDataStream &s, const AuthInfo &a);
52 KIOCORE_EXPORT friend QDataStream &operator>>(QDataStream &s, AuthInfo &a);
53
54 KIOCORE_EXPORT friend QDBusArgument &operator<<(QDBusArgument &argument, const AuthInfo &a);
55 KIOCORE_EXPORT friend const QDBusArgument &operator>>(const QDBusArgument &argument, AuthInfo &a);
56
57public:
58 /**
59 * Default constructor.
60 */
61 AuthInfo();
62
63 /**
64 * Copy constructor.
65 */
66 AuthInfo(const AuthInfo &info);
67
68 /**
69 * Destructor
70 */
72
73 /**
74 * Custom assignment operator.
75 */
76 AuthInfo &operator=(const AuthInfo &info);
77
78 /**
79 * Use this method to check if the object was modified.
80 * @return true if the object has been modified
81 */
82 bool isModified() const;
83
84 /**
85 * Use this method to indicate that this object has been modified.
86 * @param flag true to mark the object as modified, false to clear
87 */
88 void setModified(bool flag);
89
90 /**
91 * The URL for which authentication is to be stored.
92 *
93 * This field is required when attempting to cache authorization
94 * and retrieve it. However, it is not needed when prompting
95 * the user for authorization info.
96 *
97 * This setting is @em required except when prompting the
98 * user for password.
99 */
101
102 /**
103 * This is @em required for caching.
104 */
106
107 /**
108 * This is @em required for caching.
109 */
111
112 /**
113 * Information to be displayed when prompting
114 * the user for authentication information.
115 *
116 * @note If this field is not set, the authentication
117 * dialog simply displays the preset default prompt.
118 *
119 * This setting is @em optional and empty by default.
120 */
122
123 /**
124 * The text to displayed in the title bar of
125 * the password prompting dialog.
126 *
127 * @note If this field is not set, the authentication
128 * dialog simply displays the preset default caption.
129 *
130 * This setting is @em optional and empty by default.
131 */
133
134 /**
135 * Additional comment to be displayed when prompting
136 * the user for authentication information.
137 *
138 * This field allows you to display a short (no more than
139 * 80 characters) extra description in the password prompt
140 * dialog. For example, this field along with the
141 * commentLabel can be used to describe the server that
142 * requested the authentication:
143 *
144 * \code
145 * Server: Squid Proxy @ foo.com
146 * \endcode
147 *
148 * where "Server:" is the commentLabel and the rest is the
149 * actual comment. Note that it is always better to use
150 * the @p commentLabel field as it will be placed properly
151 * in the dialog rather than to include it within the actual
152 * comment.
153 *
154 * This setting is @em optional and empty by default.
155 */
157
158 /**
159 * Descriptive label to be displayed in front of the
160 * comment when prompting the user for password.
161 *
162 * This setting is @em optional and only applicable when
163 * the comment field is also set.
164 */
166
167 /**
168 * A unique identifier that allows caching of multiple
169 * passwords for different resources in the same server.
170 *
171 * Mostly this setting is applicable to the HTTP protocol
172 * whose authentication scheme explicitly defines the use
173 * of such a unique key. However, any protocol that can
174 * generate or supply a unique id can effectively use it
175 * to distinguish passwords.
176 *
177 * This setting is @em optional and not set by default.
178 */
180
181 /**
182 * Field to store any extra authentication information for
183 * protocols that need it.
184 *
185 * This setting is @em optional and mostly applicable for HTTP
186 * protocol. However, any protocol can make use of it to
187 * store extra info.
188 */
190
191 /**
192 * Flag that, if set, indicates whether a path match should be
193 * performed when requesting for cached authorization.
194 *
195 * A path is deemed to be a match if it is equal to or is a subset
196 * of the cached path. For example, if stored path is "/foo/bar"
197 * and the request's path set to "/foo/bar/acme", then it is a match
198 * whereas it would not if the request's path was set to "/foo".
199 *
200 * This setting is @em optional and false by default.
201 */
203
204 /**
205 * Flag which if set forces the username field to be read-only.
206 *
207 * This setting is @em optional and false by default.
208 */
210
211 /**
212 * Flag to indicate the persistence of the given password.
213 *
214 * This is a two-way flag, when set before calling openPasswordDialog
215 * it makes the "keep Password" check box visible to the user.
216 * In return the flag will indicate the state of the check box.
217 * By default if the flag is checked the password will be cached
218 * for the entire life of the current KDE session otherwise the
219 * cached password is deleted right after the application using
220 * it has been closed.
221 */
223
224 /**
225 * Flags for extra fields
226 */
228 ExtraFieldNoFlags = 0,
229 ExtraFieldReadOnly = 1 << 1,
230 ExtraFieldMandatory = 1 << 2,
231 };
232
233 /**
234 * Set Extra Field Value.
235 * Currently supported extra-fields:
236 * "domain" (QString),
237 * "anonymous" (bool)
238 * Setting it to an invalid QVariant() will disable the field.
239 * Extra Fields are disabled by default.
240 */
241 void setExtraField(const QString &fieldName, const QVariant &value);
242
243 /**
244 * Set Extra Field Flags
245 */
246 void setExtraFieldFlags(const QString &fieldName, const FieldFlags flags);
247
248 /**
249 * Get Extra Field Value
250 * Check QVariant::isValid() to find out if the field exists.
251 */
252 QVariant getExtraField(const QString &fieldName) const;
253
254 /**
255 * Get Extra Field Flags
256 */
257 AuthInfo::FieldFlags getExtraFieldFlags(const QString &fieldName) const;
258
259 /**
260 * Register the meta-types for AuthInfo. This is called from
261 * AuthInfo's constructor but needed by daemons on the D-Bus such
262 * as kpasswdserver.
263 */
264 static void registerMetaTypes();
265
266protected:
267 bool modified;
268
269private:
270 friend class ::KIO::AuthInfoPrivate;
271 std::unique_ptr<AuthInfoPrivate> const d;
272};
273
274KIOCORE_EXPORT QDataStream &operator<<(QDataStream &s, const AuthInfo &a);
275KIOCORE_EXPORT QDataStream &operator>>(QDataStream &s, AuthInfo &a);
276
277KIOCORE_EXPORT QDBusArgument &operator<<(QDBusArgument &argument, const AuthInfo &a);
278KIOCORE_EXPORT const QDBusArgument &operator>>(const QDBusArgument &argument, AuthInfo &a);
279}
280
281Q_DECLARE_METATYPE(KIO::AuthInfo)
282
283#endif
This class is intended to make it easier to prompt for, cache and retrieve authorization information.
QString digestInfo
Field to store any extra authentication information for protocols that need it.
Definition authinfo.h:189
QString realmValue
A unique identifier that allows caching of multiple passwords for different resources in the same ser...
Definition authinfo.h:179
bool verifyPath
Flag that, if set, indicates whether a path match should be performed when requesting for cached auth...
Definition authinfo.h:202
~AuthInfo()
Destructor.
QUrl url
The URL for which authentication is to be stored.
Definition authinfo.h:100
FieldFlags
Flags for extra fields.
Definition authinfo.h:227
bool keepPassword
Flag to indicate the persistence of the given password.
Definition authinfo.h:222
QString comment
Additional comment to be displayed when prompting the user for authentication information.
Definition authinfo.h:156
bool readOnly
Flag which if set forces the username field to be read-only.
Definition authinfo.h:209
QString caption
The text to displayed in the title bar of the password prompting dialog.
Definition authinfo.h:132
QString username
This is required for caching.
Definition authinfo.h:105
QString password
This is required for caching.
Definition authinfo.h:110
QString prompt
Information to be displayed when prompting the user for authentication information.
Definition authinfo.h:121
QString commentLabel
Descriptive label to be displayed in front of the comment when prompting the user for password.
Definition authinfo.h:165
A namespace for KIO globals.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 16:58:45 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.