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

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