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