Changeset View
Standalone View
src/core/statjob.h
Show First 20 Lines • Show All 41 Lines • ▼ Show 20 Line(s) | |||||
42 | public: | 42 | public: | ||
43 | enum StatSide { | 43 | enum StatSide { | ||
44 | SourceSide, | 44 | SourceSide, | ||
45 | DestinationSide | 45 | DestinationSide | ||
46 | }; | 46 | }; | ||
47 | 47 | | |||
48 | ~StatJob() override; | 48 | ~StatJob() override; | ||
49 | 49 | | |||
50 | /// @since 5.64 | ||||
kossebau: Is there other KIO API which has similar enums, where some consistency would be good to have? | |||||
kossebau: Please add @since comment | |||||
51 | enum StatDetail { | ||||
52 | /// Filename, access, type, size, linkdest | ||||
53 | Basic = 0x1, | ||||
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 | /// uid, gid | ||||
55 | User = 0x2, | ||||
56 | /// atime, mtime, btime | ||||
57 | Time = 0x4, | ||||
58 | /// Resolve symlinks | ||||
59 | ResolveSymlink = 0x8, | ||||
60 | /// acl Data | ||||
61 | Acl = 0x10, | ||||
62 | /// dev, inode | ||||
63 | Inode = 0x20 | ||||
64 | }; | ||||
65 | Q_DECLARE_FLAGS(StatDetails, StatDetail) | ||||
66 | | ||||
50 | /** | 67 | /** | ||
51 | * A stat() can have two meanings. Either we want to read from this URL, | 68 | * 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". | 69 | * 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 | 70 | * It is necessary to know what the StatJob is for, to tune the kioslave's behavior | ||
54 | * (e.g. with FTP). | 71 | * (e.g. with FTP). | ||
55 | * By default it is SourceSide. | 72 | * By default it is SourceSide. | ||
56 | * @param side SourceSide or DestinationSide | 73 | * @param side SourceSide or DestinationSide | ||
57 | */ | 74 | */ | ||
Show All 9 Lines | 77 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0) | |||
67 | * @deprecated Since 4.0, use setSide(StatSide side). | 84 | * @deprecated Since 4.0, use setSide(StatSide side). | ||
68 | */ | 85 | */ | ||
69 | KIOCORE_DEPRECATED_VERSION(4, 0, "Use StatJob::setSide(StatSide)") | 86 | KIOCORE_DEPRECATED_VERSION(4, 0, "Use StatJob::setSide(StatSide)") | ||
70 | void setSide(bool source); | 87 | void setSide(bool source); | ||
71 | #endif | 88 | #endif | ||
72 | 89 | | |||
73 | /** | 90 | /** | ||
74 | * Selects the level of @p details we want. | 91 | * Selects the level of @p details we want. | ||
92 | * @since 5.64 | ||||
kossebau: Please add @since | |||||
93 | */ | ||||
94 | void setDetails(StatJob::StatDetails details); | ||||
95 | | ||||
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… | |||||
96 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 64) | ||||
97 | /** | ||||
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. | |||||
98 | * Selects the level of @p details we want. | ||||
75 | * By default this is 2 (all details wanted, including modification time, size, etc.), | 99 | * 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 | 100 | * 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. | 101 | * too much time, no need to follow symlinks etc. | ||
78 | * setDetails(0) is used for very simple probing: we'll only get the answer | 102 | * 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. | 103 | * "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 | 104 | * @param details 2 for all details, 1 for simple, 0 for very simple | ||
105 | * @deprecated since 5.64, use setDetails(StatJob::StatDetails) | ||||
81 | */ | 106 | */ | ||
107 | KIOCORE_DEPRECATED_VERSION(5, 64, "use setDetails(StatJob::statDetails)") | ||||
dfaure: Typo: s/stat/Stat/ | |||||
82 | void setDetails(short int details); | 108 | void setDetails(short int details); | ||
109 | #endif | ||||
kossebau: Not deprecated now? | |||||
83 | 110 | | |||
84 | /** | 111 | /** | ||
85 | * @brief Result of the stat operation. | 112 | * @brief Result of the stat operation. | ||
86 | * Call this in the slot connected to result, | 113 | * Call this in the slot connected to result, | ||
87 | * and only after making sure no error happened. | 114 | * and only after making sure no error happened. | ||
88 | * @return the result of the stat | 115 | * @return the result of the stat | ||
89 | */ | 116 | */ | ||
90 | const UDSEntry &statResult() const; | 117 | const UDSEntry &statResult() const; | ||
▲ Show 20 Lines • Show All 52 Lines • ▼ Show 20 Line(s) | |||||
143 | 170 | | |||
144 | private: | 171 | private: | ||
145 | Q_PRIVATE_SLOT(d_func(), void slotStatEntry(const KIO::UDSEntry &entry)) | 172 | Q_PRIVATE_SLOT(d_func(), void slotStatEntry(const KIO::UDSEntry &entry)) | ||
146 | Q_PRIVATE_SLOT(d_func(), void slotRedirection(const QUrl &url)) | 173 | Q_PRIVATE_SLOT(d_func(), void slotRedirection(const QUrl &url)) | ||
147 | Q_DECLARE_PRIVATE(StatJob) | 174 | Q_DECLARE_PRIVATE(StatJob) | ||
148 | friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags); | 175 | friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags); | ||
149 | }; | 176 | }; | ||
150 | 177 | | |||
178 | Q_DECLARE_OPERATORS_FOR_FLAGS(StatJob::StatDetails) | ||||
179 | | ||||
180 | /// @since 5.64 | ||||
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… | |||||
181 | constexpr static StatJob::StatDetails StatDefaultDetails = StatJob::StatDetail::Basic | StatJob::StatDetail::User | StatJob::StatDetail::Time | StatJob::StatDetail::Acl | StatJob::StatDetail::ResolveSymlink; | ||||
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… | |||||
182 | | ||||
151 | /** | 183 | /** | ||
152 | * Find all details for one file or directory. | 184 | * Find all details for one file or directory. | ||
153 | * | 185 | * | ||
154 | * @param url the URL of the file | 186 | * @param url the URL of the file | ||
155 | * @param flags Can be HideProgressInfo here | 187 | * @param flags Can be HideProgressInfo here | ||
156 | * @return the job handling the operation. | 188 | * @return the job handling the operation. | ||
157 | */ | 189 | */ | ||
158 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, JobFlags flags = DefaultFlags); | 190 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, JobFlags flags = DefaultFlags); | ||
Show All 11 Lines | |||||
170 | * @li be optimistic if SourceSide, i.e. it will assume the file exists, | 202 | * @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 | 203 | * 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 | 204 | * @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. | 205 | * 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, | 206 | * If you simply want to check for existence without downloading/uploading afterwards, | ||
175 | * then you should use DestinationSide. | 207 | * then you should use DestinationSide. | ||
176 | * | 208 | * | ||
177 | * @param details selects the level of details we want. | 209 | * @param details selects the level of details we want. | ||
210 | * 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… | |||||
211 | * @param flags Can be HideProgressInfo here | ||||
212 | * @return the job handling the operation. | ||||
213 | * @since 5.64 | ||||
kossebau: Please add @since | |||||
214 | */ | ||||
215 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, KIO::StatJob::StatSide side, | ||||
216 | StatJob::StatDetails details = StatDefaultDetails, JobFlags flags = DefaultFlags); | ||||
217 | | ||||
218 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 64) | ||||
kossebau: This wants to be "5, 69" now, not "5, 68" | |||||
kossebau: Ah, was already fixed. | |||||
meven: 5434ffd0c655b0996e881fec605dc988a672d85c | |||||
219 | /** | ||||
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… | |||||
220 | * Find all details for one file or directory. | ||||
221 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. | ||||
222 | * | ||||
223 | * @param url the URL of the file | ||||
224 | * @param side is SourceSide when stating a source file (we will do a get on it if | ||||
225 | * the stat works) and DestinationSide when stating a destination file (target of a copy). | ||||
226 | * The reason for this parameter is that in some cases the kioslave might not | ||||
227 | * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP | ||||
228 | * has issues with case-sensitivity on some systems). | ||||
229 | * When the slave can't reliably determine the existence of a file, it will: | ||||
230 | * @li be optimistic if SourceSide, i.e. it will assume the file exists, | ||||
231 | * and if it doesn't this will appear when actually trying to download it | ||||
232 | * @li be pessimistic if DestinationSide, i.e. it will assume the file | ||||
233 | * doesn't exist, to prevent showing "about to overwrite" errors to the user. | ||||
234 | * If you simply want to check for existence without downloading/uploading afterwards, | ||||
235 | * then you should use DestinationSide. | ||||
236 | * | ||||
237 | * @param details selects the level of details we want. | ||||
178 | * By default this is 2 (all details wanted, including modification time, size, etc.), | 238 | * 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 | 239 | * 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. | 240 | * too much time, no need to follow symlinks etc. | ||
181 | * setDetails(0) is used for very simple probing: we'll only get the answer | 241 | * 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. | 242 | * "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 | 243 | * @param flags Can be HideProgressInfo here | ||
184 | * @return the job handling the operation. | 244 | * @return the job handling the operation. | ||
245 | * @deprecated since 5.64, use stat(const QUrl &, KIO::StatJob::StatSide, StatJob::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 | */ | 246 | */ | ||
247 | KIOCORE_DEPRECATED_VERSION(5, 64, "Use KIO::stat(const QUrl &, KIO::StatJob::StatSide, StatJob::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, | 248 | KIOCORE_EXPORT StatJob *stat(const QUrl &url, KIO::StatJob::StatSide side, | ||
187 | short int details, JobFlags flags = DefaultFlags); | 249 | short int details, JobFlags flags = DefaultFlags); | ||
250 | #endif | ||||
188 | 251 | | |||
kossebau: #endif | |||||
189 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0) | 252 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0) | ||
190 | /** | 253 | /** | ||
191 | * Find all details for one file or directory. | 254 | * Find all details for one file or directory. | ||
192 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. | 255 | * This version of the call includes two additional booleans, @p sideIsSource and @p details. | ||
193 | * | 256 | * | ||
dfaure: Typo: direcly -> directly (happens again two lines down) | |||||
dfaure: Still there | |||||
194 | * @param url the URL of the file | 257 | * @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 | 258 | * @param sideIsSource is true when stating a source file (we will do a get on it if | ||
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 | |||||
196 | * the stat works) and false when stating a destination file (target of a copy). | 259 | * the stat works) and false when stating a destination file (target of a copy). | ||
197 | * The reason for this parameter is that in some cases the kioslave might not | 260 | * The reason for this parameter is that in some cases the kioslave might not | ||
198 | * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP | 261 | * be able to determine a file's existence (e.g. HTTP doesn't allow it, FTP | ||
199 | * has issues with case-sensitivity on some systems). | 262 | * has issues with case-sensitivity on some systems). | ||
200 | * When the slave can't reliably determine the existence of a file, it will: | 263 | * When the slave can't reliably determine the existence of a file, it will: | ||
201 | * @li be optimistic if sideIsSource=true, i.e. it will assume the file exists, | 264 | * @li be optimistic if sideIsSource=true, i.e. it will assume the file exists, | ||
202 | * and if it doesn't this will appear when actually trying to download it | 265 | * and if it doesn't this will appear when actually trying to download it | ||
203 | * @li be pessimistic if sideIsSource=false, i.e. it will assume the file | 266 | * @li be pessimistic if sideIsSource=false, i.e. it will assume the file | ||
Show All 32 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.