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 kioslaves 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  /**
189  * Returns the soft limit on the number of slaves for this protocol.
190  * This limits the number of slaves used for a single operation, note
191  * that multiple operations may result in a number of instances that
192  * exceeds this soft limit.
193  *
194  * This corresponds to the "maxInstances=" field in the protocol description file.
195  * The default is 1.
196  *
197  * @param protocol the protocol to check
198  * @return the maximum number of slaves, or 1 if unknown
199  */
200  static int maxSlaves(const QString &protocol);
201 
202  /**
203  * Returns the limit on the number of slaves for this protocol per host.
204  *
205  * This corresponds to the "maxInstancesPerHost=" field in the protocol description file.
206  * The default is 0 which means there is no per host limit.
207  *
208  * @param protocol the protocol to check
209  * @return the maximum number of slaves, or 1 if unknown
210  *
211  * @since 4.4
212  */
213  static int maxSlavesPerHost(const QString &protocol);
214 
215  /**
216  * Returns whether MIME types can be determined based on extension for this
217  * protocol. For some protocols, e.g. http, the filename extension in the URL
218  * can not be trusted to truly reflect the file type.
219  *
220  * This corresponds to the "determineMimetypeFromExtension=" field in the protocol description file.
221  * Valid values for this field are "true" (default) or "false".
222  *
223  * @param protocol the protocol to check
224  * @return true if the MIME types can be determined by extension
225  */
226  static bool determineMimetypeFromExtension(const QString &protocol);
227 
228  /**
229  * Returns the default MIME type for the specified protocol, if one exists.
230  *
231  * This corresponds to the "defaultMimetype=" field in the protocol description file.
232  *
233  * @param protocol the protocol to check
234  * @return the default MIME type of the protocol, or an empty string if none set or protocol unknown
235  * @since 5.60
236  */
237  static QString defaultMimetype(const QString &protocol);
238 
239  /**
240  * Returns the documentation path for the specified protocol.
241  *
242  * This corresponds to the "X-DocPath=" or "DocPath=" field in the protocol description file.
243  *
244  * @param protocol the protocol to check
245  * @return the docpath of the protocol, or an empty string if unknown
246  */
247  static QString docPath(const QString &protocol);
248 
249  /**
250  * Returns the protocol class for the specified protocol.
251  *
252  * This corresponds to the "Class=" field in the protocol description file.
253  *
254  * The following classes are defined:
255  * @li ":internet" for common internet protocols
256  * @li ":local" for protocols that access local resources
257  *
258  * Protocol classes always start with a ':' so that they can not be confused with
259  * the protocols themselves.
260  *
261  * @param protocol the protocol to check
262  * @return the class of the protocol, or an empty string if unknown
263  */
264  static QString protocolClass(const QString &protocol);
265 
266  /**
267  * Returns whether file previews should be shown for the specified protocol.
268  *
269  * This corresponds to the "ShowPreviews=" field in the protocol description file.
270  *
271  * By default previews are shown if protocolClass is :local.
272  *
273  * @param protocol the protocol to check
274  * @return true if previews should be shown by default, false otherwise
275  */
276  static bool showFilePreview(const QString &protocol);
277 
278  /**
279  * Returns the list of capabilities provided by the kioslave implementing
280  * this protocol.
281  *
282  * This corresponds to the "Capabilities=" field in the protocol description file.
283  *
284  * The capability names are not defined globally, they are up to each
285  * slave implementation. For example when adding support for a new
286  * special command for mounting, one would add the string "Mount" to the
287  * capabilities list, and applications could check for that string
288  * before sending a special() command that would otherwise do nothing
289  * on older kioslave implementations.
290  *
291  * @param protocol the protocol to check
292  * @return the list of capabilities.
293  */
294  static QStringList capabilities(const QString &protocol);
295 
296  /**
297  * Returns the list of archive MIME types handled by the kioslave implementing
298  * this protocol.
299  *
300  * This corresponds to the "archiveMimetype=" field in the protocol description file.
301  *
302  * @param protocol the protocol to check
303  * @return the list of archive MIME types (e.g. application/x-zip) handled.
304  * @since 5.23
305  */
306  static QStringList archiveMimetypes(const QString &protocol);
307 
308  /**
309  * Returns the list of notification types the kioslave implementing this
310  * protocol will produce on its own, making it unnecessary for job
311  * implementations to do so. An example would be returning "Rename"
312  * if the kioslave's rename() method takes care of calling
313  * KDirNotify::emitFileRenameWithLocalPath on its own.
314  *
315  * This corresponds to "slaveHandlesNotify=" in the protocol description file.
316  *
317  * @since 5.20
318  */
319  static QStringList slaveHandlesNotify(const QString &protocol);
320 
321  /**
322  * Returns the name of the protocol through which the request
323  * will be routed if proxy support is enabled.
324  *
325  * A good example of this is the ftp protocol for which proxy
326  * support is commonly handled by the http protocol.
327  *
328  * This corresponds to the "ProxiedBy=" in the protocol description file.
329  */
330  static QString proxiedBy(const QString &protocol);
331 
332  typedef enum { Name, FromUrl, DisplayName } FileNameUsedForCopying;
333 
334 private:
335  Q_DISABLE_COPY(KProtocolInfo)
336 };
337 
338 #endif
no information about the type available
Definition: kprotocolinfo.h:84
Information about I/O (Internet, etc.) protocols supported by KDE.
Definition: kprotocolinfo.h:33
Definition of an extra field in the UDS entries, returned by a listDir operation. ...
Definition: kprotocolinfo.h:96
structured directory
Definition: kprotocolinfo.h:83
stream of data (e.g. single file)
Definition: kprotocolinfo.h:82
used to signal an error
Definition: kprotocolinfo.h:85
Type
Describes the type of a protocol.
Definition: kprotocolinfo.h:81
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Apr 16 2021 23:00:36 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.