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

KDE's Doxygen guidelines are available online.