Warning, file /frameworks/kio/src/core/statjob.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org>
0004     SPDX-FileCopyrightText: 2000-2013 David Faure <faure@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KIO_STATJOB_H
0010 #define KIO_STATJOB_H
0011 
0012 #include "global.h"
0013 #include "simplejob.h"
0014 #include <kio/udsentry.h>
0015 
0016 namespace KIO
0017 {
0018 class StatJobPrivate;
0019 /**
0020  * @class KIO::StatJob statjob.h <KIO/StatJob>
0021  *
0022  * A KIO job that retrieves information about a file or directory.
0023  * @see KIO::stat()
0024  */
0025 class KIOCORE_EXPORT StatJob : public SimpleJob
0026 {
0027     Q_OBJECT
0028 
0029 public:
0030     enum StatSide {
0031         SourceSide,
0032         DestinationSide,
0033     };
0034 
0035     ~StatJob() override;
0036 
0037     /**
0038      * A stat() can have two meanings. Either we want to read from this URL,
0039      * or to check if we can write to it. First case is "source", second is "dest".
0040      * It is necessary to know what the StatJob is for, to tune the KIO worker's behavior
0041      * (e.g. with FTP).
0042      * By default it is SourceSide.
0043      * @param side SourceSide or DestinationSide
0044      */
0045     void setSide(StatSide side);
0046 
0047 #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0)
0048     /**
0049      * A stat() can have two meanings. Either we want to read from this URL,
0050      * or to check if we can write to it. First case is "source", second is "dest".
0051      * It is necessary to know what the StatJob is for, to tune the KIO worker's behavior
0052      * (e.g. with FTP).
0053      * @param source true for "source" mode, false for "dest" mode
0054      * @deprecated Since 4.0, use setSide(StatSide side).
0055      */
0056     KIOCORE_DEPRECATED_VERSION(4, 0, "Use StatJob::setSide(StatSide)")
0057     void setSide(bool source);
0058 #endif
0059 
0060     /**
0061      * Selects the level of @p details we want.
0062      * @since 5.69
0063      */
0064     void setDetails(KIO::StatDetails details);
0065 
0066 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 69)
0067     /**
0068      * @brief @see setDetails(KIO::StatDetails details)
0069      * Needed until setDetails(short int details) is removed
0070      */
0071     void setDetails(KIO::StatDetail detail);
0072 
0073     /**
0074      * Selects the level of @p details we want.
0075      * By default this is 2 (all details wanted, including modification time, size, etc.),
0076      * setDetails(1) is used when deleting: we don't need all the information if it takes
0077      * too much time, no need to follow symlinks etc.
0078      * setDetails(0) is used for very simple probing: we'll only get the answer
0079      * "it's a file or a directory, or it doesn't exist". This is used by KRun.
0080      * @param details 2 for all details, 1 for simple, 0 for very simple
0081      * @deprecated since 5.69, use setDetails(KIO::StatDetails)
0082      */
0083     KIOCORE_DEPRECATED_VERSION(5, 69, "Use setDetails(KIO::statDetails)")
0084     void setDetails(short int details);
0085 #endif
0086 
0087     /**
0088      * @brief Result of the stat operation.
0089      * Call this in the slot connected to result,
0090      * and only after making sure no error happened.
0091      * @return the result of the stat
0092      */
0093     const UDSEntry &statResult() const;
0094 
0095     /**
0096      * @brief most local URL
0097      *
0098      * Since this method depends on UDSEntry::UDS_LOCAL_PATH having been previously set
0099      * by a KIO worker, ideally you should first check that the protocol Class of the URL
0100      * being stat'ed is ":local" before creating the StatJob at all. Typically only ":local"
0101      * KIO workers set UDS_LOCAL_PATH. See KProtocolInfo::protocolClass().
0102      *
0103      * Call this in a slot connected to the result signal, and only after making sure no error
0104      * happened.
0105      *
0106      * @return the most local URL for the URL we were stat'ing
0107      *
0108      * Sample usage:
0109      *
0110      * @code
0111      * auto *job = KIO::mostLocalUrl("desktop:/foo");
0112      * job->uiDelegate()->setWindow(this);
0113      * connect(job, &KJob::result, this, &MyClass::slotMostLocalUrlResult);
0114      * [...]
0115      * // and in slotMostLocalUrlResult(KJob *job)
0116      * if (job->error()) {
0117      *    [...] // doesn't exist
0118      * } else {
0119      *    const QUrl localUrl = job->mostLocalUrl();
0120      *    // localUrl = file:///$HOME/Desktop/foo
0121      *    [...]
0122      * }
0123      * @endcode
0124      *
0125      * \since 4.4
0126      */
0127     QUrl mostLocalUrl() const;
0128 
0129 Q_SIGNALS:
0130     /**
0131      * Signals a redirection.
0132      * Use to update the URL shown to the user.
0133      * The redirection itself is handled internally.
0134      * @param job the job that is redirected
0135      * @param url the new url
0136      */
0137     void redirection(KIO::Job *job, const QUrl &url);
0138 
0139     /**
0140      * Signals a permanent redirection.
0141      * The redirection itself is handled internally.
0142      * @param job the job that is redirected
0143      * @param fromUrl the original URL
0144      * @param toUrl the new URL
0145      */
0146     void permanentRedirection(KIO::Job *job, const QUrl &fromUrl, const QUrl &toUrl);
0147 
0148 protected Q_SLOTS:
0149     void slotFinished() override;
0150 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 101) // override no longer needed
0151     void slotMetaData(const KIO::MetaData &_metaData) override;
0152 #endif
0153 
0154 protected:
0155     KIOCORE_NO_EXPORT explicit StatJob(StatJobPrivate &dd);
0156 
0157 private:
0158     Q_DECLARE_PRIVATE(StatJob)
0159     friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags);
0160 };
0161 
0162 /**
0163  * Find all details for one file or directory.
0164  *
0165  * @param url the URL of the file
0166  * @param flags Can be HideProgressInfo here
0167  * @return the job handling the operation.
0168  */
0169 KIOCORE_EXPORT StatJob *stat(const QUrl &url, JobFlags flags = DefaultFlags);
0170 /**
0171  * Find all details for one file or directory.
0172  * This version of the call includes two additional booleans, @p sideIsSource and @p details.
0173  *
0174  * @param url the URL of the file
0175  * @param side is SourceSide when stating a source file (we will do a get on it if
0176  * the stat works) and DestinationSide when stating a destination file (target of a copy).
0177  * The reason for this parameter is that in some cases the KIO worker might not
0178  * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
0179  * has issues with case-sensitivity on some systems).
0180  * When the worker can't reliably determine the existence of a file, it will:
0181  * @li be optimistic if SourceSide, i.e. it will assume the file exists,
0182  * and if it doesn't this will appear when actually trying to download it
0183  * @li be pessimistic if DestinationSide, i.e. it will assume the file
0184  * doesn't exist, to prevent showing "about to overwrite" errors to the user.
0185  * If you simply want to check for existence without downloading/uploading afterwards,
0186  * then you should use DestinationSide.
0187  *
0188  * @param details selects the level of details we want.
0189  * You should minimize the detail level for better performance.
0190  * @param flags Can be HideProgressInfo here
0191  * @return the job handling the operation.
0192  * @since 5.69
0193  */
0194 KIOCORE_EXPORT StatJob *
0195 statDetails(const QUrl &url, KIO::StatJob::StatSide side, KIO::StatDetails details = KIO::StatDefaultDetails, JobFlags flags = DefaultFlags);
0196 
0197 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 69)
0198 /**
0199  * Find all details for one file or directory.
0200  * This version of the call includes two additional booleans, @p sideIsSource and @p details.
0201  *
0202  * @param url the URL of the file
0203  * @param side is SourceSide when stating a source file (we will do a get on it if
0204  * the stat works) and DestinationSide when stating a destination file (target of a copy).
0205  * The reason for this parameter is that in some cases the KIO worker might not
0206  * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
0207  * has issues with case-sensitivity on some systems).
0208  * When the worker can't reliably determine the existence of a file, it will:
0209  * @li be optimistic if SourceSide, i.e. it will assume the file exists,
0210  * and if it doesn't this will appear when actually trying to download it
0211  * @li be pessimistic if DestinationSide, i.e. it will assume the file
0212  * doesn't exist, to prevent showing "about to overwrite" errors to the user.
0213  * If you simply want to check for existence without downloading/uploading afterwards,
0214  * then you should use DestinationSide.
0215  *
0216  * @param details selects the level of details we want.
0217  * By default this is 2 (all details wanted, including modification time, size, etc.),
0218  * setDetails(1) is used when deleting: we don't need all the information if it takes
0219  * too much time, no need to follow symlinks etc.
0220  * setDetails(0) is used for very simple probing: we'll only get the answer
0221  * "it's a file or a directory or a symlink, or it doesn't exist". This is used by KRun and DeleteJob.
0222  * @param flags Can be HideProgressInfo here
0223  * @return the job handling the operation.
0224  * @deprecated since 5.69, use statDetails(const QUrl &, KIO::StatJob::StatSide, KIO::StatDetails, JobFlags)
0225  */
0226 KIOCORE_EXPORT
0227 KIOCORE_DEPRECATED_VERSION(5, 69, "Use KIO::statDetails(const QUrl &, KIO::StatJob::StatSide, KIO::StatDetails, JobFlags)")
0228 StatJob *stat(const QUrl &url, KIO::StatJob::StatSide side, short int details, JobFlags flags = DefaultFlags);
0229 #endif
0230 
0231 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 69)
0232 /**
0233  * Converts the legacy stat details int to a StatDetail Flag
0234  * @param details @see setDetails()
0235  * @since 5.69
0236  * @deprecated since 5.69, use directly KIO::StatDetails
0237  */
0238 KIOCORE_EXPORT
0239 KIOCORE_DEPRECATED_VERSION(5, 69, "Use directly KIO::StatDetails")
0240 KIO::StatDetails detailsToStatDetails(int details);
0241 #endif
0242 
0243 #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0)
0244 /**
0245  * Find all details for one file or directory.
0246  * This version of the call includes two additional booleans, @p sideIsSource and @p details.
0247  *
0248  * @param url the URL of the file
0249  * @param sideIsSource is true when stating a source file (we will do a get on it if
0250  * the stat works) and false when stating a destination file (target of a copy).
0251  * The reason for this parameter is that in some cases the KIO worker might not
0252  * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
0253  * has issues with case-sensitivity on some systems).
0254  * When the worker can't reliably determine the existence of a file, it will:
0255  * @li be optimistic if sideIsSource=true, i.e. it will assume the file exists,
0256  * and if it doesn't this will appear when actually trying to download it
0257  * @li be pessimistic if sideIsSource=false, i.e. it will assume the file
0258  * doesn't exist, to prevent showing "about to overwrite" errors to the user.
0259  * If you simply want to check for existence without downloading/uploading afterwards,
0260  * then you should use sideIsSource=false.
0261  *
0262  * @param details selects the level of details we want.
0263  * By default this is 2 (all details wanted, including modification time, size, etc.),
0264  * setDetails(1) is used when deleting: we don't need all the information if it takes
0265  * too much time, no need to follow symlinks etc.
0266  * setDetails(0) is used for very simple probing: we'll only get the answer
0267  * "it's a file or a directory, or it doesn't exist". This is used by KRun.
0268  * @param flags Can be HideProgressInfo here
0269  * @return the job handling the operation.
0270  * @deprecated Since 4.0, use stat(const QUrl &, KIO::StatJob::StatSide, short int, JobFlags)
0271  */
0272 KIOCORE_EXPORT
0273 KIOCORE_DEPRECATED_VERSION(4, 0, "Use KIO::stat(const QUrl &, KIO::StatJob::StatSide, short int, JobFlags)")
0274 StatJob *stat(const QUrl &url, bool sideIsSource, short int details, JobFlags flags = DefaultFlags);
0275 #endif
0276 
0277 /**
0278  * Tries to map a local URL for the given URL, using a KIO job. This only makes sense for
0279  * protocols that have Class ":local" (such protocols most likely have KIO workers that set
0280  * UDSEntry::UDS_LOCAL_PATH); ideally you should check the URL protocol Class before creating
0281  * a StatJob. See KProtocolInfo::protocolClass().
0282  *
0283  * Starts a (stat) job for determining the "most local URL" for a given URL.
0284  * Retrieve the result with StatJob::mostLocalUrl in the result slot.
0285  *
0286  * @param url The URL we are stat'ing.
0287  *
0288  * @since 4.4
0289  *
0290  * Sample usage:
0291  *
0292  * Here the KIO worker name is "foo", which for example could be:
0293  *  - "desktop", "fonts", "kdeconnect", these have class ":local"
0294  *  - "ftp", "sftp", "smb", these have class ":internet"
0295  *
0296  * @code
0297  *
0298  * QUrl url(QStringLiteral("foo://bar/");
0299  * if (url.isLocalFile()) { // If it's a local URL, there is no need to stat
0300  *    [...]
0301  * } else if (KProtocolInfo::protocolClass(url.scheme()) == QLatin1String(":local")) {
0302  *     // Not a local URL, but if the protocol class is ":local", we may be able to stat
0303  *     // and get a "most local URL"
0304  *     auto *job = KIO::mostLocalUrl(url);
0305  *     job->uiDelegate()->setWindow(this);
0306  *     connect(job, &KJob::result, this, &MyClass::slotMostLocalUrlResult);
0307  *     [...]
0308  *     // And in slotMostLocalUrlResult(KJob *job)
0309  *     if (job->error()) {
0310  *         [...] // Doesn't exist, ideally show an error message
0311  *     } else {
0312  *         const QUrl localUrl = job->mostLocalUrl();
0313  *         // localUrl = file:///local/path/to/bar/
0314  *         [...]
0315  *     }
0316  * }
0317  *
0318  * @endcode
0319  *
0320  */
0321 KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags = DefaultFlags);
0322 
0323 }
0324 
0325 #endif