1 | /* |
2 | * This file is part of the KDE libraries |
3 | * Copyright (C) 2000-2001 Dawit Alemayehu <adawit@kde.org> |
4 | * |
5 | * This library is free software; you can redistribute it and/or |
6 | * modify it under the terms of the GNU Library General Public |
7 | * License as published by the Free Software Foundation; either |
8 | * version 2 of the License, or (at your option) any later version. |
9 | * |
10 | * This library is distributed in the hope that it will be useful, |
11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
13 | * Library General Public License for more details. |
14 | * |
15 | * You should have received a copy of the GNU Library General Public License |
16 | * along with this library; see the file COPYING.LIB. If not, write to |
17 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
18 | * Boston, MA 02110-1301, USA. |
19 | */ |
20 | |
21 | #ifndef KIO_AUTHINFO_H |
22 | #define KIO_AUTHINFO_H |
23 | |
24 | #include "kio_export.h" |
25 | |
26 | #include <QtCore/QMap> |
27 | #include <QtCore/QList> |
28 | #include <QtCore/QStringList> |
29 | #include <kurl.h> |
30 | |
31 | class QDBusArgument; |
32 | |
33 | namespace KIO { |
34 | |
35 | class AuthInfoPrivate; |
36 | |
37 | /** |
38 | * This class is intended to make it easier to prompt for, cache |
39 | * and retrieve authorization information. |
40 | * |
41 | * When using this class to cache, retrieve or prompt authentication |
42 | * information, you only need to set the necessary attributes. For |
43 | * example, to check whether a password is already cached, the only |
44 | * required information is the URL of the resource and optionally |
45 | * whether or not a path match should be performed. Similarly, to |
46 | * prompt for password you only need to optionally set the prompt, |
47 | * username (if already supplied), comment and commentLabel fields. |
48 | * |
49 | * <em>SPECIAL NOTE:</em> If you extend this class to add additional |
50 | * parameters do not forget to overload the stream insertion and |
51 | * extraction operators ("<<" and ">>") so that the added data can |
52 | * be correctly serialzed. |
53 | * |
54 | * @short A two way messaging class for passing authentication information. |
55 | * @author Dawit Alemayehu <adawit@kde.org> |
56 | */ |
57 | class KIO_EXPORT AuthInfo |
58 | { |
59 | KIO_EXPORT friend QDataStream& operator<< (QDataStream& s, const AuthInfo& a); |
60 | KIO_EXPORT friend QDataStream& operator>> (QDataStream& s, AuthInfo& a); |
61 | |
62 | KIO_EXPORT friend QDBusArgument &operator<<(QDBusArgument &argument, const AuthInfo &a); |
63 | KIO_EXPORT friend const QDBusArgument &operator>>(const QDBusArgument &argument, AuthInfo &a); |
64 | |
65 | public: |
66 | |
67 | /** |
68 | * Default constructor. |
69 | */ |
70 | AuthInfo(); |
71 | |
72 | /** |
73 | * Copy constructor. |
74 | */ |
75 | AuthInfo( const AuthInfo& info ); |
76 | |
77 | /** |
78 | * Destructor |
79 | * @since 4.1 |
80 | */ |
81 | ~AuthInfo(); |
82 | |
83 | /** |
84 | * Custom assignment operator. |
85 | */ |
86 | AuthInfo& operator=( const AuthInfo& info ); |
87 | |
88 | /** |
89 | * Use this method to check if the object was modified. |
90 | * @return 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 | * @param flag true to mark the object as modified, false to clear |
97 | */ |
98 | void setModified( bool flag ); |
99 | |
100 | /** |
101 | * The URL for which authentication is to be stored. |
102 | * |
103 | * This field is required when attempting to cache authorization |
104 | * and retrieve it. However, it is not needed when prompting |
105 | * the user for authorization info. |
106 | * |
107 | * This setting is @em required except when prompting the |
108 | * user for password. |
109 | */ |
110 | KUrl url; |
111 | |
112 | /** |
113 | * This is @em required for caching. |
114 | */ |
115 | QString username; |
116 | |
117 | /** |
118 | * This is @em required for caching. |
119 | */ |
120 | QString password; |
121 | |
122 | /** |
123 | * Information to be displayed when prompting |
124 | * the user for authentication information. |
125 | * |
126 | * @note If this field is not set, the authentication |
127 | * dialog simply displays the preset default prompt. |
128 | * |
129 | * This setting is @em optional and empty by default. |
130 | */ |
131 | QString prompt; |
132 | |
133 | /** |
134 | * The text to displayed in the title bar of |
135 | * the password prompting dialog. |
136 | * |
137 | * @note If this field is not set, the authentication |
138 | * dialog simply displays the preset default caption. |
139 | * |
140 | * This setting is @em optional and empty by default. |
141 | */ |
142 | QString caption; |
143 | |
144 | /** |
145 | * Additional comment to be displayed when prompting |
146 | * the user for authentication information. |
147 | * |
148 | * This field allows you to display a short (no more than |
149 | * 80 characters) extra description in the password prompt |
150 | * dialog. For example, this field along with the |
151 | * commentLabel can be used to describe the server that |
152 | * requested the authentication: |
153 | * |
154 | * \code |
155 | * Server: Squid Proxy @ foo.com |
156 | * \endcode |
157 | * |
158 | * where "Server:" is the commentLabel and the rest is the |
159 | * actual comment. Note that it is always better to use |
160 | * the @p commentLabel field as it will be placed properly |
161 | * in the dialog rather than to include it within the actual |
162 | * comment. |
163 | * |
164 | * This setting is @em optional and empty by default. |
165 | */ |
166 | QString ; |
167 | |
168 | /** |
169 | * Descriptive label to be displayed in front of the |
170 | * comment when prompting the user for password. |
171 | * |
172 | * This setting is @em optional and only applicable when |
173 | * the comment field is also set. |
174 | */ |
175 | QString ; |
176 | |
177 | /** |
178 | * A unique identifier that allows caching of multiple |
179 | * passwords for different resources in the same server. |
180 | * |
181 | * Mostly this setting is applicable to the HTTP protocol |
182 | * whose authentication scheme explicitly defines the use |
183 | * of such a unique key. However, any protocol that can |
184 | * generate or supply a unique id can effectively use it |
185 | * to distinguish passwords. |
186 | * |
187 | * This setting is @em optional and not set by default. |
188 | */ |
189 | QString realmValue; |
190 | |
191 | /** |
192 | * Field to store any extra authentication information for |
193 | * protocols that need it. |
194 | * |
195 | * This setting is @em optional and mostly applicable for HTTP |
196 | * protocol. However, any protocol can make use of it to |
197 | * store extra info. |
198 | */ |
199 | QString digestInfo; |
200 | |
201 | /** |
202 | * Flag that, if set, indicates whether a path match should be |
203 | * performed when requesting for cached authorization. |
204 | * |
205 | * A path is deemed to be a match if it is equal to or is a subset |
206 | * of the cached path. For example, if stored path is "/foo/bar" |
207 | * and the request's path set to "/foo/bar/acme", then it is a match |
208 | * whereas it would not if the request's path was set to "/foo". |
209 | * |
210 | * This setting is @em optional and false by default. |
211 | */ |
212 | bool verifyPath; |
213 | |
214 | /** |
215 | * Flag which if set forces the username field to be read-only. |
216 | * |
217 | * This setting is @em optional and false by default. |
218 | */ |
219 | bool readOnly; |
220 | |
221 | /** |
222 | * Flag to indicate the persistence of the given password. |
223 | * |
224 | * This is a two-way flag, when set before calling openPasswordDialog |
225 | * it makes the "keep Password" check box visible to the user. |
226 | * In return the flag will indicate the state of the check box. |
227 | * By default if the flag is checked the password will be cached |
228 | * for the entire life of the current KDE session otherwise the |
229 | * cached password is deleted right after the application using |
230 | * it has been closed. |
231 | */ |
232 | bool keepPassword; |
233 | |
234 | /** |
235 | * Flags for extra fields |
236 | * @since 4.1 |
237 | */ |
238 | enum FieldFlags |
239 | { |
240 | = 0, |
241 | = 1<<1, |
242 | ExtraFieldMandatory = 1<<2 |
243 | }; |
244 | |
245 | /** |
246 | * Set Extra Field Value. |
247 | * Currently supported extra-fields: |
248 | * "domain" (QString), |
249 | * "anonymous" (bool) |
250 | * Setting it to an invalid QVariant() will disable the field. |
251 | * Extra Fields are disabled by default. |
252 | * @since 4.1 |
253 | */ |
254 | void (const QString &fieldName, const QVariant & value); |
255 | |
256 | /** |
257 | * Set Extra Field Flags |
258 | * @since 4.1 |
259 | */ |
260 | void (const QString &fieldName, const FieldFlags flags); |
261 | |
262 | /** |
263 | * Get Extra Field Value |
264 | * Check QVariant::isValid() to find out if the field exists. |
265 | * @since 4.1 |
266 | */ |
267 | QVariant (const QString &fieldName) const; |
268 | |
269 | /** |
270 | * Get Extra Field Flags |
271 | * @since 4.1 |
272 | */ |
273 | AuthInfo::FieldFlags (const QString &fieldName) const; |
274 | |
275 | /** |
276 | * Register the meta-types for AuthInfo. This is called from |
277 | * AuthInfo's constructor but needed by daemons on the DBus such |
278 | * as kpasswdserver. |
279 | * @since 4.3 |
280 | */ |
281 | static void registerMetaTypes(); |
282 | |
283 | protected: |
284 | bool modified; |
285 | |
286 | private: |
287 | friend class ::KIO::AuthInfoPrivate; |
288 | AuthInfoPrivate * const d; |
289 | }; |
290 | |
291 | KIO_EXPORT QDataStream& operator<< (QDataStream& s, const AuthInfo& a); |
292 | KIO_EXPORT QDataStream& operator>> (QDataStream& s, AuthInfo& a); |
293 | |
294 | KIO_EXPORT QDBusArgument &operator<<(QDBusArgument &argument, const AuthInfo &a); |
295 | KIO_EXPORT const QDBusArgument &operator>>(const QDBusArgument &argument, AuthInfo &a); |
296 | |
297 | /** |
298 | * A Singleton class that provides access to passwords |
299 | * stored in .netrc files for automatic login purposes. |
300 | * This is only meant to address backward compatibility |
301 | * with old automated ftp client style logins... |
302 | * |
303 | * @short An interface to the ftp .netrc files |
304 | * @author Dawit Alemayehu <adawit@kde.org> |
305 | */ |
306 | class KIO_EXPORT NetRC |
307 | { |
308 | public: |
309 | |
310 | /** |
311 | * Specifies the mode to be used when searching for a |
312 | * matching automatic login info for a given site : |
313 | * |
314 | * @li exactOnly search entries with exact host name matches. |
315 | * @li defaultOnly search entries that are specified as "default". |
316 | * @li presetOnly search entries that are specified as "preset". |
317 | * |
318 | * @see lookup |
319 | */ |
320 | enum LookUpModeFlag |
321 | { |
322 | exactOnly = 0x0002, |
323 | defaultOnly = 0x0004, |
324 | presetOnly = 0x0008 |
325 | }; |
326 | Q_DECLARE_FLAGS(LookUpMode, LookUpModeFlag) |
327 | |
328 | /** |
329 | * Contains auto login information. |
330 | * @see lookup() |
331 | */ |
332 | struct AutoLogin |
333 | { |
334 | QString type; |
335 | QString machine; |
336 | QString login; |
337 | QString password; |
338 | QMap<QString, QStringList> macdef; |
339 | }; |
340 | |
341 | /** |
342 | * A reference to the instance of the class. |
343 | * @return the class |
344 | */ |
345 | static NetRC* self(); |
346 | |
347 | /** |
348 | * Looks up the @p login information for the given @p url. |
349 | * |
350 | * @param url the url whose login information will be checked |
351 | * @param login the login information will be writte here |
352 | * @param userealnetrc if true, use $HOME/.netrc fle |
353 | * @param type the type of the login. If null, the @p url's protocol |
354 | * will be taken |
355 | * @param mode the LookUpMode flags (ORed) for the query |
356 | */ |
357 | bool lookup( const KUrl& url, AutoLogin& login, |
358 | bool userealnetrc = false, |
359 | const QString &type = QString(), |
360 | LookUpMode mode = LookUpMode(exactOnly) | defaultOnly ); |
361 | /** |
362 | * Reloads the auto login information. |
363 | */ |
364 | void reload(); |
365 | |
366 | protected: |
367 | QString ( const char*, const char*, int& ); |
368 | int openf( const QString& ); |
369 | bool parse( int ); |
370 | |
371 | private: |
372 | NetRC(); |
373 | ~NetRC(); |
374 | |
375 | private: |
376 | static NetRC* instance; |
377 | |
378 | class NetRCPrivate; |
379 | NetRCPrivate* const d; |
380 | }; |
381 | } |
382 | Q_DECLARE_OPERATORS_FOR_FLAGS(KIO::NetRC::LookUpMode) |
383 | Q_DECLARE_METATYPE(KIO::AuthInfo) |
384 | |
385 | #endif |
386 | |