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