KIO

kprotocolinfo.h
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 {
98 String = QMetaType::QString,
99 DateTime = QMetaType::QDateTime,
100 Invalid = QMetaType::UnknownType
101 };
102
103 ExtraField()
104 : type(Invalid)
105 {
106 }
107 ExtraField(const QString &_name, Type _type)
108 : name(_name)
109 , type(_type)
110 {
111 }
112 QString name;
113 Type type;
114 };
116 /**
117 * Definition of extra fields in the UDS entries, returned by a listDir operation.
118 *
119 * This corresponds to the "ExtraNames=" and "ExtraTypes=" fields in the protocol description file.
120 * Those two lists should be separated with ',' in the protocol description file.
121 * See ExtraField for details about names and types
122 */
123 static ExtraFieldList extraFields(const QUrl &url);
124
125 /**
126 * Returns whether the protocol can act as a helper protocol.
127 * A helper protocol invokes an external application and does not return
128 * a file or stream.
129 *
130 * This corresponds to the "helper=" field in the protocol description file.
131 * Valid values for this field are "true" or "false" (default).
132 *
133 * @param url the url to check
134 * @return true if the protocol is a helper protocol (e.g. vnc), false
135 * if not (e.g. http)
136 */
137 static bool isHelperProtocol(const QUrl &url);
138
139 /**
140 * Same as above except you can supply just the protocol instead of
141 * the whole URL.
142 */
143 static bool isHelperProtocol(const QString &protocol);
144
145 /**
146 * Returns whether the protocol can act as a filter protocol.
147 *
148 * A filter protocol can operate on data that is passed to it
149 * but does not retrieve/store data itself, like gzip.
150 * A filter protocol is the opposite of a source protocol.
151 *
152 * The "source=" field in the protocol description file determines
153 * whether a protocol is a source protocol or a filter protocol.
154 * Valid values for this field are "true" (default) for source protocol or
155 * "false" for filter protocol.
156 *
157 * @param url the url to check
158 * @return true if the protocol is a filter (e.g. gzip), false if the
159 * protocol is a helper or source
160 */
161 static bool isFilterProtocol(const QUrl &url);
162
163 /**
164 * Same as above except you can supply just the protocol instead of
165 * the whole URL.
166 */
167 static bool isFilterProtocol(const QString &protocol);
168
169 /**
170 * Returns the name of the icon, associated with the specified protocol.
171 *
172 * This corresponds to the "Icon=" field in the protocol description file.
173 *
174 * @param protocol the protocol to check
175 * @return the icon of the protocol, or an empty string if unknown
176 */
177 static QString icon(const QString &protocol);
178
179 /**
180 * Returns the name of the config file associated with the
181 * specified protocol. This is useful if two similar protocols
182 * need to share a single config file, e.g. http and https.
183 *
184 * This corresponds to the "config=" field in the protocol description file.
185 * The default is the protocol name, see name()
186 *
187 * @param protocol the protocol to check
188 * @return the config file, or an empty string if unknown
189 */
190 static QString config(const QString &protocol);
191
192 /**
193 * Returns the soft limit on the number of KIO workers for this protocol.
194 * This limits the number of workers used for a single operation, note
195 * that multiple operations may result in a number of instances that
196 * exceeds this soft limit.
197 *
198 * This corresponds to the "maxInstances=" field in the protocol's worker metadata.
199 * The default is 1.
200 *
201 * @param protocol the protocol to check
202 * @return the maximum number of workers, or 1 if unknown
203 *
204 * @since 5.101
205 */
206 static int maxWorkers(const QString &protocol);
207
208 /**
209 * Returns the limit on the number of KIO workers for this protocol per host.
210 *
211 * This corresponds to the "maxInstancesPerHost=" field in the protocol's worker metadata.
212 * The default is 0 which means there is no per host limit.
213 *
214 * @param protocol the protocol to check
215 * @return the maximum number of workers, or 1 if unknown
216 *
217 * @since 5.101
218 */
219 static int maxWorkersPerHost(const QString &protocol);
220
221 /**
222 * Returns whether MIME types can be determined based on extension for this
223 * protocol. For some protocols, e.g. http, the filename extension in the URL
224 * can not be trusted to truly reflect the file type.
225 *
226 * This corresponds to the "determineMimetypeFromExtension=" field in the protocol description file.
227 * Valid values for this field are "true" (default) or "false".
228 *
229 * @param protocol the protocol to check
230 * @return true if the MIME types can be determined by extension
231 */
232 static bool determineMimetypeFromExtension(const QString &protocol);
233
234 /**
235 * Returns the default MIME type for the specified protocol, if one exists.
236 *
237 * This corresponds to the "defaultMimetype=" field in the protocol description file.
238 *
239 * @param protocol the protocol to check
240 * @return the default MIME type of the protocol, or an empty string if none set or protocol unknown
241 * @since 5.60
242 */
243 static QString defaultMimetype(const QString &protocol);
244
245 /**
246 * Returns the documentation path for the specified protocol.
247 *
248 * This corresponds to the "X-DocPath=" or "DocPath=" field in the protocol description file.
249 *
250 * @param protocol the protocol to check
251 * @return the docpath of the protocol, or an empty string if unknown
252 */
253 static QString docPath(const QString &protocol);
254
255 /**
256 * Returns the protocol class for the specified protocol.
257 *
258 * This corresponds to the "Class=" field in the protocol description file.
259 *
260 * The following classes are defined:
261 * @li ":internet" for common internet protocols
262 * @li ":local" for protocols that access local resources
263 *
264 * Protocol classes always start with a ':' so that they can not be confused with
265 * the protocols themselves.
266 *
267 * @param protocol the protocol to check
268 * @return the class of the protocol, or an empty string if unknown
269 */
270 static QString protocolClass(const QString &protocol);
271
272 /**
273 * Returns whether file previews should be shown for the specified protocol.
274 *
275 * This corresponds to the "ShowPreviews=" field in the protocol description file.
276 *
277 * By default previews are shown if protocolClass is :local.
278 *
279 * @param protocol the protocol to check
280 * @return true if previews should be shown by default, false otherwise
281 */
282 static bool showFilePreview(const QString &protocol);
283
284 /**
285 * Returns the list of capabilities provided by the KIO worker implementing
286 * this protocol.
287 *
288 * This corresponds to the "Capabilities=" field in the protocol description file.
289 *
290 * The capability names are not defined globally, they are up to each
291 * worker implementation. For example when adding support for a new
292 * special command for mounting, one would add the string "Mount" to the
293 * capabilities list, and applications could check for that string
294 * before sending a special() command that would otherwise do nothing
295 * on older KIO worker implementations.
296 *
297 * @param protocol the protocol to check
298 * @return the list of capabilities.
299 */
300 static QStringList capabilities(const QString &protocol);
301
302 /**
303 * Returns the list of archive MIME types handled by the KIO worker implementing
304 * this protocol.
305 *
306 * This corresponds to the "archiveMimetype=" field in the protocol description file.
307 *
308 * @param protocol the protocol to check
309 * @return the list of archive MIME types (e.g. application/x-zip) handled.
310 * @since 5.23
311 */
312 static QStringList archiveMimetypes(const QString &protocol);
313
314#if KIOCORE_ENABLE_DEPRECATED_SINCE(6, 4)
315 /**
316 * Returns the name of the protocol through which the request
317 * will be routed if proxy support is enabled.
318 *
319 * A good example of this is the ftp protocol for which proxy
320 * support is commonly handled by the http protocol.
321 *
322 * This corresponds to the "ProxiedBy=" in the protocol description file.
323 *
324 * @deprecated since 6.4, not used.
325 */
326 KIOCORE_DEPRECATED_VERSION(6, 4, "Not used")
327 static QString proxiedBy(const QString &protocol);
328#endif
329
330 typedef enum {
331 Name,
332 FromUrl,
333 DisplayName
334 } FileNameUsedForCopying;
335
336private:
337 Q_DISABLE_COPY(KProtocolInfo)
338};
339
340#endif
Information about I/O (Internet, etc.) protocols supported by KDE.
Type
Describes the type of a protocol.
@ T_ERROR
used to signal an error
@ T_STREAM
stream of data (e.g. single file)
@ T_NONE
no information about the type available
@ T_FILESYSTEM
structured directory
Definition of an extra field in the UDS entries, returned by a listDir operation.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Wed Nov 6 2024 12:07:34 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.