KIO

kprotocolinfo.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 1999 Torben Weis <[email protected]>
4  SPDX-FileCopyrightText: 2000-2001 Waldo Bastian <[email protected]>
5  SPDX-FileCopyrightText: 2012 David Faure <[email protected]>
6 
7  SPDX-License-Identifier: LGPL-2.0-only
8 */
9 
10 #ifndef KPROTOCOLINFO_H
11 #define KPROTOCOLINFO_H
12 
13 #include "kiocore_export.h"
14 #include <QStringList>
15 #include <QVariant>
16 
17 /**
18  * \class KProtocolInfo kprotocolinfo.h <KProtocolInfo>
19  *
20  * Information about I/O (Internet, etc.) protocols supported by KDE.
21 
22  * KProtocolInfo is useful if you want to know which protocols
23  * KDE supports. In addition you can find out lots of information
24  * about a certain protocol. All of the functionality is provided by the static
25  * methods.
26  * The implementation scans the *.protocol files of all installed KIO workers to get
27  * this information and stores the result into an internal cache.
28  *
29  * *.protocol files are installed in the "services" resource.
30  *
31  * The KProtocolInfo methods are reentrant (i.e. can be called from multiple threads simultaneously).
32  */
33 class KIOCORE_EXPORT KProtocolInfo
34 {
35 public:
36  //
37  // Static functions:
38  //
39 
40  /**
41  * Returns list of all known protocols.
42  * @return a list of all known protocols
43  */
44  static QStringList protocols();
45 
46  /**
47  * Returns whether a protocol is installed that is able to handle @p url.
48  *
49  * @param url the url to check
50  * @return true if the protocol is known
51  * @see name()
52  */
53  static bool isKnownProtocol(const QUrl &url);
54 
55  /**
56  * Same as above except you can supply just the protocol instead of
57  * the whole URL.
58  */
59  static bool isKnownProtocol(const QString &protocol);
60 
61  /**
62  * Returns the library / executable to open for the protocol @p protocol
63  * Example : "kio_ftp", meaning either the executable "kio_ftp" or
64  * the library "kio_ftp.la" (recommended), whichever is available.
65  *
66  * This corresponds to the "exec=" field in the protocol description file.
67  * @param protocol the protocol to check
68  * @return the executable of library to open, or QString() for
69  * unsupported protocols
70  * @see KUrl::protocol()
71  */
72  static QString exec(const QString &protocol);
73 
74  /**
75  * Describes the type of a protocol.
76  * For instance ftp:// appears as a filesystem with folders and files,
77  * while bzip2:// appears as a single file (a stream of data),
78  * and telnet:// doesn't output anything.
79  * @see outputType
80  */
81  enum Type {
82  T_STREAM, ///< stream of data (e.g.\ single file)
83  T_FILESYSTEM, ///< structured directory
84  T_NONE, ///< no information about the type available
85  T_ERROR, ///< used to signal an error
86  };
87 
88  /**
89  * Definition of an extra field in the UDS entries, returned by a listDir operation.
90  *
91  * The name is the name of the column, translated.
92  *
93  * The type name comes from QVariant::typeName()
94  * Currently supported types: "QString", "QDateTime" (ISO-8601 format)
95  */
96  struct ExtraField {
97  enum Type { String = QVariant::String, DateTime = QVariant::DateTime, Invalid = QVariant::Invalid };
98 
99  ExtraField()
100  : type(Invalid)
101  {
102  }
103  ExtraField(const QString &_name, Type _type)
104  : name(_name)
105  , type(_type)
106  {
107  }
108  QString name;
109  Type type;
110  };
112  /**
113  * Definition of extra fields in the UDS entries, returned by a listDir operation.
114  *
115  * This corresponds to the "ExtraNames=" and "ExtraTypes=" fields in the protocol description file.
116  * Those two lists should be separated with ',' in the protocol description file.
117  * See ExtraField for details about names and types
118  */
119  static ExtraFieldList extraFields(const QUrl &url);
120 
121  /**
122  * Returns whether the protocol can act as a helper protocol.
123  * A helper protocol invokes an external application and does not return
124  * a file or stream.
125  *
126  * This corresponds to the "helper=" field in the protocol description file.
127  * Valid values for this field are "true" or "false" (default).
128  *
129  * @param url the url to check
130  * @return true if the protocol is a helper protocol (e.g. vnc), false
131  * if not (e.g. http)
132  */
133  static bool isHelperProtocol(const QUrl &url);
134 
135  /**
136  * Same as above except you can supply just the protocol instead of
137  * the whole URL.
138  */
139  static bool isHelperProtocol(const QString &protocol);
140 
141  /**
142  * Returns whether the protocol can act as a filter protocol.
143  *
144  * A filter protocol can operate on data that is passed to it
145  * but does not retrieve/store data itself, like gzip.
146  * A filter protocol is the opposite of a source protocol.
147  *
148  * The "source=" field in the protocol description file determines
149  * whether a protocol is a source protocol or a filter protocol.
150  * Valid values for this field are "true" (default) for source protocol or
151  * "false" for filter protocol.
152  *
153  * @param url the url to check
154  * @return true if the protocol is a filter (e.g. gzip), false if the
155  * protocol is a helper or source
156  */
157  static bool isFilterProtocol(const QUrl &url);
158 
159  /**
160  * Same as above except you can supply just the protocol instead of
161  * the whole URL.
162  */
163  static bool isFilterProtocol(const QString &protocol);
164 
165  /**
166  * Returns the name of the icon, associated with the specified protocol.
167  *
168  * This corresponds to the "Icon=" field in the protocol description file.
169  *
170  * @param protocol the protocol to check
171  * @return the icon of the protocol, or an empty string if unknown
172  */
173  static QString icon(const QString &protocol);
174 
175  /**
176  * Returns the name of the config file associated with the
177  * specified protocol. This is useful if two similar protocols
178  * need to share a single config file, e.g. http and https.
179  *
180  * This corresponds to the "config=" field in the protocol description file.
181  * The default is the protocol name, see name()
182  *
183  * @param protocol the protocol to check
184  * @return the config file, or an empty string if unknown
185  */
186  static QString config(const QString &protocol);
187 
188 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 101)
189  /**
190  * Returns the soft limit on the number of slaves for this protocol.
191  * This limits the number of slaves used for a single operation, note
192  * that multiple operations may result in a number of instances that
193  * exceeds this soft limit.
194  *
195  * This corresponds to the "maxInstances=" field in the protocol description file.
196  * The default is 1.
197  *
198  * @param protocol the protocol to check
199  * @return the maximum number of slaves, or 1 if unknown
200  *
201  * @deprecated Since 5.101, use maxWorkers(const QString &)
202  */
203  static KIOCORE_DEPRECATED_VERSION(5, 101, "Use maxWorkers(const QString&)") int maxSlaves(const QString &protocol);
204 #endif
205 
206 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 101)
207  /**
208  * Returns the limit on the number of slaves for this protocol per host.
209  *
210  * This corresponds to the "maxInstancesPerHost=" field in the protocol description file.
211  * The default is 0 which means there is no per host limit.
212  *
213  * @param protocol the protocol to check
214  * @return the maximum number of slaves, or 1 if unknown
215  *
216  * @since 4.4
217  * @deprecated Since 5.101, use maxWorkersPerHost(const QString &)
218  */
219  static KIOCORE_DEPRECATED_VERSION(5, 101, "Use maxWorkersPerHost(const QString&)") int maxSlavesPerHost(const QString &protocol);
220 #endif
221 
222  /**
223  * Returns the soft limit on the number of KIO workers for this protocol.
224  * This limits the number of workers used for a single operation, note
225  * that multiple operations may result in a number of instances that
226  * exceeds this soft limit.
227  *
228  * This corresponds to the "maxInstances=" field in the protocol's worker metadata.
229  * The default is 1.
230  *
231  * @param protocol the protocol to check
232  * @return the maximum number of workers, or 1 if unknown
233  *
234  * @since 5.101
235  */
236  static int maxWorkers(const QString &protocol);
237 
238  /**
239  * Returns the limit on the number of KIO workers for this protocol per host.
240  *
241  * This corresponds to the "maxInstancesPerHost=" field in the protocol's worker metadata.
242  * The default is 0 which means there is no per host limit.
243  *
244  * @param protocol the protocol to check
245  * @return the maximum number of workers, or 1 if unknown
246  *
247  * @since 5.101
248  */
249  static int maxWorkersPerHost(const QString &protocol);
250 
251  /**
252  * Returns whether MIME types can be determined based on extension for this
253  * protocol. For some protocols, e.g. http, the filename extension in the URL
254  * can not be trusted to truly reflect the file type.
255  *
256  * This corresponds to the "determineMimetypeFromExtension=" field in the protocol description file.
257  * Valid values for this field are "true" (default) or "false".
258  *
259  * @param protocol the protocol to check
260  * @return true if the MIME types can be determined by extension
261  */
262  static bool determineMimetypeFromExtension(const QString &protocol);
263 
264  /**
265  * Returns the default MIME type for the specified protocol, if one exists.
266  *
267  * This corresponds to the "defaultMimetype=" field in the protocol description file.
268  *
269  * @param protocol the protocol to check
270  * @return the default MIME type of the protocol, or an empty string if none set or protocol unknown
271  * @since 5.60
272  */
273  static QString defaultMimetype(const QString &protocol);
274 
275  /**
276  * Returns the documentation path for the specified protocol.
277  *
278  * This corresponds to the "X-DocPath=" or "DocPath=" field in the protocol description file.
279  *
280  * @param protocol the protocol to check
281  * @return the docpath of the protocol, or an empty string if unknown
282  */
283  static QString docPath(const QString &protocol);
284 
285  /**
286  * Returns the protocol class for the specified protocol.
287  *
288  * This corresponds to the "Class=" field in the protocol description file.
289  *
290  * The following classes are defined:
291  * @li ":internet" for common internet protocols
292  * @li ":local" for protocols that access local resources
293  *
294  * Protocol classes always start with a ':' so that they can not be confused with
295  * the protocols themselves.
296  *
297  * @param protocol the protocol to check
298  * @return the class of the protocol, or an empty string if unknown
299  */
300  static QString protocolClass(const QString &protocol);
301 
302  /**
303  * Returns whether file previews should be shown for the specified protocol.
304  *
305  * This corresponds to the "ShowPreviews=" field in the protocol description file.
306  *
307  * By default previews are shown if protocolClass is :local.
308  *
309  * @param protocol the protocol to check
310  * @return true if previews should be shown by default, false otherwise
311  */
312  static bool showFilePreview(const QString &protocol);
313 
314  /**
315  * Returns the list of capabilities provided by the KIO worker implementing
316  * this protocol.
317  *
318  * This corresponds to the "Capabilities=" field in the protocol description file.
319  *
320  * The capability names are not defined globally, they are up to each
321  * worker implementation. For example when adding support for a new
322  * special command for mounting, one would add the string "Mount" to the
323  * capabilities list, and applications could check for that string
324  * before sending a special() command that would otherwise do nothing
325  * on older KIO worker implementations.
326  *
327  * @param protocol the protocol to check
328  * @return the list of capabilities.
329  */
330  static QStringList capabilities(const QString &protocol);
331 
332  /**
333  * Returns the list of archive MIME types handled by the KIO worker implementing
334  * this protocol.
335  *
336  * This corresponds to the "archiveMimetype=" field in the protocol description file.
337  *
338  * @param protocol the protocol to check
339  * @return the list of archive MIME types (e.g. application/x-zip) handled.
340  * @since 5.23
341  */
342  static QStringList archiveMimetypes(const QString &protocol);
343 
344 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 101)
345  /**
346  * Returns the list of notification types the kioslave implementing this
347  * protocol will produce on its own, making it unnecessary for job
348  * implementations to do so. An example would be returning "Rename"
349  * if the kioslave's rename() method takes care of calling
350  * KDirNotify::emitFileRenameWithLocalPath on its own.
351  *
352  * This corresponds to "slaveHandlesNotify=" in the protocol description file.
353  *
354  * @since 5.20
355  * @deprecated Since 5.101, no known users
356  */
357  static KIOCORE_DEPRECATED_VERSION(5, 101, "No known users") QStringList slaveHandlesNotify(const QString &protocol);
358 #endif
359 
360  /**
361  * Returns the name of the protocol through which the request
362  * will be routed if proxy support is enabled.
363  *
364  * A good example of this is the ftp protocol for which proxy
365  * support is commonly handled by the http protocol.
366  *
367  * This corresponds to the "ProxiedBy=" in the protocol description file.
368  */
369  static QString proxiedBy(const QString &protocol);
370 
371  typedef enum { Name, FromUrl, DisplayName } FileNameUsedForCopying;
372 
373 private:
374  Q_DISABLE_COPY(KProtocolInfo)
375 };
376 
377 #endif
@ T_NONE
no information about the type available
Definition: kprotocolinfo.h:84
Definition of an extra field in the UDS entries, returned by a listDir operation.
Definition: kprotocolinfo.h:96
Type
Describes the type of a protocol.
Definition: kprotocolinfo.h:81
@ T_FILESYSTEM
structured directory
Definition: kprotocolinfo.h:83
@ T_STREAM
stream of data (e.g. single file)
Definition: kprotocolinfo.h:82
KSharedConfigPtr config()
@ T_ERROR
used to signal an error
Definition: kprotocolinfo.h:85
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Sep 30 2023 03:50:08 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.