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 | */ |
34 | class KIOCORE_EXPORT KProtocolInfo |
35 | { |
36 | public: |
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 { |
101 | /*! |
102 | * \value String |
103 | * \value DateTime |
104 | * \value Invalid |
105 | */ |
106 | enum { |
107 | = QMetaType::QString, |
108 | = QMetaType::QDateTime, |
109 | = QMetaType::UnknownType |
110 | }; |
111 | |
112 | () |
113 | : type(Invalid) |
114 | { |
115 | } |
116 | (const QString &_name, Type _type) |
117 | : name(_name) |
118 | , type(_type) |
119 | { |
120 | } |
121 | QString ; |
122 | Type ; |
123 | }; |
124 | /*! |
125 | * TODO qdoc? |
126 | */ |
127 | typedef QList<ExtraField> ; |
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 (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 | |
364 | private: |
365 | Q_DISABLE_COPY(KProtocolInfo) |
366 | }; |
367 | |
368 | #endif |
369 | |