1 | // -*- c++ -*- |
2 | /* |
3 | This file is part of the KDE libraries |
4 | SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org> |
5 | SPDX-FileCopyrightText: 2000-2006 David Faure <faure@kde.org> |
6 | |
7 | SPDX-License-Identifier: LGPL-2.0-or-later |
8 | */ |
9 | |
10 | #ifndef KIO_COPYJOB_H |
11 | #define KIO_COPYJOB_H |
12 | |
13 | #include <QObject> |
14 | #include <QStringList> |
15 | #include <QUrl> |
16 | |
17 | #include "job_base.h" |
18 | #include "kiocore_export.h" |
19 | |
20 | class QDateTime; |
21 | |
22 | namespace KIO |
23 | { |
24 | |
25 | class CopyJobPrivate; |
26 | /*! |
27 | * \class KIO::CopyJob |
28 | * \inheaderfile KIO/CopyJob |
29 | * \inmodule KIOCore |
30 | * |
31 | * \brief CopyJob is used to move, copy or symlink files and directories. |
32 | * |
33 | * Don't create the job directly, but use KIO::copy(), |
34 | * KIO::move(), KIO::link() and friends. |
35 | * |
36 | * \sa copy() |
37 | * \sa copyAs() |
38 | * \sa move() |
39 | * \sa moveAs() |
40 | * \sa link() |
41 | * \sa linkAs() |
42 | */ |
43 | class KIOCORE_EXPORT CopyJob : public Job |
44 | { |
45 | Q_OBJECT |
46 | |
47 | public: |
48 | /*! |
49 | * Defines the mode of the operation |
50 | * |
51 | * \value Copy |
52 | * \value Move |
53 | * \value Link |
54 | */ |
55 | enum CopyMode { |
56 | Copy, |
57 | Move, |
58 | Link |
59 | }; |
60 | |
61 | ~CopyJob() override; |
62 | |
63 | /*! |
64 | * Returns the mode of the operation (copy, move, or link), |
65 | * depending on whether KIO::copy(), KIO::move() or KIO::link() was called. |
66 | */ |
67 | CopyMode operationMode() const; |
68 | |
69 | /*! |
70 | * Returns the list of source URLs. |
71 | */ |
72 | QList<QUrl> srcUrls() const; |
73 | |
74 | /*! |
75 | * Returns the destination URL. |
76 | */ |
77 | QUrl destUrl() const; |
78 | |
79 | /*! |
80 | * By default the permissions of the copied files will be those of the source files. |
81 | * |
82 | * But when copying "template" files to "new" files, people prefer the umask |
83 | * to apply, rather than the template's permissions. |
84 | * For that case, call setDefaultPermissions(true) |
85 | */ |
86 | void setDefaultPermissions(bool b); |
87 | |
88 | /*! |
89 | * Skip copying or moving any file when the destination already exists, |
90 | * instead of the default behavior (interactive mode: showing a dialog to the user, |
91 | * non-interactive mode: aborting with an error). |
92 | * Initially added for a unit test. |
93 | * \since 4.2 |
94 | */ |
95 | void setAutoSkip(bool autoSkip); |
96 | |
97 | /*! |
98 | * Rename files automatically when the destination already exists, |
99 | * instead of the default behavior (interactive mode: showing a dialog to the user, |
100 | * non-interactive mode: aborting with an error). |
101 | * Initially added for a unit test. |
102 | * \since 4.7 |
103 | */ |
104 | void setAutoRename(bool autoRename); |
105 | |
106 | /*! |
107 | * Reuse any directory that already exists, instead of the default behavior |
108 | * (interactive mode: showing a dialog to the user, |
109 | * non-interactive mode: aborting with an error). |
110 | * \since 4.2 |
111 | */ |
112 | void setWriteIntoExistingDirectories(bool overwriteAllDirs); |
113 | |
114 | /*! |
115 | * \reimp |
116 | */ |
117 | bool doSuspend() override; |
118 | |
119 | /*! |
120 | * \reimp |
121 | */ |
122 | bool doResume() override; |
123 | |
124 | Q_SIGNALS: |
125 | /*! |
126 | * Sends the number of processed files. |
127 | * |
128 | * \a job the job that emitted this signal |
129 | * |
130 | * \a files the number of processed files |
131 | */ |
132 | void processedFiles(KIO::Job *job, unsigned long files); |
133 | /*! |
134 | * Sends the number of processed directories. |
135 | * |
136 | * \a job the job that emitted this signal |
137 | * |
138 | * \a dirs the number of processed dirs |
139 | */ |
140 | void processedDirs(KIO::Job *job, unsigned long dirs); |
141 | |
142 | /*! |
143 | * The job is copying a file or directory. |
144 | * |
145 | * Note: This signal is used for progress dialogs, it's not emitted for |
146 | * every file or directory (this would be too slow), but every 200ms. |
147 | * |
148 | * \a job the job that emitted this signal |
149 | * |
150 | * \a src the URL of the file or directory that is currently |
151 | * being copied |
152 | * |
153 | * \a dest the destination of the current operation |
154 | */ |
155 | void copying(KIO::Job *job, const QUrl &src, const QUrl &dest); |
156 | /*! |
157 | * The job is creating a symbolic link. |
158 | * |
159 | * Note: This signal is used for progress dialogs, it's not emitted for |
160 | * every file or directory (this would be too slow), but every 200ms. |
161 | * |
162 | * \a job the job that emitted this signal |
163 | * |
164 | * \a target the URL of the file or directory that is currently |
165 | * being linked |
166 | * |
167 | * \a to the destination of the current operation |
168 | */ |
169 | void linking(KIO::Job *job, const QString &target, const QUrl &to); |
170 | /*! |
171 | * The job is moving a file or directory. |
172 | * |
173 | * Note: This signal is used for progress dialogs, it's not emitted for |
174 | * every file or directory (this would be too slow), but every 200ms. |
175 | * |
176 | * \a job the job that emitted this signal |
177 | * |
178 | * \a from the URL of the file or directory that is currently |
179 | * being moved |
180 | * |
181 | * \a to the destination of the current operation |
182 | */ |
183 | void moving(KIO::Job *job, const QUrl &from, const QUrl &to); |
184 | /*! |
185 | * The job is creating the directory \a dir. |
186 | * |
187 | * This signal is emitted for every directory being created. |
188 | * |
189 | * \a job the job that emitted this signal |
190 | * |
191 | * \a dir the directory that is currently being created |
192 | */ |
193 | void creatingDir(KIO::Job *job, const QUrl &dir); |
194 | /*! |
195 | * The user chose to rename \a from to \a to. |
196 | * |
197 | * \a job the job that emitted this signal |
198 | * |
199 | * \a from the original name |
200 | * |
201 | * \a to the new name |
202 | */ |
203 | void renamed(KIO::Job *job, const QUrl &from, const QUrl &to); |
204 | |
205 | /*! |
206 | * The job emits this signal when copying or moving a file or directory successfully finished. |
207 | * This signal is mainly for the Undo feature. |
208 | * If you simply want to know when a copy job is done, use result(). |
209 | * |
210 | * \a job the job that emitted this signal |
211 | * |
212 | * \a from the source URL |
213 | * |
214 | * \a to the destination URL |
215 | * |
216 | * \a mtime the modification time of the source file, hopefully set on the destination file |
217 | * too (when the KIO worker supports it). |
218 | * |
219 | * \a directory indicates whether a file or directory was successfully copied/moved. |
220 | * true for a directory, false for file |
221 | * |
222 | * \a renamed indicates that the destination URL was created using a |
223 | * rename operation (i.e. fast directory moving). true if is has been renamed |
224 | */ |
225 | void copyingDone(KIO::Job *job, const QUrl &from, const QUrl &to, const QDateTime &mtime, bool directory, bool renamed); |
226 | /*! |
227 | * The job is copying or moving a symbolic link, that points to target. |
228 | * The new link is created in \a to. The existing one is/was in \a from. |
229 | * This signal is mainly for the Undo feature. |
230 | * |
231 | * \a job the job that emitted this signal |
232 | * |
233 | * \a from the source URL |
234 | * |
235 | * \a target the target |
236 | * |
237 | * \a to the destination URL |
238 | */ |
239 | void copyingLinkDone(KIO::Job *job, const QUrl &from, const QString &target, const QUrl &to); |
240 | protected Q_SLOTS: |
241 | void slotResult(KJob *job) override; |
242 | |
243 | protected: |
244 | KIOCORE_NO_EXPORT explicit CopyJob(CopyJobPrivate &dd); |
245 | void emitResult(); |
246 | |
247 | private: |
248 | Q_DECLARE_PRIVATE(CopyJob) |
249 | }; |
250 | |
251 | /*! |
252 | * \relates KIO::CopyJob |
253 | * |
254 | * Copy a file or directory \a src into the destination \a dest, |
255 | * which can be a file (including the final filename) or a directory |
256 | * (into which \a src will be copied). |
257 | * |
258 | * This emulates the cp command completely. |
259 | * |
260 | * \a src the file or directory to copy |
261 | * \a dest the destination |
262 | * \a flags copy() supports HideProgressInfo and Overwrite. |
263 | * Note: Overwrite has the meaning of both "write into existing directories" and |
264 | * "overwrite existing files". However if "dest" exists, then src is copied |
265 | * into a subdir of dest, just like "cp" does. Use copyAs if you don't want that. |
266 | * |
267 | * Returns the job handling the operation |
268 | * |
269 | * \sa copyAs() |
270 | */ |
271 | KIOCORE_EXPORT CopyJob *copy(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags); |
272 | |
273 | /*! |
274 | * \relates KIO::CopyJob |
275 | * |
276 | * Copy a file or directory \a src into the destination \a dest, |
277 | * which is the destination name in any case, even for a directory. |
278 | * |
279 | * As opposed to copy(), this doesn't emulate cp, but is the only |
280 | * way to copy a directory, giving it a new name and getting an error |
281 | * box if a directory already exists with the same name (or writing the |
282 | * contents of \a src into \a dest, when using Overwrite). |
283 | * |
284 | * \a src the file or directory to copy |
285 | * \a dest the destination |
286 | * \a flags copyAs() supports HideProgressInfo and Overwrite. |
287 | * |
288 | * \note Overwrite has the meaning of both "write into existing directories" and |
289 | * "overwrite existing files". |
290 | * |
291 | * Returns the job handling the operation |
292 | */ |
293 | KIOCORE_EXPORT CopyJob *copyAs(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags); |
294 | |
295 | /*! |
296 | * \relates KIO::CopyJob |
297 | * |
298 | * Copy a list of file/dirs \a src into a destination directory \a dest. |
299 | * |
300 | * \a src the list of files and/or directories |
301 | * |
302 | * \a dest the destination |
303 | * |
304 | * \a flags copy() supports HideProgressInfo and Overwrite. |
305 | * Note: Overwrite has the meaning of both "write into existing directories" and |
306 | * "overwrite existing files". However if "dest" exists, then src is copied |
307 | * into a subdir of dest, just like "cp" does. |
308 | * |
309 | * Returns the job handling the operation |
310 | */ |
311 | KIOCORE_EXPORT CopyJob *copy(const QList<QUrl> &src, const QUrl &dest, JobFlags flags = DefaultFlags); |
312 | |
313 | /*! |
314 | * \relates KIO::CopyJob |
315 | * |
316 | * Moves a file or directory \a src to the given destination \a dest. |
317 | * |
318 | * \a src the file or directory to copy |
319 | * |
320 | * \a dest the destination |
321 | * |
322 | * \a flags move() supports HideProgressInfo and Overwrite. |
323 | * Note: Overwrite has the meaning of both "write into existing directories" and |
324 | * "overwrite existing files". However if "dest" exists, then src is copied |
325 | * into a subdir of dest, just like "cp" does. |
326 | * |
327 | * Returns the job handling the operation |
328 | * \sa copy() |
329 | * \sa moveAs() |
330 | */ |
331 | KIOCORE_EXPORT CopyJob *move(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags); |
332 | /*! |
333 | * \relates KIO::CopyJob |
334 | * |
335 | * Moves a file or directory \a src to the given destination \a dest. Unlike move() |
336 | * this operation will not move \a src into \a dest when \a dest exists: it will |
337 | * either fail, or move the contents of \a src into it if Overwrite is set. |
338 | * |
339 | * \a src the file or directory to copy |
340 | * |
341 | * \a dest the destination |
342 | * |
343 | * \a flags moveAs() supports HideProgressInfo and Overwrite. |
344 | * Note: Overwrite has the meaning of both "write into existing directories" and |
345 | * "overwrite existing files". |
346 | * |
347 | * Returns the job handling the operation |
348 | * \sa copyAs() |
349 | */ |
350 | KIOCORE_EXPORT CopyJob *moveAs(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags); |
351 | /*! |
352 | * \relates KIO::CopyJob |
353 | * |
354 | * Moves a list of files or directories \a src to the given destination \a dest. |
355 | * |
356 | * \a src the list of files or directories to copy |
357 | * |
358 | * \a dest the destination |
359 | * |
360 | * \a flags move() supports HideProgressInfo and Overwrite. |
361 | * Note: Overwrite has the meaning of both "write into existing directories" and |
362 | * "overwrite existing files". However if "dest" exists, then src is copied |
363 | * into a subdir of dest, just like "cp" does. |
364 | * |
365 | * Returns the job handling the operation |
366 | * \sa copy() |
367 | */ |
368 | KIOCORE_EXPORT CopyJob *move(const QList<QUrl> &src, const QUrl &dest, JobFlags flags = DefaultFlags); |
369 | |
370 | /*! |
371 | * \relates KIO::CopyJob |
372 | * |
373 | * Create a link. |
374 | * If the protocols and hosts are the same, a Unix symlink will be created. |
375 | * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created. |
376 | * |
377 | * \a src The existing file or directory, 'target' of the link. |
378 | * |
379 | * \a destDir Destination directory where the link will be created. |
380 | * |
381 | * \a flags link() supports HideProgressInfo only |
382 | * |
383 | * Returns the job handling the operation |
384 | */ |
385 | KIOCORE_EXPORT CopyJob *link(const QUrl &src, const QUrl &destDir, JobFlags flags = DefaultFlags); |
386 | |
387 | /*! |
388 | * \relates KIO::CopyJob |
389 | * |
390 | * Create several links |
391 | * If the protocols and hosts are the same, a Unix symlink will be created. |
392 | * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created. |
393 | * |
394 | * \a src The existing files or directories, 'targets' of the link. |
395 | * |
396 | * \a destDir Destination directory where the links will be created. |
397 | * |
398 | * \a flags link() supports HideProgressInfo only |
399 | * |
400 | * Returns the job handling the operation |
401 | */ |
402 | KIOCORE_EXPORT CopyJob *link(const QList<QUrl> &src, const QUrl &destDir, JobFlags flags = DefaultFlags); |
403 | |
404 | /*! |
405 | * \relates KIO::CopyJob |
406 | * |
407 | * Create a link. Unlike link() this operation will fail when \a dest is an existing |
408 | * directory rather than the final name for the link. |
409 | * If the protocols and hosts are the same, a Unix symlink will be created. |
410 | * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created. |
411 | * |
412 | * \a src The existing file or directory, 'target' of the link. |
413 | * |
414 | * \a dest Destination (i.e. the final symlink) |
415 | * |
416 | * \a flags linkAs() supports HideProgressInfo only |
417 | * |
418 | * Returns the job handling the operation |
419 | * \sa link() |
420 | * \sa copyAs() |
421 | */ |
422 | KIOCORE_EXPORT CopyJob *linkAs(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags); |
423 | |
424 | /*! |
425 | * \relates KIO::CopyJob |
426 | * |
427 | * Trash a file or directory. |
428 | * This is currently only supported for local files and directories. |
429 | * Use QUrl::fromLocalFile to create a URL from a local file path. |
430 | * |
431 | * \a src file to delete |
432 | * |
433 | * \a flags trash() supports HideProgressInfo only |
434 | * |
435 | * Returns the job handling the operation |
436 | */ |
437 | KIOCORE_EXPORT CopyJob *trash(const QUrl &src, JobFlags flags = DefaultFlags); |
438 | |
439 | /*! |
440 | * \relates KIO::CopyJob |
441 | * |
442 | * Trash a list of files or directories. |
443 | * This is currently only supported for local files and directories. |
444 | * |
445 | * \a src the files to delete |
446 | * |
447 | * \a flags trash() supports HideProgressInfo only |
448 | * |
449 | * Returns the job handling the operation |
450 | */ |
451 | KIOCORE_EXPORT CopyJob *trash(const QList<QUrl> &src, JobFlags flags = DefaultFlags); |
452 | |
453 | } |
454 | |
455 | #endif |
456 | |