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