1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org>
4 SPDX-FileCopyrightText: 2000-2013 David Faure <faure@kde.org>
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
16namespace KIO
17{
18class StatJobPrivate;
19/*!
20 * \class KIO::StatJob
21 * \inheaderfile KIO/StatJob
22 * \inmodule KIOCore
23 *
24 * \brief A KIO job that retrieves information about a file or directory.
25 *
26 * \sa KIO::stat()
27 */
28class KIOCORE_EXPORT StatJob : public SimpleJob
29{
30 Q_OBJECT
31
32public:
33 /*!
34 * \value SourceSide
35 * \value DestinationSide
36 */
37 enum StatSide {
38 SourceSide,
39 DestinationSide,
40 };
41
42 ~StatJob() override;
43
44 /*!
45 * A stat() can have two meanings. Either we want to read from this URL,
46 * or to check if we can write to it. First case is "source", second is "dest".
47 * It is necessary to know what the StatJob is for, to tune the KIO worker's behavior
48 * (e.g. with FTP).
49 *
50 * By default it is SourceSide.
51 *
52 * \a side SourceSide or DestinationSide
53 */
54 void setSide(StatSide side);
55
56 /*!
57 * Selects the level of \a details we want.
58 * \since 5.69
59 */
60 void setDetails(KIO::StatDetails details);
61
62 /*!
63 * \brief Result of the stat operation.
64 *
65 * Call this in the slot connected to result,
66 * and only after making sure no error happened.
67 *
68 * Returns the result of the stat
69 */
70 const UDSEntry &statResult() const;
71
72 /*!
73 * \brief most local URL
74 *
75 * Since this method depends on UDSEntry::UDS_LOCAL_PATH having been previously set
76 * by a KIO worker, ideally you should first check that the protocol Class of the URL
77 * being stat'ed is ":local" before creating the StatJob at all. Typically only ":local"
78 * KIO workers set UDS_LOCAL_PATH. See KProtocolInfo::protocolClass().
79 *
80 * Call this in a slot connected to the result signal, and only after making sure no error
81 * happened.
82 *
83 * Returns the most local URL for the URL we were stat'ing
84 *
85 * Sample usage:
86 *
87 * \code
88 * auto *job = KIO::mostLocalUrl("desktop:/foo");
89 * job->uiDelegate()->setWindow(this);
90 * connect(job, &KJob::result, this, &MyClass::slotMostLocalUrlResult);
91 * [...]
92 * // and in slotMostLocalUrlResult(KJob *job)
93 * if (job->error()) {
94 * [...] // doesn't exist
95 * } else {
96 * const QUrl localUrl = job->mostLocalUrl();
97 * // localUrl = file:///$HOME/Desktop/foo
98 * [...]
99 * }
100 * \endcode
101 *
102 * \since 4.4
103 */
104 QUrl mostLocalUrl() const;
105
106Q_SIGNALS:
107 /*!
108 * Signals a redirection.
109 *
110 * Use to update the URL shown to the user.
111 * The redirection itself is handled internally.
112 *
113 * \a job the job that is redirected
114 *
115 * \a url the new url
116 */
117 void redirection(KIO::Job *job, const QUrl &url);
118
119 /*!
120 * Signals a permanent redirection.
121 *
122 * The redirection itself is handled internally.
123 *
124 * \a job the job that is redirected
125 *
126 * \a fromUrl the original URL
127 *
128 * \a toUrl the new URL
129 */
130 void permanentRedirection(KIO::Job *job, const QUrl &fromUrl, const QUrl &toUrl);
131
132protected Q_SLOTS:
133 void slotFinished() override;
134
135protected:
136 KIOCORE_NO_EXPORT explicit StatJob(StatJobPrivate &dd);
137
138private:
139 Q_DECLARE_PRIVATE(StatJob)
140 friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags);
141};
142
143/*!
144 * \relates KIO::StatJob
145 *
146 * Find all details for one file or directory.
147 *
148 * \a url the URL of the file
149 *
150 * \a flags Can be HideProgressInfo here
151 *
152 * Returns the job handling the operation.
153 */
154KIOCORE_EXPORT StatJob *stat(const QUrl &url, JobFlags flags = DefaultFlags);
155
156/*!
157 * \relates KIO::StatJob
158 *
159 * Find all details for one file or directory.
160 *
161 * This version includes two additional parameters, \a side and \a details.
162 *
163 * \a url the URL of the file
164 *
165 * \a side is SourceSide when stating a source file (we will do a get on it if
166 * the stat works) and DestinationSide when stating a destination file (target of a copy).
167 * The reason for this parameter is that in some cases the KIO worker might not
168 * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP
169 * has issues with case-sensitivity on some systems).
170 * When the worker can't reliably determine the existence of a file, it will:
171 * \list
172 * \li be optimistic if SourceSide, i.e. it will assume the file exists,
173 * and if it doesn't this will appear when actually trying to download it
174 * \li be pessimistic if DestinationSide, i.e. it will assume the file
175 * doesn't exist, to prevent showing "about to overwrite" errors to the user.
176 * If you simply want to check for existence without downloading/uploading afterwards,
177 * then you should use DestinationSide.
178 * \endlist
179 *
180 * \a details selects the level of details we want.
181 * You should minimize the detail level for better performance.
182 *
183 * \a flags Can be HideProgressInfo here
184 *
185 * Returns the job handling the operation.
186 *
187 * \since 6.0
188 */
189KIOCORE_EXPORT StatJob *stat(const QUrl &url, KIO::StatJob::StatSide side, KIO::StatDetails details = KIO::StatDefaultDetails, JobFlags flags = DefaultFlags);
190
191/*!
192 * \relates KIO::StatJob
193 *
194 * Tries to map a local URL for the given URL, using a KIO job. This only makes sense for
195 * protocols that have Class ":local" (such protocols most likely have KIO workers that set
196 * UDSEntry::UDS_LOCAL_PATH); ideally you should check the URL protocol Class before creating
197 * a StatJob. See KProtocolInfo::protocolClass().
198 *
199 * Starts a (stat) job for determining the "most local URL" for a given URL.
200 * Retrieve the result with StatJob::mostLocalUrl in the result slot.
201 *
202 * \a url The URL we are stat'ing.
203 *
204 * Sample usage:
205 *
206 * Here the KIO worker name is "foo", which for example could be:
207 * \list
208 * \li "desktop", "fonts", "kdeconnect", these have class ":local"
209 * \li "ftp", "sftp", "smb", these have class ":internet"
210 * \endlist
211 *
212 * \code
213 * QUrl url(QStringLiteral("foo://bar/");
214 * if (url.isLocalFile()) { // If it's a local URL, there is no need to stat
215 * [...]
216 * } else if (KProtocolInfo::protocolClass(url.scheme()) == QLatin1String(":local")) {
217 * // Not a local URL, but if the protocol class is ":local", we may be able to stat
218 * // and get a "most local URL"
219 * auto *job = KIO::mostLocalUrl(url);
220 * job->uiDelegate()->setWindow(this);
221 * connect(job, &KJob::result, this, &MyClass::slotMostLocalUrlResult);
222 * [...]
223 * // And in slotMostLocalUrlResult(KJob *job)
224 * if (job->error()) {
225 * [...] // Doesn't exist, ideally show an error message
226 * } else {
227 * const QUrl localUrl = job->mostLocalUrl();
228 * // localUrl = file:///local/path/to/bar/
229 * [...]
230 * }
231 * }
232 * \endcode
233 *
234 */
235KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags = DefaultFlags);
236
237}
238
239#endif
240

source code of kio/src/core/statjob.h