1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 1999 Torben Weis <weis@kde.org>
4 SPDX-FileCopyrightText: 2000 Waldo Bastain <bastain@kde.org>
5 SPDX-FileCopyrightText: 2000 Dawit Alemayehu <adawit@kde.org>
6 SPDX-FileCopyrightText: 2008 Jarosław Staniek <staniek@kde.org>
7 SPDX-FileCopyrightText: 2022 Harald Sitter <sitter@kde.org>
8
9 SPDX-License-Identifier: LGPL-2.0-only
10*/
11
12#ifndef KPROTOCOLMANAGER_H
13#define KPROTOCOLMANAGER_H
14
15#include <QStringList>
16
17#include "kio/global.h" // KIO::CacheControl
18#include "kiocore_export.h"
19#include "kprotocolinfo.h"
20
21class KSharedConfig;
22template<class T>
23class QExplicitlySharedDataPointer;
24typedef QExplicitlySharedDataPointer<KSharedConfig> KSharedConfigPtr;
25namespace KIO
26{
27class WorkerConfigPrivate;
28} // namespace KIO
29
30/*!
31 * \class KProtocolManager
32 * \inmodule KIOCore
33 *
34 * \brief Provides information about I/O (Internet, etc.) settings chosen/set
35 * by the end user.
36 *
37 * KProtocolManager has a heap of static functions that allows only read
38 * access to KDE's IO related settings. These include proxy, cache, file
39 * transfer resumption, timeout and user-agent related settings.
40 *
41 * The information provided by this class is generic enough to be applicable
42 * to any application that makes use of KDE's IO sub-system. Note that this
43 * mean the proxy, timeout etc. settings are saved in a separate user-specific
44 * config file and not in the config file of the application.
45 */
46class KIOCORE_EXPORT KProtocolManager
47{
48public:
49 /*=========================== TIMEOUT CONFIG ================================*/
50
51#if KIOCORE_ENABLE_DEPRECATED_SINCE(6, 11)
52 /*!
53 * Returns the preferred timeout value for reading from
54 * remote connections in seconds.
55 *
56 * Returns the timeout value for remote connection in secs.
57 *
58 * This is not used.
59 *
60 * \deprecated[6.11]
61 */
62 KIOCORE_DEPRECATED_VERSION(6, 11, "Not used")
63 static int readTimeout();
64#endif
65
66#if KIOCORE_ENABLE_DEPRECATED_SINCE(6, 11)
67 /*!
68 * Returns the preferred timeout value for remote connections
69 * in seconds.
70 *
71 * Returns the timeout value for remote connection in secs.
72 *
73 * This is not used.
74 *
75 * \deprecated[6.11]
76 */
77 KIOCORE_DEPRECATED_VERSION(6, 11, "Not used")
78 static int connectTimeout();
79#endif
80
81#if KIOCORE_ENABLE_DEPRECATED_SINCE(6, 11)
82 /*!
83 * Returns the preferred timeout value for proxy connections
84 * in seconds.
85 *
86 * Returns the timeout value for proxy connection in secs.
87 *
88 * This is not used.
89 *
90 * \deprecated[6.11]
91 */
92 KIOCORE_DEPRECATED_VERSION(6, 11, "Not used")
93 static int proxyConnectTimeout();
94#endif
95
96#if KIOCORE_ENABLE_DEPRECATED_SINCE(6, 11)
97 /*!
98 * Returns the preferred response timeout value for
99 * remote connecting in seconds.
100 *
101 * Returns the timeout value for remote connection in seconds.
102 *
103 * This is not used.
104 *
105 * \deprecated[6.11]
106 */
107 KIOCORE_DEPRECATED_VERSION(6, 11, "Not used")
108 static int responseTimeout();
109#endif
110
111 /*============================ DOWNLOAD CONFIG ==============================*/
112
113 /*!
114 * Returns \c true if partial downloads should be
115 * automatically resumed.
116 */
117 static bool autoResume();
118
119 /*!
120 * Returns \c true if partial downloads should be marked
121 * with a ".part" extension.
122 */
123 static bool markPartial();
124
125 /*!
126 * Returns the minimum file size for keeping aborted
127 * downloads.
128 *
129 * Any data downloaded that does not meet this minimum
130 * requirement will simply be discarded. The default size
131 * is 5 KB.
132 */
133 static int minimumKeepSize();
134
135 /*===================== PROTOCOL CAPABILITIES ===============================*/
136
137 /*!
138 * Returns whether the protocol can list files/objects.
139 * If a protocol supports listing it can be browsed in e.g. file-dialogs
140 * and konqueror.
141 *
142 * Whether a protocol supports listing is determined by the "listing="
143 * field in the protocol description file.
144 * If the protocol support listing it should list the fields it provides in
145 * this field. If the protocol does not support listing this field should
146 * remain empty (default.)
147 *
148 * \a url the url to check
149 * \sa listing()
150 */
151 static bool supportsListing(const QUrl &url);
152
153 /*!
154 * Returns whether the protocol can retrieve data from URLs.
155 *
156 * This corresponds to the "reading=" field in the protocol description file.
157 * Valid values for this field are "true" or "false" (default).
158 *
159 * \a url the url to check
160 */
161 static bool supportsReading(const QUrl &url);
162
163 /*!
164 * Returns whether the protocol can store data to URLs.
165 *
166 * This corresponds to the "writing=" field in the protocol description file.
167 * Valid values for this field are "true" or "false" (default).
168 *
169 * \a url the url to check
170 */
171 static bool supportsWriting(const QUrl &url);
172
173 /*!
174 * Returns whether the protocol can create directories/folders.
175 *
176 * This corresponds to the "makedir=" field in the protocol description file.
177 * Valid values for this field are "true" or "false" (default).
178 *
179 * \a url the url to check
180 */
181 static bool supportsMakeDir(const QUrl &url);
182
183 /*!
184 * Returns whether the protocol can delete files/objects.
185 *
186 * This corresponds to the "deleting=" field in the protocol description file.
187 * Valid values for this field are "true" or "false" (default).
188 *
189 * \a url the url to check
190 */
191 static bool supportsDeleting(const QUrl &url);
192
193 /*!
194 * Returns whether the protocol can create links between files/objects.
195 *
196 * This corresponds to the "linking=" field in the protocol description file.
197 * Valid values for this field are "true" or "false" (default).
198 *
199 * \a url the url to check
200 */
201 static bool supportsLinking(const QUrl &url);
202
203 /*!
204 * Returns whether the protocol can move files/objects between different
205 * locations.
206 *
207 * This corresponds to the "moving=" field in the protocol description file.
208 * Valid values for this field are "true" or "false" (default).
209 *
210 * \a url the url to check
211 */
212 static bool supportsMoving(const QUrl &url);
213
214 /*!
215 * Returns whether the protocol can be opened using KIO::open(const QUrl&).
216 *
217 * This corresponds to the "opening=" field in the protocol description file.
218 * Valid values for this field are "true" or "false" (default).
219 *
220 * \a url the url to check
221 */
222 static bool supportsOpening(const QUrl &url);
223
224 /*!
225 * Returns whether the protocol can be truncated with FileJob::truncate(KIO::filesize_t length).
226 *
227 * This corresponds to the "truncating=" field in the protocol description file.
228 * Valid values for this field are "true" or "false" (default).
229 *
230 * \a url the url to check
231 * \since 5.66
232 */
233 static bool supportsTruncating(const QUrl &url);
234
235 /*!
236 * Returns whether the protocol can copy files/objects directly from the
237 * filesystem itself. If not, the application will read files from the
238 * filesystem using the file-protocol and pass the data on to the destination
239 * protocol.
240 *
241 * This corresponds to the "copyFromFile=" field in the protocol description file.
242 * Valid values for this field are "true" or "false" (default).
243 *
244 * \a url the url to check
245 */
246 static bool canCopyFromFile(const QUrl &url);
247
248 /*!
249 * Returns whether the protocol can copy files/objects directly to the
250 * filesystem itself. If not, the application will receive the data from
251 * the source protocol and store it in the filesystem using the
252 * file-protocol.
253 *
254 * This corresponds to the "copyToFile=" field in the protocol description file.
255 * Valid values for this field are "true" or "false" (default).
256 *
257 * \a url the url to check
258 */
259 static bool canCopyToFile(const QUrl &url);
260
261 /*!
262 * Returns whether the protocol can rename (i.e. move fast) files/objects
263 * directly from the filesystem itself. If not, the application will read
264 * files from the filesystem using the file-protocol and pass the data on
265 * to the destination protocol.
266 *
267 * This corresponds to the "renameFromFile=" field in the protocol description file.
268 * Valid values for this field are "true" or "false" (default).
269 *
270 * \a url the url to check
271 */
272 static bool canRenameFromFile(const QUrl &url);
273
274 /*!
275 * Returns whether the protocol can rename (i.e. move fast) files/objects
276 * directly to the filesystem itself. If not, the application will receive
277 * the data from the source protocol and store it in the filesystem using the
278 * file-protocol.
279 *
280 * This corresponds to the "renameToFile=" field in the protocol description file.
281 * Valid values for this field are "true" or "false" (default).
282 *
283 * \a url the url to check
284 */
285 static bool canRenameToFile(const QUrl &url);
286
287 /*!
288 * Returns whether the protocol can recursively delete directories by itself.
289 * If not (the usual case) then KIO will list the directory and delete files
290 * and empty directories one by one.
291 *
292 * This corresponds to the "deleteRecursive=" field in the protocol description file.
293 * Valid values for this field are "true" or "false" (default).
294 *
295 * \a url the url to check
296 */
297 static bool canDeleteRecursive(const QUrl &url);
298
299 /*!
300 * This setting defines the strategy to use for generating a filename, when
301 * copying a file or directory to another directory. By default the destination
302 * filename is made out of the filename in the source URL. However if the
303 * KIO worker displays names that are different from the filename of the URL
304 * (e.g. kio_fonts shows Arial for arial.ttf, or kio_trash shows foo.txt and
305 * uses some internal URL), using Name means that the display name (UDS_NAME)
306 * will be used to as the filename in the destination directory.
307 *
308 * This corresponds to the "fileNameUsedForCopying=" field in the protocol description file.
309 * Valid values for this field are "Name" or "FromURL" (default).
310 *
311 * \a url the url to check
312 */
313 static KProtocolInfo::FileNameUsedForCopying fileNameUsedForCopying(const QUrl &url);
314
315 /*!
316 * Returns default MIME type for this URL based on the protocol.
317 *
318 * This corresponds to the "defaultMimetype=" field in the protocol description file.
319 *
320 * \a url the url to check
321 */
322 static QString defaultMimetype(const QUrl &url);
323
324 /*!
325 * Returns whether the protocol should be treated as a filesystem
326 * or as a stream when reading from it.
327 *
328 * This corresponds to the "input=" field in the protocol description file.
329 * Valid values for this field are "filesystem", "stream" or "none" (default).
330 *
331 * \a url the url to check
332 */
333 static KProtocolInfo::Type inputType(const QUrl &url);
334
335 /*!
336 * Returns whether the protocol should be treated as a filesystem
337 * or as a stream when writing to it.
338 *
339 * This corresponds to the "output=" field in the protocol description file.
340 * Valid values for this field are "filesystem", "stream" or "none" (default).
341 *
342 * \a url the url to check
343 */
344 static KProtocolInfo::Type outputType(const QUrl &url);
345
346 /*!
347 * Returns the list of fields this protocol returns when listing
348 * The current possibilities are
349 * Name, Type, Size, Date, AccessDate, Access, Owner, Group, Link, URL, MimeType
350 * as well as Extra1, Extra2 etc. for extra fields (see extraFields).
351 *
352 * This corresponds to the "listing=" field in the protocol description file.
353 * The supported fields should be separated with ',' in the protocol description file.
354 *
355 * \a url the url to check
356 */
357 static QStringList listing(const QUrl &url);
358
359 /*!
360 * Returns whether the protocol can act as a source protocol.
361 *
362 * A source protocol retrieves data from or stores data to the
363 * location specified by a URL.
364 * A source protocol is the opposite of a filter protocol.
365 *
366 * The "source=" field in the protocol description file determines
367 * whether a protocol is a source protocol or a filter protocol.
368 *
369 * \a url the url to check
370 *
371 * Returns true if the protocol is a source of data (e.g. http), false if the
372 * protocol is a filter (e.g. gzip)
373 */
374 static bool isSourceProtocol(const QUrl &url);
375
376 /*!
377 * Returns which protocol handles this MIME type, if it's an archive MIME type.
378 * For instance zip:/ handles application/x-zip.
379 *
380 * This is defined in the protocol description file using an entry like
381 * "archiveMimetype=application/x-zip"
382 *
383 * \a mimeType the MIME type to check
384 */
385 static QString protocolForArchiveMimetype(const QString &mimeType);
386
387 /*=============================== OTHERS ====================================*/
388
389 /*!
390 * Force a reload of the general config file of
391 * KIO workers ( kioslaverc).
392 */
393 static void reparseConfiguration();
394
395 /*!
396 * Returns the charset to use for the specified \a url.
397 *
398 */
399 static QString charsetFor(const QUrl &url);
400
401 /*!
402 * Returns whether the protocol suppports KIO/POSIX permissions handling.
403 *
404 * When this is false the Permissions properties tab may be hidden, for example. The protocol may still support
405 * permission control through other means, specific to the individual KIO worker.
406 *
407 * \a url the url to check
408 * \since 5.98
409 */
410 static bool supportsPermissions(const QUrl &url);
411
412private:
413 friend class KIO::WorkerConfigPrivate;
414
415 KIOCORE_NO_EXPORT static QMap<QString, QString> entryMap(const QString &group);
416};
417#endif
418

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