KIO

statjob.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Stephan Kulow <[email protected]>
4  SPDX-FileCopyrightText: 2000-2013 David Faure <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KIO_STATJOB_H
10 #define KIO_STATJOB_H
11 
12 #include "global.h"
13 #include "simplejob.h"
14 #include <kio/udsentry.h>
15 
16 namespace KIO
17 {
18 class StatJobPrivate;
19 /**
20  * @class KIO::StatJob statjob.h <KIO/StatJob>
21  *
22  * A KIO job that retrieves information about a file or directory.
23  * @see KIO::stat()
24  */
25 class KIOCORE_EXPORT StatJob : public SimpleJob
26 {
27  Q_OBJECT
28 
29 public:
30  enum StatSide {
31  SourceSide,
32  DestinationSide,
33  };
34 
35  ~StatJob() override;
36 
37  /**
38  * A stat() can have two meanings. Either we want to read from this URL,
39  * or to check if we can write to it. First case is "source", second is "dest".
40  * It is necessary to know what the StatJob is for, to tune the KIO worker's behavior
41  * (e.g. with FTP).
42  * By default it is SourceSide.
43  * @param side SourceSide or DestinationSide
44  */
45  void setSide(StatSide side);
46 
47 #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0)
48  /**
49  * A stat() can have two meanings. Either we want to read from this URL,
50  * or to check if we can write to it. First case is "source", second is "dest".
51  * It is necessary to know what the StatJob is for, to tune the KIO worker's behavior
52  * (e.g. with FTP).
53  * @param source true for "source" mode, false for "dest" mode
54  * @deprecated Since 4.0, use setSide(StatSide side).
55  */
56  KIOCORE_DEPRECATED_VERSION(4, 0, "Use StatJob::setSide(StatSide)")
57  void setSide(bool source);
58 #endif
59 
60  /**
61  * Selects the level of @p details we want.
62  * @since 5.69
63  */
64  void setDetails(KIO::StatDetails details);
65 
66 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 69)
67  /**
68  * @brief @see setDetails(KIO::StatDetails details)
69  * Needed until setDetails(short int details) is removed
70  */
71  void setDetails(KIO::StatDetail detail);
72 
73  /**
74  * Selects the level of @p details we want.
75  * By default this is 2 (all details wanted, including modification time, size, etc.),
76  * setDetails(1) is used when deleting: we don't need all the information if it takes
77  * too much time, no need to follow symlinks etc.
78  * setDetails(0) is used for very simple probing: we'll only get the answer
79  * "it's a file or a directory, or it doesn't exist". This is used by KRun.
80  * @param details 2 for all details, 1 for simple, 0 for very simple
81  * @deprecated since 5.69, use setDetails(KIO::StatDetails)
82  */
83  KIOCORE_DEPRECATED_VERSION(5, 69, "Use setDetails(KIO::statDetails)")
84  void setDetails(short int details);
85 #endif
86 
87  /**
88  * @brief Result of the stat operation.
89  * Call this in the slot connected to result,
90  * and only after making sure no error happened.
91  * @return the result of the stat
92  */
93  const UDSEntry &statResult() const;
94 
95  /**
96  * @brief most local URL
97  *
98  * Since this method depends on UDSEntry::UDS_LOCAL_PATH having been previously set
99  * by a KIO worker, ideally you should first check that the protocol Class of the URL
100  * being stat'ed is ":local" before creating the StatJob at all. Typically only ":local"
101  * KIO workers set UDS_LOCAL_PATH. See KProtocolInfo::protocolClass().
102  *
103  * Call this in a slot connected to the result signal, and only after making sure no error
104  * happened.
105  *
106  * @return the most local URL for the URL we were stat'ing
107  *
108  * Sample usage:
109  *
110  * @code
111  * auto *job = KIO::mostLocalUrl("desktop:/foo");
112  * job->uiDelegate()->setWindow(this);
113  * connect(job, &KJob::result, this, &MyClass::slotMostLocalUrlResult);
114  * [...]
115  * // and in slotMostLocalUrlResult(KJob *job)
116  * if (job->error()) {
117  * [...] // doesn't exist
118  * } else {
119  * const QUrl localUrl = job->mostLocalUrl();
120  * // localUrl = file:///$HOME/Desktop/foo
121  * [...]
122  * }
123  * @endcode
124  *
125  * \since 4.4
126  */
127  QUrl mostLocalUrl() const;
128 
129 Q_SIGNALS:
130  /**
131  * Signals a redirection.
132  * Use to update the URL shown to the user.
133  * The redirection itself is handled internally.
134  * @param job the job that is redirected
135  * @param url the new url
136  */
137  void redirection(KIO::Job *job, const QUrl &url);
138 
139  /**
140  * Signals a permanent redirection.
141  * The redirection itself is handled internally.
142  * @param job the job that is redirected
143  * @param fromUrl the original URL
144  * @param toUrl the new URL
145  */
146  void permanentRedirection(KIO::Job *job, const QUrl &fromUrl, const QUrl &toUrl);
147 
148 protected Q_SLOTS:
149  void slotFinished() override;
150 #if KIOCORE_BUILD_DEPRECATED_SINCE(5, 101) // override no longer needed
151  void slotMetaData(const KIO::MetaData &_metaData) override;
152 #endif
153 
154 protected:
155  KIOCORE_NO_EXPORT explicit StatJob(StatJobPrivate &dd);
156 
157 private:
158  Q_DECLARE_PRIVATE(StatJob)
159  friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags);
160 };
161 
162 /**
163  * Find all details for one file or directory.
164  *
165  * @param url the URL of the file
166  * @param flags Can be HideProgressInfo here
167  * @return the job handling the operation.
168  */
169 KIOCORE_EXPORT StatJob *stat(const QUrl &url, JobFlags flags = DefaultFlags);
170 /**
171  * Find all details for one file or directory.
172  * This version of the call includes two additional booleans, @p sideIsSource and @p details.
173  *
174  * @param url the URL of the file
175  * @param side is SourceSide when stating a source file (we will do a get on it if
176  * the stat works) and DestinationSide when stating a destination file (target of a copy).
177  * The reason for this parameter is that in some cases the KIO worker might not
178  * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
179  * has issues with case-sensitivity on some systems).
180  * When the worker can't reliably determine the existence of a file, it will:
181  * @li be optimistic if SourceSide, i.e. it will assume the file exists,
182  * and if it doesn't this will appear when actually trying to download it
183  * @li be pessimistic if DestinationSide, i.e. it will assume the file
184  * doesn't exist, to prevent showing "about to overwrite" errors to the user.
185  * If you simply want to check for existence without downloading/uploading afterwards,
186  * then you should use DestinationSide.
187  *
188  * @param details selects the level of details we want.
189  * You should minimize the detail level for better performance.
190  * @param flags Can be HideProgressInfo here
191  * @return the job handling the operation.
192  * @since 5.69
193  */
194 KIOCORE_EXPORT StatJob *
195 statDetails(const QUrl &url, KIO::StatJob::StatSide side, KIO::StatDetails details = KIO::StatDefaultDetails, JobFlags flags = DefaultFlags);
196 
197 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 69)
198 /**
199  * Find all details for one file or directory.
200  * This version of the call includes two additional booleans, @p sideIsSource and @p details.
201  *
202  * @param url the URL of the file
203  * @param side is SourceSide when stating a source file (we will do a get on it if
204  * the stat works) and DestinationSide when stating a destination file (target of a copy).
205  * The reason for this parameter is that in some cases the KIO worker might not
206  * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
207  * has issues with case-sensitivity on some systems).
208  * When the worker can't reliably determine the existence of a file, it will:
209  * @li be optimistic if SourceSide, i.e. it will assume the file exists,
210  * and if it doesn't this will appear when actually trying to download it
211  * @li be pessimistic if DestinationSide, i.e. it will assume the file
212  * doesn't exist, to prevent showing "about to overwrite" errors to the user.
213  * If you simply want to check for existence without downloading/uploading afterwards,
214  * then you should use DestinationSide.
215  *
216  * @param details selects the level of details we want.
217  * By default this is 2 (all details wanted, including modification time, size, etc.),
218  * setDetails(1) is used when deleting: we don't need all the information if it takes
219  * too much time, no need to follow symlinks etc.
220  * setDetails(0) is used for very simple probing: we'll only get the answer
221  * "it's a file or a directory or a symlink, or it doesn't exist". This is used by KRun and DeleteJob.
222  * @param flags Can be HideProgressInfo here
223  * @return the job handling the operation.
224  * @deprecated since 5.69, use statDetails(const QUrl &, KIO::StatJob::StatSide, KIO::StatDetails, JobFlags)
225  */
226 KIOCORE_EXPORT
227 KIOCORE_DEPRECATED_VERSION(5, 69, "Use KIO::statDetails(const QUrl &, KIO::StatJob::StatSide, KIO::StatDetails, JobFlags)")
228 StatJob *stat(const QUrl &url, KIO::StatJob::StatSide side, short int details, JobFlags flags = DefaultFlags);
229 #endif
230 
231 #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 69)
232 /**
233  * Converts the legacy stat details int to a StatDetail Flag
234  * @param details @see setDetails()
235  * @since 5.69
236  * @deprecated since 5.69, use directly KIO::StatDetails
237  */
238 KIOCORE_EXPORT
239 KIOCORE_DEPRECATED_VERSION(5, 69, "Use directly KIO::StatDetails")
240 KIO::StatDetails detailsToStatDetails(int details);
241 #endif
242 
243 #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0)
244 /**
245  * Find all details for one file or directory.
246  * This version of the call includes two additional booleans, @p sideIsSource and @p details.
247  *
248  * @param url the URL of the file
249  * @param sideIsSource is true when stating a source file (we will do a get on it if
250  * the stat works) and false when stating a destination file (target of a copy).
251  * The reason for this parameter is that in some cases the KIO worker might not
252  * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
253  * has issues with case-sensitivity on some systems).
254  * When the worker can't reliably determine the existence of a file, it will:
255  * @li be optimistic if sideIsSource=true, i.e. it will assume the file exists,
256  * and if it doesn't this will appear when actually trying to download it
257  * @li be pessimistic if sideIsSource=false, i.e. it will assume the file
258  * doesn't exist, to prevent showing "about to overwrite" errors to the user.
259  * If you simply want to check for existence without downloading/uploading afterwards,
260  * then you should use sideIsSource=false.
261  *
262  * @param details selects the level of details we want.
263  * By default this is 2 (all details wanted, including modification time, size, etc.),
264  * setDetails(1) is used when deleting: we don't need all the information if it takes
265  * too much time, no need to follow symlinks etc.
266  * setDetails(0) is used for very simple probing: we'll only get the answer
267  * "it's a file or a directory, or it doesn't exist". This is used by KRun.
268  * @param flags Can be HideProgressInfo here
269  * @return the job handling the operation.
270  * @deprecated Since 4.0, use stat(const QUrl &, KIO::StatJob::StatSide, short int, JobFlags)
271  */
272 KIOCORE_EXPORT
273 KIOCORE_DEPRECATED_VERSION(4, 0, "Use KIO::stat(const QUrl &, KIO::StatJob::StatSide, short int, JobFlags)")
274 StatJob *stat(const QUrl &url, bool sideIsSource, short int details, JobFlags flags = DefaultFlags);
275 #endif
276 
277 /**
278  * Tries to map a local URL for the given URL, using a KIO job. This only makes sense for
279  * protocols that have Class ":local" (such protocols most likely have KIO workers that set
280  * UDSEntry::UDS_LOCAL_PATH); ideally you should check the URL protocol Class before creating
281  * a StatJob. See KProtocolInfo::protocolClass().
282  *
283  * Starts a (stat) job for determining the "most local URL" for a given URL.
284  * Retrieve the result with StatJob::mostLocalUrl in the result slot.
285  *
286  * @param url The URL we are stat'ing.
287  *
288  * @since 4.4
289  *
290  * Sample usage:
291  *
292  * Here the KIO worker name is "foo", which for example could be:
293  * - "desktop", "fonts", "kdeconnect", these have class ":local"
294  * - "ftp", "sftp", "smb", these have class ":internet"
295  *
296  * @code
297  *
298  * QUrl url(QStringLiteral("foo://bar/");
299  * if (url.isLocalFile()) { // If it's a local URL, there is no need to stat
300  * [...]
301  * } else if (KProtocolInfo::protocolClass(url.scheme()) == QLatin1String(":local")) {
302  * // Not a local URL, but if the protocol class is ":local", we may be able to stat
303  * // and get a "most local URL"
304  * auto *job = KIO::mostLocalUrl(url);
305  * job->uiDelegate()->setWindow(this);
306  * connect(job, &KJob::result, this, &MyClass::slotMostLocalUrlResult);
307  * [...]
308  * // And in slotMostLocalUrlResult(KJob *job)
309  * if (job->error()) {
310  * [...] // Doesn't exist, ideally show an error message
311  * } else {
312  * const QUrl localUrl = job->mostLocalUrl();
313  * // localUrl = file:///local/path/to/bar/
314  * [...]
315  * }
316  * }
317  *
318  * @endcode
319  *
320  */
321 KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags = DefaultFlags);
322 
323 }
324 
325 #endif
KIOCORE_EXPORT KIO::StatDetails detailsToStatDetails(int details)
Converts the legacy stat details int to a StatDetail Flag.
Definition: statjob.cpp:99
@ DefaultFlags
Show the progress info GUI, no Resume and no Overwrite.
Definition: job_base.h:270
StatDetail
Describes the fields that a stat command will retrieve.
Definition: global.h:365
KIOCORE_EXPORT StatJob * statDetails(const QUrl &url, KIO::StatJob::StatSide side, KIO::StatDetails details=KIO::StatDefaultDetails, JobFlags flags=DefaultFlags)
Find all details for one file or directory.
Definition: statjob.cpp:263
A namespace for KIO globals.
KIOCORE_EXPORT StatJob * stat(const QUrl &url, JobFlags flags=DefaultFlags)
Find all details for one file or directory.
Definition: statjob.cpp:215
KIOCORE_EXPORT StatJob * mostLocalUrl(const QUrl &url, JobFlags flags=DefaultFlags)
Tries to map a local URL for the given URL, using a KIO job.
Definition: statjob.cpp:241
@ StatDefaultDetails
Default StatDetail flag when creating a StatJob.
Definition: global.h:389
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 03:53:24 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.