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
20class QDateTime;
21
22namespace KIO
23{
24
25class 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 */
43class KIOCORE_EXPORT CopyJob : public Job
44{
45 Q_OBJECT
46
47public:
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
124Q_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);
240protected Q_SLOTS:
241 void slotResult(KJob *job) override;
242
243protected:
244 KIOCORE_NO_EXPORT explicit CopyJob(CopyJobPrivate &dd);
245 void emitResult();
246
247private:
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 */
271KIOCORE_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 */
293KIOCORE_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 */
311KIOCORE_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 */
331KIOCORE_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 */
350KIOCORE_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 */
368KIOCORE_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 */
385KIOCORE_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 */
402KIOCORE_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 */
422KIOCORE_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 */
437KIOCORE_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 */
451KIOCORE_EXPORT CopyJob *trash(const QList<QUrl> &src, JobFlags flags = DefaultFlags);
452
453}
454
455#endif
456

source code of kio/src/core/copyjob.h