Changeset View
Standalone View
src/core/statjob.h
Show All 15 Lines | 1 | /* This file is part of the KDE libraries | |||
---|---|---|---|---|---|
16 | along with this library; see the file COPYING.LIB. If not, write to | 16 | along with this library; see the file COPYING.LIB. If not, write to | ||
17 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, | 17 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, | ||
18 | Boston, MA 02110-1301, USA. | 18 | Boston, MA 02110-1301, USA. | ||
19 | */ | 19 | */ | ||
20 | 20 | | |||
21 | #ifndef KIO_STATJOB_H | 21 | #ifndef KIO_STATJOB_H | ||
22 | #define KIO_STATJOB_H | 22 | #define KIO_STATJOB_H | ||
23 | 23 | | |||
24 | #include "global.h" | ||||
24 | #include "simplejob.h" | 25 | #include "simplejob.h" | ||
25 | #include <kio/udsentry.h> | 26 | #include <kio/udsentry.h> | ||
26 | 27 | | |||
27 | namespace KIO | 28 | namespace KIO | ||
28 | { | 29 | { | ||
29 | 30 | | |||
30 | class StatJobPrivate; | 31 | class StatJobPrivate; | ||
31 | /** | 32 | /** | ||
Show All 10 Lines | |||||
42 | public: | 43 | public: | ||
43 | enum StatSide { | 44 | enum StatSide { | ||
44 | SourceSide, | 45 | SourceSide, | ||
45 | DestinationSide | 46 | DestinationSide | ||
46 | }; | 47 | }; | ||
47 | 48 | | |||
48 | ~StatJob() override; | 49 | ~StatJob() override; | ||
49 | 50 | | |||
50 | /** | 51 | /** | ||
kossebau: Is there other KIO API which has similar enums, where some consistency would be good to have? | |||||
kossebau: Please add @since comment | |||||
51 | * A stat() can have two meanings. Either we want to read from this URL, | 52 | * A stat() can have two meanings. Either we want to read from this URL, | ||
52 | * or to check if we can write to it. First case is "source", second is "dest". | 53 | * or to check if we can write to it. First case is "source", second is "dest". | ||
53 | * It is necessary to know what the StatJob is for, to tune the kioslave's behavior | 54 | * It is necessary to know what the StatJob is for, to tune the kioslave's behavior | ||
I am open to suggestion here :
meven: I am open to suggestion here :
1. Should it be more granular ?
2. Are names KIO-ish ? | |||||
54 | * (e.g. with FTP). | 55 | * (e.g. with FTP). | ||
55 | * By default it is SourceSide. | 56 | * By default it is SourceSide. | ||
56 | * @param side SourceSide or DestinationSide | 57 | * @param side SourceSide or DestinationSide | ||
57 | */ | 58 | */ | ||
58 | void setSide(StatSide side); | 59 | void setSide(StatSide side); | ||
59 | 60 | | |||
60 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0) | 61 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0) | ||
61 | /** | 62 | /** | ||
62 | * A stat() can have two meanings. Either we want to read from this URL, | 63 | * A stat() can have two meanings. Either we want to read from this URL, | ||
63 | * or to check if we can write to it. First case is "source", second is "dest". | 64 | * or to check if we can write to it. First case is "source", second is "dest". | ||
64 | * It is necessary to know what the StatJob is for, to tune the kioslave's behavior | 65 | * It is necessary to know what the StatJob is for, to tune the kioslave's behavior | ||
65 | * (e.g. with FTP). | 66 | * (e.g. with FTP). | ||
66 | * @param source true for "source" mode, false for "dest" mode | 67 | * @param source true for "source" mode, false for "dest" mode | ||
67 | * @deprecated Since 4.0, use setSide(StatSide side). | 68 | * @deprecated Since 4.0, use setSide(StatSide side). | ||
68 | */ | 69 | */ | ||
69 | KIOCORE_DEPRECATED_VERSION(4, 0, "Use StatJob::setSide(StatSide)") | 70 | KIOCORE_DEPRECATED_VERSION(4, 0, "Use StatJob::setSide(StatSide)") | ||
70 | void setSide(bool source); | 71 | void setSide(bool source); | ||
71 | #endif | 72 | #endif | ||
72 | 73 | | |||
73 | /** | 74 | /** | ||
74 | * Selects the level of @p details we want. | 75 | * Selects the level of @p details we want. | ||
76 | * @since 5.65 | ||||
kossebau: Please add @since | |||||
77 | */ | ||||
78 | void setDetails(KIO::StatDetails details); | ||||
79 | void setDetails(KIO::StatDetail detail); | ||||
I guess this overload exists because of the setDetails(short int) overload? If so, I suppose we can get rid of it for Qt6. dfaure: I guess this overload exists because of the setDetails(short int) overload?
(QFlags has an… | |||||
80 | | ||||
81 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 65) | ||||
82 | /** | ||||
All deprecated API should be also wrapped in visibility controls., so same #if/#endif also here. Basic structure: if deprecated api should be visible to compiler & Co (e.g. docs generator) API docs warning attribute if should be emitted method declaration endif kossebau: All deprecated API should be also wrapped in visibility controls., so same #if/#endif also here. | |||||
83 | * Selects the level of @p details we want. | ||||
75 | * By default this is 2 (all details wanted, including modification time, size, etc.), | 84 | * 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 | 85 | * 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. | 86 | * too much time, no need to follow symlinks etc. | ||
78 | * setDetails(0) is used for very simple probing: we'll only get the answer | 87 | * 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. | 88 | * "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 | 89 | * @param details 2 for all details, 1 for simple, 0 for very simple | ||
90 | * @deprecated since 5.65, use setDetails(KIO::StatDetails) | ||||
81 | */ | 91 | */ | ||
92 | KIOCORE_DEPRECATED_VERSION(5, 65, "Use setDetails(KIO::statDetails)") | ||||
dfaure: Typo: s/stat/Stat/ | |||||
82 | void setDetails(short int details); | 93 | void setDetails(short int details); | ||
94 | #endif | ||||
kossebau: Not deprecated now? | |||||
83 | 95 | | |||
84 | /** | 96 | /** | ||
85 | * @brief Result of the stat operation. | 97 | * @brief Result of the stat operation. | ||
86 | * Call this in the slot connected to result, | 98 | * Call this in the slot connected to result, | ||
87 | * and only after making sure no error happened. | 99 | * and only after making sure no error happened. | ||
88 | * @return the result of the stat | 100 | * @return the result of the stat | ||
89 | */ | 101 | */ | ||
90 | const UDSEntry &statResult() const; | 102 | const UDSEntry &statResult() const; | ||
▲ Show 20 Lines • Show All 54 Lines • ▼ Show 20 Line(s) | 156 | private: | |||
145 | Q_PRIVATE_SLOT(d_func(), void slotStatEntry(const KIO::UDSEntry &entry)) | 157 | Q_PRIVATE_SLOT(d_func(), void slotStatEntry(const KIO::UDSEntry &entry)) | ||
146 | Q_PRIVATE_SLOT(d_func(), void slotRedirection(const QUrl &url)) | 158 | Q_PRIVATE_SLOT(d_func(), void slotRedirection(const QUrl &url)) | ||
147 | Q_DECLARE_PRIVATE(StatJob) | 159 | Q_DECLARE_PRIVATE(StatJob) | ||
148 | friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags); | 160 | friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags); | ||
149 | }; | 161 | }; | ||
150 | 162 | | |||
151 | /** | 163 | /** | ||
152 | * Find all details for one file or directory. | 164 | * Find all details for one file or directory. | ||
153 | * | 165 | * | ||
Does KIO::DefaultDetails make sense beyond stat in the KIO namespace? How does it match other similar flags? kossebau: Does KIO::DefaultDetails make sense beyond stat in the KIO namespace? How does it match other… | |||||
154 | * @param url the URL of the file | 166 | * @param url the URL of the file | ||
I wonder if this should not be rather a member of StatJob, instead of being on generic KIO namespace level. kossebau: I wonder if this should not be rather a member of StatJob, instead of being on generic KIO… | |||||
Actually, this could be part of the StatJob::StatDetail enum, no? Having combinations of lfags in the enum itself (to be used as shortcuts) is usual practice and also should not conflict with Q_DECLARE_FLAGS, IIRC (would need to check). kossebau: Actually, this could be part of the StatJob::StatDetail enum, no? Having combinations of lfags… | |||||
Great suggestion ! Adding it to the enum should just work, working on it. meven: Great suggestion !
I wanted to do that but I just did not find a way to have StatDefaultDetails… | |||||
155 | * @param flags Can be HideProgressInfo here | 167 | * @param flags Can be HideProgressInfo here | ||
156 | * @return the job handling the operation. | 168 | * @return the job handling the operation. | ||
157 | */ | 169 | */ | ||
158 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, JobFlags flags = DefaultFlags); | 170 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, JobFlags flags = DefaultFlags); | ||
159 | /** | 171 | /** | ||
160 | * Find all details for one file or directory. | 172 | * Find all details for one file or directory. | ||
161 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. | 173 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. | ||
162 | * | 174 | * | ||
163 | * @param url the URL of the file | 175 | * @param url the URL of the file | ||
164 | * @param side is SourceSide when stating a source file (we will do a get on it if | 176 | * @param side is SourceSide when stating a source file (we will do a get on it if | ||
165 | * the stat works) and DestinationSide when stating a destination file (target of a copy). | 177 | * the stat works) and DestinationSide when stating a destination file (target of a copy). | ||
166 | * The reason for this parameter is that in some cases the kioslave might not | 178 | * The reason for this parameter is that in some cases the kioslave might not | ||
167 | * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP | 179 | * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP | ||
168 | * has issues with case-sensitivity on some systems). | 180 | * has issues with case-sensitivity on some systems). | ||
169 | * When the slave can't reliably determine the existence of a file, it will: | 181 | * When the slave can't reliably determine the existence of a file, it will: | ||
170 | * @li be optimistic if SourceSide, i.e. it will assume the file exists, | 182 | * @li be optimistic if SourceSide, i.e. it will assume the file exists, | ||
171 | * and if it doesn't this will appear when actually trying to download it | 183 | * and if it doesn't this will appear when actually trying to download it | ||
172 | * @li be pessimistic if DestinationSide, i.e. it will assume the file | 184 | * @li be pessimistic if DestinationSide, i.e. it will assume the file | ||
173 | * doesn't exist, to prevent showing "about to overwrite" errors to the user. | 185 | * doesn't exist, to prevent showing "about to overwrite" errors to the user. | ||
174 | * If you simply want to check for existence without downloading/uploading afterwards, | 186 | * If you simply want to check for existence without downloading/uploading afterwards, | ||
175 | * then you should use DestinationSide. | 187 | * then you should use DestinationSide. | ||
176 | * | 188 | * | ||
177 | * @param details selects the level of details we want. | 189 | * @param details selects the level of details we want. | ||
190 | * You can fine grain the detail level you want. | ||||
Not sure what this specific sentence adds to the previous one. It's a parameter, obviously that means we can choose what to pass to it... Maybe more useful to mention that this is for performance reasons, less details implies more speed. dfaure: Not sure what this specific sentence adds to the previous one. It's a parameter, obviously that… | |||||
191 | * @param flags Can be HideProgressInfo here | ||||
192 | * @return the job handling the operation. | ||||
193 | * @since 5.65 | ||||
kossebau: Please add @since | |||||
194 | */ | ||||
195 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, KIO::StatJob::StatSide side, | ||||
196 | KIO::StatDetails details = KIO::StatDetail::StatDefaultDetails, JobFlags flags = DefaultFlags); | ||||
197 | | ||||
198 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 65) | ||||
kossebau: This wants to be "5, 69" now, not "5, 68" | |||||
kossebau: Ah, was already fixed. | |||||
meven: 5434ffd0c655b0996e881fec605dc988a672d85c | |||||
199 | /** | ||||
Please wrap the deprecated API call (incl. API dox comment) with visibilty controlling #if/#endif., so here #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 64) kossebau: Please wrap the deprecated API call (incl. API dox comment) with visibilty controlling… | |||||
200 | * Find all details for one file or directory. | ||||
201 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. | ||||
202 | * | ||||
203 | * @param url the URL of the file | ||||
204 | * @param side is SourceSide when stating a source file (we will do a get on it if | ||||
205 | * the stat works) and DestinationSide when stating a destination file (target of a copy). | ||||
206 | * The reason for this parameter is that in some cases the kioslave might not | ||||
207 | * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP | ||||
208 | * has issues with case-sensitivity on some systems). | ||||
209 | * When the slave can't reliably determine the existence of a file, it will: | ||||
210 | * @li be optimistic if SourceSide, i.e. it will assume the file exists, | ||||
211 | * and if it doesn't this will appear when actually trying to download it | ||||
212 | * @li be pessimistic if DestinationSide, i.e. it will assume the file | ||||
213 | * doesn't exist, to prevent showing "about to overwrite" errors to the user. | ||||
214 | * If you simply want to check for existence without downloading/uploading afterwards, | ||||
215 | * then you should use DestinationSide. | ||||
216 | * | ||||
217 | * @param details selects the level of details we want. | ||||
178 | * By default this is 2 (all details wanted, including modification time, size, etc.), | 218 | * By default this is 2 (all details wanted, including modification time, size, etc.), | ||
179 | * setDetails(1) is used when deleting: we don't need all the information if it takes | 219 | * setDetails(1) is used when deleting: we don't need all the information if it takes | ||
180 | * too much time, no need to follow symlinks etc. | 220 | * too much time, no need to follow symlinks etc. | ||
181 | * setDetails(0) is used for very simple probing: we'll only get the answer | 221 | * setDetails(0) is used for very simple probing: we'll only get the answer | ||
182 | * "it's a file or a directory or a symlink, or it doesn't exist". This is used by KRun and DeleteJob. | 222 | * "it's a file or a directory or a symlink, or it doesn't exist". This is used by KRun and DeleteJob. | ||
183 | * @param flags Can be HideProgressInfo here | 223 | * @param flags Can be HideProgressInfo here | ||
184 | * @return the job handling the operation. | 224 | * @return the job handling the operation. | ||
225 | * @deprecated since 5.65, use stat(const QUrl &, KIO::StatSide, KIO::StatDetails int, JobFlags) | ||||
Please add "@deprecated Since 5.64. Use KIO::stat(const QUrl &, KIO::StatJob::StatSide, StatJob::Details int, JobFlags)" For all the recommended details to add when deprecating API (also with the new deprecation macros), please see kossebau: Please add "@deprecated Since 5.64. Use KIO::stat(const QUrl &, KIO::StatJob::StatSide, StatJob… | |||||
185 | */ | 226 | */ | ||
227 | KIOCORE_DEPRECATED_VERSION(5, 65, "Use KIO::stat(const QUrl &, KIO::StatSide, KIO::StatDetails int, JobFlags)") | ||||
dfaure: Why does this say "int" after "StatDetails"? | |||||
dfaure: This was marked as done, but I still see ", KIO::StatDetails int," | |||||
186 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, KIO::StatJob::StatSide side, | 228 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, KIO::StatJob::StatSide side, | ||
187 | short int details, JobFlags flags = DefaultFlags); | 229 | short int details, JobFlags flags = DefaultFlags); | ||
188 | 230 | | |||
231 | /** | ||||
232 | * Converts the legacy stat details int to a StatDetail Flag | ||||
233 | * @param details @see setDetails() | ||||
234 | * @since 5.65 | ||||
235 | * @deprecated since 5.65, use direcly KIO::StatDetails | ||||
dfaure: Typo: direcly -> directly (happens again two lines down) | |||||
dfaure: Still there | |||||
236 | */ | ||||
237 | KIOCORE_DEPRECATED_VERSION(5, 65, "Use direcly KIO::StatDetails") | ||||
missing the same #if as the above methods, no? dfaure: missing the same #if as the above methods, no?
In a "clean" build it should disappear. | |||||
meven: It shares the same #if block with the stat function | |||||
238 | KIOCORE_EXPORT KIO::StatDetails detailsToStatDetails(int details); | ||||
239 | | ||||
240 | #endif | ||||
241 | | ||||
kossebau: #endif | |||||
189 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0) | 242 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0) | ||
190 | /** | 243 | /** | ||
191 | * Find all details for one file or directory. | 244 | * Find all details for one file or directory. | ||
192 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. | 245 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. | ||
193 | * | 246 | * | ||
194 | * @param url the URL of the file | 247 | * @param url the URL of the file | ||
195 | * @param sideIsSource is true when stating a source file (we will do a get on it if | 248 | * @param sideIsSource is true when stating a source file (we will do a get on it if | ||
196 | * the stat works) and false when stating a destination file (target of a copy). | 249 | * the stat works) and false when stating a destination file (target of a copy). | ||
Show All 11 Lines | |||||
208 | * @param details selects the level of details we want. | 261 | * @param details selects the level of details we want. | ||
209 | * By default this is 2 (all details wanted, including modification time, size, etc.), | 262 | * By default this is 2 (all details wanted, including modification time, size, etc.), | ||
210 | * setDetails(1) is used when deleting: we don't need all the information if it takes | 263 | * setDetails(1) is used when deleting: we don't need all the information if it takes | ||
211 | * too much time, no need to follow symlinks etc. | 264 | * too much time, no need to follow symlinks etc. | ||
212 | * setDetails(0) is used for very simple probing: we'll only get the answer | 265 | * setDetails(0) is used for very simple probing: we'll only get the answer | ||
213 | * "it's a file or a directory, or it doesn't exist". This is used by KRun. | 266 | * "it's a file or a directory, or it doesn't exist". This is used by KRun. | ||
214 | * @param flags Can be HideProgressInfo here | 267 | * @param flags Can be HideProgressInfo here | ||
215 | * @return the job handling the operation. | 268 | * @return the job handling the operation. | ||
216 | * @deprecated Since 4.0, use stat(const QUrl &, KIO::StatJob::StatSide, short int, JobFlags) | 269 | * @deprecated Since 4.0, use stat(const QUrl &, KIO::StatSide, short int, JobFlags) | ||
217 | */ | 270 | */ | ||
218 | KIOCORE_DEPRECATED_VERSION(4, 0, "Use KIO::stat(const QUrl &, KIO::StatJob::StatSide, short int, JobFlags)") | 271 | KIOCORE_DEPRECATED_VERSION(4, 0, "Use KIO::stat(const QUrl &, KIO::StatSide, short int, JobFlags)") | ||
219 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, bool sideIsSource, | 272 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, bool sideIsSource, | ||
220 | short int details, JobFlags flags = DefaultFlags); | 273 | short int details, JobFlags flags = DefaultFlags); | ||
221 | #endif | 274 | #endif | ||
222 | 275 | | |||
223 | /** | 276 | /** | ||
224 | * Tries to map a local URL for the given URL, using a KIO job. | 277 | * Tries to map a local URL for the given URL, using a KIO job. | ||
225 | * | 278 | * | ||
226 | * Starts a (stat) job for determining the "most local URL" for a given URL. | 279 | * Starts a (stat) job for determining the "most local URL" for a given URL. | ||
Show All 9 Lines |
Is there other KIO API which has similar enums, where some consistency would be good to have?
On a first look, the names seems very short & generic to me, having some other name element might avoid semantic collisions perhaps. No idea yet, not looked further.