KIO

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

KDE's Doxygen guidelines are available online.