1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Torben Weis <weis@kde.org>
3 Copyright (C) 2000- Waldo Bastain <bastain@kde.org>
4 Copyright (C) 2000- Dawit Alemayehu <adawit@kde.org>
5 Copyright (C) 2008 Jarosław Staniek <staniek@kde.org>
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License version 2 as published by the Free Software Foundation.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21#ifndef KPROTOCOLMANAGER_H
22#define KPROTOCOLMANAGER_H
23
24#include <QtCore/QStringList>
25
26#include <kio/global.h>
27#include "kprotocolinfo.h"
28
29class KSharedConfig;
30template<class T>
31class KSharedPtr;
32typedef KSharedPtr<KSharedConfig> KSharedConfigPtr;
33namespace KIO
34{
35 class SlaveConfigPrivate;
36} // namespace KIO
37
38/**
39 * Provides information about I/O (Internet, etc.) settings chosen/set
40 * by the end user.
41 *
42 * KProtocolManager has a heap of static functions that allows only read
43 * access to KDE's IO related settings. These include proxy, cache, file
44 * transfer resumption, timeout and user-agent related settings.
45 *
46 * The information provided by this class is generic enough to be applicable
47 * to any application that makes use of KDE's IO sub-system. Note that this
48 * mean the proxy, timeout etc. settings are saved in a separate user-specific
49 * config file and not in the config file of the application.
50 *
51 * Original author:
52 * @author Torben Weis <weis@kde.org>
53 *
54 * Revised by:
55 * @author Waldo Bastain <bastain@kde.org>
56 * @author Dawit Alemayehu <adawit@kde.org>
57 * @see KPAC
58 */
59class KIO_EXPORT KProtocolManager
60{
61public:
62
63
64/*=========================== USER-AGENT SETTINGS ===========================*/
65
66
67 /**
68 * Returns the default user-agent string used for web browsing.
69 *
70 * @return the default user-agent string
71 */
72 static QString defaultUserAgent();
73
74 /**
75 * Returns the default user-agent value used for web browsing, for example
76 * "Mozilla/5.0 (compatible; Konqueror/4.0; Linux; X11; i686; en_US) KHTML/4.0.1 (like Gecko)"
77 *
78 * @param keys can be any of the following:
79 * @li 'o' Show OS
80 * @li 'v' Show OS Version
81 * @li 'p' Show platform (only for X11)
82 * @li 'm' Show machine architecture
83 * @li 'l' Show language
84 * @return the default user-agent value with the given @p keys
85 */
86 static QString defaultUserAgent(const QString &keys);
87
88 /**
89 * Returns the application's user-agent string.
90 * Example string is "KMail/1.9.50 (Windows/6.0; KDE/3.97.1; i686; svn-762186; 2008-01-15)",
91 * where "KMail" is the @p appName parameter, "1.9.50" is the @p appVersion parameter,
92 * "Windows/6.0; KDE/3.97.1; i686" part is added automatically and "svn-762186; 2008-01-15"
93 * is provided by @p extraInfo list.
94 *
95 * @param appName name of the application
96 * @param appVersion name of the application
97 * @param extraInfo a list of elements that will be appended to the string as extra information
98 * @return the application's user-agent string
99 *
100 * @since 4.1
101 */
102 static QString userAgentForApplication( const QString &appName, const QString& appVersion,
103 const QStringList& extraInfo = QStringList() );
104
105 /**
106 * Returns the user-agent string configured for the
107 * specified host.
108 *
109 * If hostname is not found or is empty (i.e. "" or
110 * QString()) this function will return the default
111 * user agent.
112 *
113 * @param hostname name of the host
114 * @return specified user-agent string
115 */
116 static QString userAgentForHost( const QString &hostname );
117
118 /*
119 * Returns system name, version and machine type, for example "Windows", "5.1", "i686".
120 * This information can be used for constructing custom user-agent strings.
121 *
122 * @param systemName system name
123 * @param systemVersion system version
124 * @param machine machine type
125
126 * @return true if system name, version and machine type has been provided
127 *
128 * @since 4.1
129 */
130 static bool getSystemNameVersionAndMachine(
131 QString& systemName, QString& systemVersion, QString& machine );
132
133
134/*=========================== TIMEOUT CONFIG ================================*/
135
136
137 /**
138 * Returns the preferred timeout value for reading from
139 * remote connections in seconds.
140 *
141 * @return timeout value for remote connection in secs.
142 */
143 static int readTimeout();
144
145 /**
146 * Returns the preferred timeout value for remote connections
147 * in seconds.
148 *
149 * @return timeout value for remote connection in secs.
150 */
151 static int connectTimeout();
152
153 /**
154 * Returns the preferred timeout value for proxy connections
155 * in seconds.
156 *
157 * @return timeout value for proxy connection in secs.
158 */
159 static int proxyConnectTimeout();
160
161 /**
162 * Returns the preferred response timeout value for
163 * remote connecting in seconds.
164 *
165 * @return timeout value for remote connection in seconds.
166 */
167 static int responseTimeout();
168
169
170/*=============================== PROXY CONFIG ==============================*/
171
172
173 /**
174 * Returns whether or not the user specified the
175 * use of proxy server to make connections.
176 * @return true to use a proxy
177 */
178 static bool useProxy();
179
180 /**
181 * Returns whether or not the proxy server
182 * lookup should be reversed or not.
183 * @return true to use a reversed proxy
184 */
185 static bool useReverseProxy();
186
187 /**
188 * Types of proxy configuration
189 * @li NoProxy - No proxy is used
190 * @li ManualProxy - Proxies are manually configured
191 * @li PACProxy - A Proxy configuration URL has been given
192 * @li WPADProxy - A proxy should be automatically discovered
193 * @li EnvVarProxy - Use the proxy values set through environment variables.
194 */
195 enum ProxyType
196 {
197 NoProxy,
198 ManualProxy,
199 PACProxy,
200 WPADProxy,
201 EnvVarProxy
202 };
203
204 /**
205 * Returns the type of proxy configuration that is used.
206 * @return the proxy type
207 */
208 static ProxyType proxyType();
209
210 /**
211 * Proxy authorization modes.
212 *
213 * @li Prompt - Ask for authorization as needed
214 * @li Automatic - Use auto login as defined in kionetrc files.
215 */
216 enum ProxyAuthMode
217 {
218 Prompt,
219 Automatic
220 };
221
222 /**
223 * Returns the way proxy authorization should be handled.
224 *
225 * @return the proxy authorization mode
226 * @see ProxyAuthMode
227 */
228 static ProxyAuthMode proxyAuthMode();
229
230 /**
231 * Returns the strings for hosts that should contacted
232 * DIRECTLY, bypassing any proxy settings.
233 * @return a list of (comma-separated) hostnames or partial host
234 * names
235 */
236 static QString noProxyFor();
237
238 /**
239 * Returns the proxy server address for a given
240 * protocol.
241 *
242 * @param protocol the protocol whose proxy info is needed
243 * @returns the proxy server address if one is available,
244 * or QString() if not available
245 */
246 static QString proxyFor( const QString& protocol );
247
248 /**
249 * Returns the Proxy server address for a given URL.
250 *
251 * If the selected proxy type is @ref PACProxy or @ref WPADProxy, then a
252 * helper kded module, proxyscout, is used to determine the proxy information.
253 * Otherwise, @ref proxyFor is used to find the proxy to use for the given url.
254 *
255 * If this function returns an empty string, then the request to a proxy server
256 * must be denied. For a direct connection, without the use of a proxy, this
257 * function will return "DIRECT".
258 *
259 * @param url the URL whose proxy info is needed
260 * @returns the proxy server address if one is available, otherwise a QString().
261 */
262 static QString proxyForUrl( const KUrl& url );
263
264 /**
265 * Returns all the possible proxy server addresses for @p url.
266 *
267 * If the selected proxy type is @ref PACProxy or @ref WPADProxy, then a
268 * helper kded module, proxyscout, is used to determine the proxy information.
269 * Otherwise, @ref proxyFor is used to find the proxy to use for the given url.
270 *
271 * If this function returns empty list, then the request is to a proxy server
272 * must be denied. For a direct connection, this function will return a single
273 * entry of "DIRECT".
274 *
275 * @since 4.7
276 *
277 * @param url the URL whose proxy info is needed
278 * @returns the proxy server address if one is available, otherwise an empty list .
279 */
280 static QStringList proxiesForUrl( const KUrl& url );
281
282 /**
283 * Marks this proxy as bad (down). It will not be used for the
284 * next 30 minutes. (The script may supply an alternate proxy)
285 * @param proxy the proxy to mark as bad (as URL)
286 */
287 static void badProxy( const QString & proxy );
288
289 /**
290 * Returns the URL of the script for automatic proxy configuration.
291 * @return the proxy configuration script
292 */
293 static QString proxyConfigScript();
294
295
296/*========================== CACHE CONFIG ===================================*/
297
298
299 /**
300 * Returns true/false to indicate whether a cache
301 * should be used
302 *
303 * @return true to use the cache, false otherwisea
304 */
305 static bool useCache();
306
307 /**
308 * Returns the maximum age in seconds cached files should be
309 * kept before they are deleted as necessary.
310 *
311 * @return the maximum cache age in seconds
312 */
313 static int maxCacheAge();
314
315 /**
316 * Returns the maximum size that can be used for caching.
317 *
318 * By default this function returns the DEFAULT_MAX_CACHE_SIZE
319 * value as defined in http_slave_defaults.h. Not that the
320 * value returned is in bytes, hence a value of 5120 would mean
321 * 5 Kb.
322 *
323 * @return the maximum cache size in bytes
324 */
325 static int maxCacheSize(); // Maximum cache size in Kb.
326
327 /**
328 * The directory which contains the cache files.
329 * @return the directory that contains the cache files
330 */
331 static QString cacheDir();
332
333 /**
334 * Returns the Cache control directive to be used.
335 * @return the cache control value
336 */
337 static KIO::CacheControl cacheControl();
338
339
340/*============================ DOWNLOAD CONFIG ==============================*/
341
342 /**
343 * Returns true if partial downloads should be
344 * automatically resumed.
345 * @return true to resume partial downloads
346 */
347 static bool autoResume();
348
349 /**
350 * Returns true if partial downloads should be marked
351 * with a ".part" extension.
352 * @return true if partial downloads should get an ".part" extension
353 */
354 static bool markPartial();
355
356 /**
357 * Returns the minimum file size for keeping aborted
358 * downloads.
359 *
360 * Any data downloaded that does not meet this minimum
361 * requirement will simply be discarded. The default size
362 * is 5 KB.
363 *
364 * @return the minimum keep size for aborted downloads in bytes
365 */
366 static int minimumKeepSize();
367
368
369 /*============================ NETWORK CONNECTIONS ==========================*/
370 /**
371 * Returns true if proxy connections should be persistent.
372 * @return true if proxy connections should be persistent
373 */
374 static bool persistentProxyConnection();
375
376 /**
377 * Returns true if connections should be persistent
378 * @return true if the connections should be persistent
379 */
380 static bool persistentConnections();
381
382
383 /*===================== PROTOCOL CAPABILITIES ===============================*/
384
385 /**
386 * Returns whether the protocol can list files/objects.
387 * If a protocol supports listing it can be browsed in e.g. file-dialogs
388 * and konqueror.
389 *
390 * Whether a protocol supports listing is determined by the "listing="
391 * field in the protocol description file.
392 * If the protocol support listing it should list the fields it provides in
393 * this field. If the protocol does not support listing this field should
394 * remain empty (default.)
395 *
396 * @param url the url to check
397 * @return true if the protocol support listing
398 * @see listing()
399 */
400 static bool supportsListing( const KUrl &url );
401
402 /**
403 * Returns whether the protocol can retrieve data from URLs.
404 *
405 * This corresponds to the "reading=" field in the protocol description file.
406 * Valid values for this field are "true" or "false" (default).
407 *
408 * @param url the url to check
409 * @return true if it is possible to read from the URL
410 */
411 static bool supportsReading( const KUrl &url );
412
413 /**
414 * Returns whether the protocol can store data to URLs.
415 *
416 * This corresponds to the "writing=" field in the protocol description file.
417 * Valid values for this field are "true" or "false" (default).
418 *
419 * @param url the url to check
420 * @return true if the protocol supports writing
421 */
422 static bool supportsWriting( const KUrl &url );
423
424 /**
425 * Returns whether the protocol can create directories/folders.
426 *
427 * This corresponds to the "makedir=" field in the protocol description file.
428 * Valid values for this field are "true" or "false" (default).
429 *
430 * @param url the url to check
431 * @return true if the protocol can create directories
432 */
433 static bool supportsMakeDir( const KUrl &url );
434
435 /**
436 * Returns whether the protocol can delete files/objects.
437 *
438 * This corresponds to the "deleting=" field in the protocol description file.
439 * Valid values for this field are "true" or "false" (default).
440 *
441 * @param url the url to check
442 * @return true if the protocol supports deleting
443 */
444 static bool supportsDeleting( const KUrl &url );
445
446 /**
447 * Returns whether the protocol can create links between files/objects.
448 *
449 * This corresponds to the "linking=" field in the protocol description file.
450 * Valid values for this field are "true" or "false" (default).
451 *
452 * @param url the url to check
453 * @return true if the protocol supports linking
454 */
455 static bool supportsLinking( const KUrl &url );
456
457 /**
458 * Returns whether the protocol can move files/objects between different
459 * locations.
460 *
461 * This corresponds to the "moving=" field in the protocol description file.
462 * Valid values for this field are "true" or "false" (default).
463 *
464 * @param url the url to check
465 * @return true if the protocol supports moving
466 */
467 static bool supportsMoving( const KUrl &url );
468
469 /**
470 * Returns whether the protocol can be opened using KIO::open(const KUrl&).
471 *
472 * This corresponds to the "opening=" field in the protocol description file.
473 * Valid values for this field are "true" or "false" (default).
474 *
475 * @param url the url to check
476 * @return true if the protocol supports opening
477 */
478 static bool supportsOpening( const KUrl &url );
479
480 /**
481 * Returns whether the protocol can copy files/objects directly from the
482 * filesystem itself. If not, the application will read files from the
483 * filesystem using the file-protocol and pass the data on to the destination
484 * protocol.
485 *
486 * This corresponds to the "copyFromFile=" field in the protocol description file.
487 * Valid values for this field are "true" or "false" (default).
488 *
489 * @param url the url to check
490 * @return true if the protocol can copy files from the local file system
491 */
492 static bool canCopyFromFile( const KUrl &url );
493
494 /**
495 * Returns whether the protocol can copy files/objects directly to the
496 * filesystem itself. If not, the application will receive the data from
497 * the source protocol and store it in the filesystem using the
498 * file-protocol.
499 *
500 * This corresponds to the "copyToFile=" field in the protocol description file.
501 * Valid values for this field are "true" or "false" (default).
502 *
503 * @param url the url to check
504 * @return true if the protocol can copy files to the local file system
505 */
506 static bool canCopyToFile( const KUrl &url );
507
508 /**
509 * Returns whether the protocol can rename (i.e. move fast) files/objects
510 * directly from the filesystem itself. If not, the application will read
511 * files from the filesystem using the file-protocol and pass the data on
512 * to the destination protocol.
513 *
514 * This corresponds to the "renameFromFile=" field in the protocol description file.
515 * Valid values for this field are "true" or "false" (default).
516 *
517 * @param url the url to check
518 * @return true if the protocol can rename/move files from the local file system
519 */
520 static bool canRenameFromFile( const KUrl &url );
521
522 /**
523 * Returns whether the protocol can rename (i.e. move fast) files/objects
524 * directly to the filesystem itself. If not, the application will receive
525 * the data from the source protocol and store it in the filesystem using the
526 * file-protocol.
527 *
528 * This corresponds to the "renameToFile=" field in the protocol description file.
529 * Valid values for this field are "true" or "false" (default).
530 *
531 * @param url the url to check
532 * @return true if the protocol can rename files to the local file system
533 */
534 static bool canRenameToFile( const KUrl &url );
535
536 /**
537 * Returns whether the protocol can recursively delete directories by itself.
538 * If not (the usual case) then KIO will list the directory and delete files
539 * and empty directories one by one.
540 *
541 * This corresponds to the "deleteRecursive=" field in the protocol description file.
542 * Valid values for this field are "true" or "false" (default).
543 *
544 * @param url the url to check
545 * @return true if the protocol can delete non-empty directories by itself.
546 */
547 static bool canDeleteRecursive( const KUrl &url );
548
549 /**
550 * This setting defines the strategy to use for generating a filename, when
551 * copying a file or directory to another directory. By default the destination
552 * filename is made out of the filename in the source URL. However if the
553 * ioslave displays names that are different from the filename of the URL
554 * (e.g. kio_fonts shows Arial for arial.ttf, or kio_trash shows foo.txt and
555 * uses some internal URL), using Name means that the display name (UDS_NAME)
556 * will be used to as the filename in the destination directory.
557 *
558 * This corresponds to the "fileNameUsedForCopying=" field in the protocol description file.
559 * Valid values for this field are "Name" or "FromURL" (default).
560 *
561 * @param url the url to check
562 * @return how to generate the filename in the destination directory when copying/moving
563 */
564 static KProtocolInfo::FileNameUsedForCopying fileNameUsedForCopying( const KUrl &url );
565
566 /**
567 * Returns default mimetype for this URL based on the protocol.
568 *
569 * This corresponds to the "defaultMimetype=" field in the protocol description file.
570 *
571 * @param url the url to check
572 * @return the default mime type of the protocol, or null if unknown
573 */
574 static QString defaultMimetype( const KUrl& url );
575
576 /**
577 * Returns whether the protocol should be treated as a filesystem
578 * or as a stream when reading from it.
579 *
580 * This corresponds to the "input=" field in the protocol description file.
581 * Valid values for this field are "filesystem", "stream" or "none" (default).
582 *
583 * @param url the url to check
584 * @return the input type of the given @p url
585 */
586 static KProtocolInfo::Type inputType( const KUrl &url );
587
588 /**
589 * Returns whether the protocol should be treated as a filesystem
590 * or as a stream when writing to it.
591 *
592 * This corresponds to the "output=" field in the protocol description file.
593 * Valid values for this field are "filesystem", "stream" or "none" (default).
594 *
595 * @param url the url to check
596 * @return the output type of the given @p url
597 */
598 static KProtocolInfo::Type outputType( const KUrl &url );
599
600 /**
601 * Returns the list of fields this protocol returns when listing
602 * The current possibilities are
603 * Name, Type, Size, Date, AccessDate, Access, Owner, Group, Link, URL, MimeType
604 * as well as Extra1, Extra2 etc. for extra fields (see extraFields).
605 *
606 * This corresponds to the "listing=" field in the protocol description file.
607 * The supported fields should be separated with ',' in the protocol description file.
608 *
609 * @param url the url to check
610 * @return a list of field names
611 */
612 static QStringList listing( const KUrl &url );
613
614
615 /**
616 * Returns whether the protocol can act as a source protocol.
617 *
618 * A source protocol retrieves data from or stores data to the
619 * location specified by a URL.
620 * A source protocol is the opposite of a filter protocol.
621 *
622 * The "source=" field in the protocol description file determines
623 * whether a protocol is a source protocol or a filter protocol.
624 * @param url the url to check
625 * @return true if the protocol is a source of data (e.g. http), false if the
626 * protocol is a filter (e.g. gzip)
627 */
628 static bool isSourceProtocol( const KUrl &url );
629
630 /**
631 * Returns which protocol handles this mimetype, if it's an archive mimetype.
632 * For instance zip:/ handles application/x-zip.
633 *
634 * This is defined in the protocol description file using an entry like
635 * "archiveMimetype=application/x-zip"
636 *
637 * @param mimetype the mimetype to check
638 * @return the protocol that can handle this archive mimetype, for instance "zip".
639 * @since 4.1
640 */
641 static QString protocolForArchiveMimetype( const QString& mimeType );
642
643 /*=============================== OTHERS ====================================*/
644
645
646 /**
647 * Force a reload of the general config file of
648 * io-slaves ( kioslaverc).
649 */
650 static void reparseConfiguration();
651
652 /**
653 * Return the protocol to use in order to handle the given @p url
654 * It's usually the same, except that FTP, when handled by a proxy,
655 * needs an HTTP ioslave.
656 *
657 * When a proxy is to be used, proxy contains the URL for the proxy.
658 * @param url the url to check
659 * @param proxy the URL of the proxy to use
660 * @return the slave protocol (e.g. 'http'), can be null if unknown
661 */
662 static QString slaveProtocol(const KUrl &url, QString &proxy);
663
664 /**
665 * Overloaded function that returns a list of all available proxy servers.
666 *
667 * @since 4.7
668 */
669 static QString slaveProtocol(const KUrl &url, QStringList &proxy);
670
671 /**
672 * Return Accept-Languages header built up according to user's desktop
673 * language settings.
674 * @return Accept-Languages header string
675 */
676 static QString acceptLanguagesHeader();
677
678 /**
679 * Returns the charset to use for the specified @ref url.
680 *
681 * @since 4.10
682 */
683 static QString charsetFor(const KUrl& url);
684
685private:
686 friend class KIO::SlaveConfigPrivate;
687
688 /**
689 * @internal
690 * (Shared with SlaveConfig)
691 */
692 KDE_NO_EXPORT static KSharedConfigPtr config();
693};
694#endif
695