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