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

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