File indexing completed on 2024-11-03 06:47:37
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 1999 Torben Weis <weis@kde.org> 0004 SPDX-FileCopyrightText: 2000 Waldo Bastain <bastain@kde.org> 0005 SPDX-FileCopyrightText: 2000 Dawit Alemayehu <adawit@kde.org> 0006 SPDX-FileCopyrightText: 2008 Jarosław Staniek <staniek@kde.org> 0007 SPDX-FileCopyrightText: 2022 Harald Sitter <sitter@kde.org> 0008 0009 SPDX-License-Identifier: LGPL-2.0-only 0010 */ 0011 0012 #ifndef KPROTOCOLMANAGER_H 0013 #define KPROTOCOLMANAGER_H 0014 0015 #include <QStringList> 0016 0017 #include "kio/global.h" // KIO::CacheControl 0018 #include "kiocore_export.h" 0019 #include "kprotocolinfo.h" 0020 0021 class KSharedConfig; 0022 template<class T> 0023 class QExplicitlySharedDataPointer; 0024 typedef QExplicitlySharedDataPointer<KSharedConfig> KSharedConfigPtr; 0025 namespace KIO 0026 { 0027 class WorkerConfigPrivate; 0028 } // namespace KIO 0029 0030 /** 0031 * @class KProtocolManager kprotocolmanager.h <KProtocolManager> 0032 * 0033 * Provides information about I/O (Internet, etc.) settings chosen/set 0034 * by the end user. 0035 * 0036 * KProtocolManager has a heap of static functions that allows only read 0037 * access to KDE's IO related settings. These include proxy, cache, file 0038 * transfer resumption, timeout and user-agent related settings. 0039 * 0040 * The information provided by this class is generic enough to be applicable 0041 * to any application that makes use of KDE's IO sub-system. Note that this 0042 * mean the proxy, timeout etc. settings are saved in a separate user-specific 0043 * config file and not in the config file of the application. 0044 * 0045 * Original author: 0046 * @author Torben Weis <weis@kde.org> 0047 * 0048 * Revised by: 0049 * @author Waldo Bastain <bastain@kde.org> 0050 * @author Dawit Alemayehu <adawit@kde.org> 0051 * @see KPAC 0052 */ 0053 class KIOCORE_EXPORT KProtocolManager 0054 { 0055 public: 0056 /*=========================== TIMEOUT CONFIG ================================*/ 0057 0058 /** 0059 * Returns the preferred timeout value for reading from 0060 * remote connections in seconds. 0061 * 0062 * @return timeout value for remote connection in secs. 0063 */ 0064 static int readTimeout(); 0065 0066 /** 0067 * Returns the preferred timeout value for remote connections 0068 * in seconds. 0069 * 0070 * @return timeout value for remote connection in secs. 0071 */ 0072 static int connectTimeout(); 0073 0074 /** 0075 * Returns the preferred timeout value for proxy connections 0076 * in seconds. 0077 * 0078 * @return timeout value for proxy connection in secs. 0079 */ 0080 static int proxyConnectTimeout(); 0081 0082 /** 0083 * Returns the preferred response timeout value for 0084 * remote connecting in seconds. 0085 * 0086 * @return timeout value for remote connection in seconds. 0087 */ 0088 static int responseTimeout(); 0089 0090 /*============================ DOWNLOAD CONFIG ==============================*/ 0091 0092 /** 0093 * Returns true if partial downloads should be 0094 * automatically resumed. 0095 * @return true to resume partial downloads 0096 */ 0097 static bool autoResume(); 0098 0099 /** 0100 * Returns true if partial downloads should be marked 0101 * with a ".part" extension. 0102 * @return true if partial downloads should get an ".part" extension 0103 */ 0104 static bool markPartial(); 0105 0106 /** 0107 * Returns the minimum file size for keeping aborted 0108 * downloads. 0109 * 0110 * Any data downloaded that does not meet this minimum 0111 * requirement will simply be discarded. The default size 0112 * is 5 KB. 0113 * 0114 * @return the minimum keep size for aborted downloads in bytes 0115 */ 0116 static int minimumKeepSize(); 0117 0118 /*===================== PROTOCOL CAPABILITIES ===============================*/ 0119 0120 /** 0121 * Returns whether the protocol can list files/objects. 0122 * If a protocol supports listing it can be browsed in e.g. file-dialogs 0123 * and konqueror. 0124 * 0125 * Whether a protocol supports listing is determined by the "listing=" 0126 * field in the protocol description file. 0127 * If the protocol support listing it should list the fields it provides in 0128 * this field. If the protocol does not support listing this field should 0129 * remain empty (default.) 0130 * 0131 * @param url the url to check 0132 * @return true if the protocol support listing 0133 * @see listing() 0134 */ 0135 static bool supportsListing(const QUrl &url); 0136 0137 /** 0138 * Returns whether the protocol can retrieve data from URLs. 0139 * 0140 * This corresponds to the "reading=" field in the protocol description file. 0141 * Valid values for this field are "true" or "false" (default). 0142 * 0143 * @param url the url to check 0144 * @return true if it is possible to read from the URL 0145 */ 0146 static bool supportsReading(const QUrl &url); 0147 0148 /** 0149 * Returns whether the protocol can store data to URLs. 0150 * 0151 * This corresponds to the "writing=" field in the protocol description file. 0152 * Valid values for this field are "true" or "false" (default). 0153 * 0154 * @param url the url to check 0155 * @return true if the protocol supports writing 0156 */ 0157 static bool supportsWriting(const QUrl &url); 0158 0159 /** 0160 * Returns whether the protocol can create directories/folders. 0161 * 0162 * This corresponds to the "makedir=" field in the protocol description file. 0163 * Valid values for this field are "true" or "false" (default). 0164 * 0165 * @param url the url to check 0166 * @return true if the protocol can create directories 0167 */ 0168 static bool supportsMakeDir(const QUrl &url); 0169 0170 /** 0171 * Returns whether the protocol can delete files/objects. 0172 * 0173 * This corresponds to the "deleting=" field in the protocol description file. 0174 * Valid values for this field are "true" or "false" (default). 0175 * 0176 * @param url the url to check 0177 * @return true if the protocol supports deleting 0178 */ 0179 static bool supportsDeleting(const QUrl &url); 0180 0181 /** 0182 * Returns whether the protocol can create links between files/objects. 0183 * 0184 * This corresponds to the "linking=" field in the protocol description file. 0185 * Valid values for this field are "true" or "false" (default). 0186 * 0187 * @param url the url to check 0188 * @return true if the protocol supports linking 0189 */ 0190 static bool supportsLinking(const QUrl &url); 0191 0192 /** 0193 * Returns whether the protocol can move files/objects between different 0194 * locations. 0195 * 0196 * This corresponds to the "moving=" field in the protocol description file. 0197 * Valid values for this field are "true" or "false" (default). 0198 * 0199 * @param url the url to check 0200 * @return true if the protocol supports moving 0201 */ 0202 static bool supportsMoving(const QUrl &url); 0203 0204 /** 0205 * Returns whether the protocol can be opened using KIO::open(const QUrl&). 0206 * 0207 * This corresponds to the "opening=" field in the protocol description file. 0208 * Valid values for this field are "true" or "false" (default). 0209 * 0210 * @param url the url to check 0211 * @return true if the protocol supports opening 0212 */ 0213 static bool supportsOpening(const QUrl &url); 0214 0215 /** 0216 * Returns whether the protocol can be truncated with FileJob::truncate(KIO::filesize_t length). 0217 * 0218 * This corresponds to the "truncating=" field in the protocol description file. 0219 * Valid values for this field are "true" or "false" (default). 0220 * 0221 * @param url the url to check 0222 * @return true if the protocol supports truncating 0223 * @since 5.66 0224 */ 0225 static bool supportsTruncating(const QUrl &url); 0226 0227 /** 0228 * Returns whether the protocol can copy files/objects directly from the 0229 * filesystem itself. If not, the application will read files from the 0230 * filesystem using the file-protocol and pass the data on to the destination 0231 * protocol. 0232 * 0233 * This corresponds to the "copyFromFile=" field in the protocol description file. 0234 * Valid values for this field are "true" or "false" (default). 0235 * 0236 * @param url the url to check 0237 * @return true if the protocol can copy files from the local file system 0238 */ 0239 static bool canCopyFromFile(const QUrl &url); 0240 0241 /** 0242 * Returns whether the protocol can copy files/objects directly to the 0243 * filesystem itself. If not, the application will receive the data from 0244 * the source protocol and store it in the filesystem using the 0245 * file-protocol. 0246 * 0247 * This corresponds to the "copyToFile=" field in the protocol description file. 0248 * Valid values for this field are "true" or "false" (default). 0249 * 0250 * @param url the url to check 0251 * @return true if the protocol can copy files to the local file system 0252 */ 0253 static bool canCopyToFile(const QUrl &url); 0254 0255 /** 0256 * Returns whether the protocol can rename (i.e. move fast) files/objects 0257 * directly from the filesystem itself. If not, the application will read 0258 * files from the filesystem using the file-protocol and pass the data on 0259 * to the destination protocol. 0260 * 0261 * This corresponds to the "renameFromFile=" field in the protocol description file. 0262 * Valid values for this field are "true" or "false" (default). 0263 * 0264 * @param url the url to check 0265 * @return true if the protocol can rename/move files from the local file system 0266 */ 0267 static bool canRenameFromFile(const QUrl &url); 0268 0269 /** 0270 * Returns whether the protocol can rename (i.e. move fast) files/objects 0271 * directly to the filesystem itself. If not, the application will receive 0272 * the data from the source protocol and store it in the filesystem using the 0273 * file-protocol. 0274 * 0275 * This corresponds to the "renameToFile=" field in the protocol description file. 0276 * Valid values for this field are "true" or "false" (default). 0277 * 0278 * @param url the url to check 0279 * @return true if the protocol can rename files to the local file system 0280 */ 0281 static bool canRenameToFile(const QUrl &url); 0282 0283 /** 0284 * Returns whether the protocol can recursively delete directories by itself. 0285 * If not (the usual case) then KIO will list the directory and delete files 0286 * and empty directories one by one. 0287 * 0288 * This corresponds to the "deleteRecursive=" field in the protocol description file. 0289 * Valid values for this field are "true" or "false" (default). 0290 * 0291 * @param url the url to check 0292 * @return true if the protocol can delete non-empty directories by itself. 0293 */ 0294 static bool canDeleteRecursive(const QUrl &url); 0295 0296 /** 0297 * This setting defines the strategy to use for generating a filename, when 0298 * copying a file or directory to another directory. By default the destination 0299 * filename is made out of the filename in the source URL. However if the 0300 * KIO worker displays names that are different from the filename of the URL 0301 * (e.g. kio_fonts shows Arial for arial.ttf, or kio_trash shows foo.txt and 0302 * uses some internal URL), using Name means that the display name (UDS_NAME) 0303 * will be used to as the filename in the destination directory. 0304 * 0305 * This corresponds to the "fileNameUsedForCopying=" field in the protocol description file. 0306 * Valid values for this field are "Name" or "FromURL" (default). 0307 * 0308 * @param url the url to check 0309 * @return how to generate the filename in the destination directory when copying/moving 0310 */ 0311 static KProtocolInfo::FileNameUsedForCopying fileNameUsedForCopying(const QUrl &url); 0312 0313 /** 0314 * Returns default MIME type for this URL based on the protocol. 0315 * 0316 * This corresponds to the "defaultMimetype=" field in the protocol description file. 0317 * 0318 * @param url the url to check 0319 * @return the default MIME type of the protocol, or an empty string if unknown 0320 */ 0321 static QString defaultMimetype(const QUrl &url); 0322 0323 /** 0324 * Returns whether the protocol should be treated as a filesystem 0325 * or as a stream when reading from it. 0326 * 0327 * This corresponds to the "input=" field in the protocol description file. 0328 * Valid values for this field are "filesystem", "stream" or "none" (default). 0329 * 0330 * @param url the url to check 0331 * @return the input type of the given @p url 0332 */ 0333 static KProtocolInfo::Type inputType(const QUrl &url); 0334 0335 /** 0336 * Returns whether the protocol should be treated as a filesystem 0337 * or as a stream when writing to it. 0338 * 0339 * This corresponds to the "output=" field in the protocol description file. 0340 * Valid values for this field are "filesystem", "stream" or "none" (default). 0341 * 0342 * @param url the url to check 0343 * @return the output type of the given @p url 0344 */ 0345 static KProtocolInfo::Type outputType(const QUrl &url); 0346 0347 /** 0348 * Returns the list of fields this protocol returns when listing 0349 * The current possibilities are 0350 * Name, Type, Size, Date, AccessDate, Access, Owner, Group, Link, URL, MimeType 0351 * as well as Extra1, Extra2 etc. for extra fields (see extraFields). 0352 * 0353 * This corresponds to the "listing=" field in the protocol description file. 0354 * The supported fields should be separated with ',' in the protocol description file. 0355 * 0356 * @param url the url to check 0357 * @return a list of field names 0358 */ 0359 static QStringList listing(const QUrl &url); 0360 0361 /** 0362 * Returns whether the protocol can act as a source protocol. 0363 * 0364 * A source protocol retrieves data from or stores data to the 0365 * location specified by a URL. 0366 * A source protocol is the opposite of a filter protocol. 0367 * 0368 * The "source=" field in the protocol description file determines 0369 * whether a protocol is a source protocol or a filter protocol. 0370 * @param url the url to check 0371 * @return true if the protocol is a source of data (e.g. http), false if the 0372 * protocol is a filter (e.g. gzip) 0373 */ 0374 static bool isSourceProtocol(const QUrl &url); 0375 0376 /** 0377 * Returns which protocol handles this MIME type, if it's an archive MIME type. 0378 * For instance zip:/ handles application/x-zip. 0379 * 0380 * This is defined in the protocol description file using an entry like 0381 * "archiveMimetype=application/x-zip" 0382 * 0383 * @param mimeType the MIME type to check 0384 * @return the protocol that can handle this archive MIME type, for instance "zip". 0385 */ 0386 static QString protocolForArchiveMimetype(const QString &mimeType); 0387 0388 /*=============================== OTHERS ====================================*/ 0389 0390 /** 0391 * Force a reload of the general config file of 0392 * KIO workers ( kioslaverc). 0393 */ 0394 static void reparseConfiguration(); 0395 0396 /** 0397 * Returns the charset to use for the specified @ref url. 0398 * 0399 */ 0400 static QString charsetFor(const QUrl &url); 0401 0402 /** 0403 * @brief Returns whether the protocol suppports KIO/POSIX permissions handling. 0404 * 0405 * When this is false the Permissions properties tab may be hidden, for example. The protocol may still support 0406 * permission control through other means, specific to the individual KIO worker. 0407 * 0408 * @param url the url to check 0409 * @return whether the protocol supports permissions 0410 * @since 5.98 0411 */ 0412 static bool supportsPermissions(const QUrl &url); 0413 0414 private: 0415 friend class KIO::WorkerConfigPrivate; 0416 0417 /** 0418 * @internal 0419 * (Shared with WorkerConfig) 0420 */ 0421 KIOCORE_NO_EXPORT static QMap<QString, QString> entryMap(const QString &group); 0422 }; 0423 #endif