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 | /// Default value includes fields provided by other entries | ||||
66 | StatDefaultDetails = Basic | User | Time | Acl | ResolveSymlink, | ||||
67 | }; | ||||
68 | Q_DECLARE_FLAGS(StatDetails, StatDetail) | ||||
69 | | ||||
50 | /** | 70 | /** | ||
51 | * A stat() can have two meanings. Either we want to read from this URL, | 71 | * 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". | 72 | * 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 | 73 | * It is necessary to know what the StatJob is for, to tune the kioslave's behavior | ||
54 | * (e.g. with FTP). | 74 | * (e.g. with FTP). | ||
55 | * By default it is SourceSide. | 75 | * By default it is SourceSide. | ||
56 | * @param side SourceSide or DestinationSide | 76 | * @param side SourceSide or DestinationSide | ||
57 | */ | 77 | */ | ||
Show All 9 Lines | 80 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(4, 0) | |||
67 | * @deprecated Since 4.0, use setSide(StatSide side). | 87 | * @deprecated Since 4.0, use setSide(StatSide side). | ||
68 | */ | 88 | */ | ||
69 | KIOCORE_DEPRECATED_VERSION(4, 0, "Use StatJob::setSide(StatSide)") | 89 | KIOCORE_DEPRECATED_VERSION(4, 0, "Use StatJob::setSide(StatSide)") | ||
70 | void setSide(bool source); | 90 | void setSide(bool source); | ||
71 | #endif | 91 | #endif | ||
72 | 92 | | |||
73 | /** | 93 | /** | ||
74 | * Selects the level of @p details we want. | 94 | * Selects the level of @p details we want. | ||
95 | * @since 5.64 | ||||
kossebau: Please add @since | |||||
96 | */ | ||||
97 | void setDetails(StatJob::StatDetails details); | ||||
98 | | ||||
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… | |||||
99 | #if KIOCORE_ENABLE_DEPRECATED_SINCE(5, 64) | ||||
100 | /** | ||||
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. | |||||
101 | * Selects the level of @p details we want. | ||||
75 | * By default this is 2 (all details wanted, including modification time, size, etc.), | 102 | * 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 | 103 | * 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. | 104 | * too much time, no need to follow symlinks etc. | ||
78 | * setDetails(0) is used for very simple probing: we'll only get the answer | 105 | * 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. | 106 | * "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 | 107 | * @param details 2 for all details, 1 for simple, 0 for very simple | ||
108 | * @deprecated since 5.64, use setDetails(StatJob::StatDetails) | ||||
81 | */ | 109 | */ | ||
110 | KIOCORE_DEPRECATED_VERSION(5, 64, "use setDetails(StatJob::statDetails)") | ||||
dfaure: Typo: s/stat/Stat/ | |||||
82 | void setDetails(short int details); | 111 | void setDetails(short int details); | ||
112 | #endif | ||||
kossebau: Not deprecated now? | |||||
83 | 113 | | |||
84 | /** | 114 | /** | ||
85 | * @brief Result of the stat operation. | 115 | * @brief Result of the stat operation. | ||
86 | * Call this in the slot connected to result, | 116 | * Call this in the slot connected to result, | ||
87 | * and only after making sure no error happened. | 117 | * and only after making sure no error happened. | ||
88 | * @return the result of the stat | 118 | * @return the result of the stat | ||
89 | */ | 119 | */ | ||
90 | const UDSEntry &statResult() const; | 120 | const UDSEntry &statResult() const; | ||
▲ Show 20 Lines • Show All 52 Lines • ▼ Show 20 Line(s) | |||||
143 | 173 | | |||
144 | private: | 174 | private: | ||
145 | Q_PRIVATE_SLOT(d_func(), void slotStatEntry(const KIO::UDSEntry &entry)) | 175 | Q_PRIVATE_SLOT(d_func(), void slotStatEntry(const KIO::UDSEntry &entry)) | ||
146 | Q_PRIVATE_SLOT(d_func(), void slotRedirection(const QUrl &url)) | 176 | Q_PRIVATE_SLOT(d_func(), void slotRedirection(const QUrl &url)) | ||
147 | Q_DECLARE_PRIVATE(StatJob) | 177 | Q_DECLARE_PRIVATE(StatJob) | ||
148 | friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags); | 178 | friend KIOCORE_EXPORT StatJob *mostLocalUrl(const QUrl &url, JobFlags flags); | ||
149 | }; | 179 | }; | ||
150 | 180 | | |||
181 | Q_DECLARE_OPERATORS_FOR_FLAGS(StatJob::StatDetails) | ||||
182 | | ||||
151 | /** | 183 | /** | ||
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… | |||||
152 | * Find all details for one file or directory. | 184 | * Find all details for one file or directory. | ||
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… | |||||
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); | ||
159 | /** | 191 | /** | ||
160 | * Find all details for one file or directory. | 192 | * Find all details for one file or directory. | ||
Show All 9 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 = StatJob::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.