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 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 */
33class KIOCORE_EXPORT KProtocolInfo
34{
35public:
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, bool updateCacheIfNotfound = true);
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 QMetaType::name()
94 * Currently supported types: "QString", "QDateTime" (ISO-8601 format)
95 */
96 struct ExtraField {
97 enum Type { String = QMetaType::QString, DateTime = QMetaType::QDateTime, Invalid = QMetaType::UnknownType };
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 };
111 typedef QList<ExtraField> ExtraFieldList;
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 KIO workers for this protocol.
190 * This limits the number of workers 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's worker metadata.
195 * The default is 1.
196 *
197 * @param protocol the protocol to check
198 * @return the maximum number of workers, or 1 if unknown
199 *
200 * @since 5.101
201 */
202 static int maxWorkers(const QString &protocol);
203
204 /**
205 * Returns the limit on the number of KIO workers for this protocol per host.
206 *
207 * This corresponds to the "maxInstancesPerHost=" field in the protocol's worker metadata.
208 * The default is 0 which means there is no per host limit.
209 *
210 * @param protocol the protocol to check
211 * @return the maximum number of workers, or 1 if unknown
212 *
213 * @since 5.101
214 */
215 static int maxWorkersPerHost(const QString &protocol);
216
217 /**
218 * Returns whether MIME types can be determined based on extension for this
219 * protocol. For some protocols, e.g. http, the filename extension in the URL
220 * can not be trusted to truly reflect the file type.
221 *
222 * This corresponds to the "determineMimetypeFromExtension=" field in the protocol description file.
223 * Valid values for this field are "true" (default) or "false".
224 *
225 * @param protocol the protocol to check
226 * @return true if the MIME types can be determined by extension
227 */
228 static bool determineMimetypeFromExtension(const QString &protocol);
229
230 /**
231 * Returns the default MIME type for the specified protocol, if one exists.
232 *
233 * This corresponds to the "defaultMimetype=" field in the protocol description file.
234 *
235 * @param protocol the protocol to check
236 * @return the default MIME type of the protocol, or an empty string if none set or protocol unknown
237 * @since 5.60
238 */
239 static QString defaultMimetype(const QString &protocol);
240
241 /**
242 * Returns the documentation path for the specified protocol.
243 *
244 * This corresponds to the "X-DocPath=" or "DocPath=" field in the protocol description file.
245 *
246 * @param protocol the protocol to check
247 * @return the docpath of the protocol, or an empty string if unknown
248 */
249 static QString docPath(const QString &protocol);
250
251 /**
252 * Returns the protocol class for the specified protocol.
253 *
254 * This corresponds to the "Class=" field in the protocol description file.
255 *
256 * The following classes are defined:
257 * @li ":internet" for common internet protocols
258 * @li ":local" for protocols that access local resources
259 *
260 * Protocol classes always start with a ':' so that they can not be confused with
261 * the protocols themselves.
262 *
263 * @param protocol the protocol to check
264 * @return the class of the protocol, or an empty string if unknown
265 */
266 static QString protocolClass(const QString &protocol);
267
268 /**
269 * Returns whether file previews should be shown for the specified protocol.
270 *
271 * This corresponds to the "ShowPreviews=" field in the protocol description file.
272 *
273 * By default previews are shown if protocolClass is :local.
274 *
275 * @param protocol the protocol to check
276 * @return true if previews should be shown by default, false otherwise
277 */
278 static bool showFilePreview(const QString &protocol);
279
280 /**
281 * Returns the list of capabilities provided by the KIO worker implementing
282 * this protocol.
283 *
284 * This corresponds to the "Capabilities=" field in the protocol description file.
285 *
286 * The capability names are not defined globally, they are up to each
287 * worker implementation. For example when adding support for a new
288 * special command for mounting, one would add the string "Mount" to the
289 * capabilities list, and applications could check for that string
290 * before sending a special() command that would otherwise do nothing
291 * on older KIO worker implementations.
292 *
293 * @param protocol the protocol to check
294 * @return the list of capabilities.
295 */
296 static QStringList capabilities(const QString &protocol);
297
298 /**
299 * Returns the list of archive MIME types handled by the KIO worker implementing
300 * this protocol.
301 *
302 * This corresponds to the "archiveMimetype=" field in the protocol description file.
303 *
304 * @param protocol the protocol to check
305 * @return the list of archive MIME types (e.g. application/x-zip) handled.
306 * @since 5.23
307 */
308 static QStringList archiveMimetypes(const QString &protocol);
309
310 /**
311 * Returns the name of the protocol through which the request
312 * will be routed if proxy support is enabled.
313 *
314 * A good example of this is the ftp protocol for which proxy
315 * support is commonly handled by the http protocol.
316 *
317 * This corresponds to the "ProxiedBy=" in the protocol description file.
318 */
319 static QString proxiedBy(const QString &protocol);
320
321 typedef enum { Name, FromUrl, DisplayName } FileNameUsedForCopying;
322
323private:
324 Q_DISABLE_COPY(KProtocolInfo)
325};
326
327#endif
328

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