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 | |
16 | namespace KIO |
17 | { |
18 | class 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 | */ |
28 | class KIOCORE_EXPORT StatJob : public SimpleJob |
29 | { |
30 | Q_OBJECT |
31 | |
32 | public: |
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 | |
106 | Q_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 | |
132 | protected Q_SLOTS: |
133 | void slotFinished() override; |
134 | |
135 | protected: |
136 | KIOCORE_NO_EXPORT explicit StatJob(StatJobPrivate &dd); |
137 | |
138 | private: |
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 | */ |
154 | KIOCORE_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 | */ |
189 | KIOCORE_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 | */ |
235 | KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags = DefaultFlags); |
236 | |
237 | } |
238 | |
239 | #endif |
240 | |