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

source code of kio/src/core/kprotocolinfo.h