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 copyjob.h <KIO/CopyJob>
28 *
29 * CopyJob is used to move, copy or symlink files and directories.
30 * Don't create the job directly, but use KIO::copy(),
31 * KIO::move(), KIO::link() and friends.
32 *
33 * @see KIO::copy()
34 * @see KIO::copyAs()
35 * @see KIO::move()
36 * @see KIO::moveAs()
37 * @see KIO::link()
38 * @see KIO::linkAs()
39 */
40class KIOCORE_EXPORT CopyJob : public Job
41{
42 Q_OBJECT
43
44public:
45 /**
46 * Defines the mode of the operation
47 */
48 enum CopyMode { Copy, Move, Link };
49
50 ~CopyJob() override;
51
52 /**
53 * Returns the mode of the operation (copy, move, or link),
54 * depending on whether KIO::copy(), KIO::move() or KIO::link() was called.
55 */
56 CopyMode operationMode() const;
57
58 /**
59 * Returns the list of source URLs.
60 * @return the list of source URLs.
61 */
62 QList<QUrl> srcUrls() const;
63
64 /**
65 * Returns the destination URL.
66 * @return the destination URL
67 */
68 QUrl destUrl() const;
69
70 /**
71 * By default the permissions of the copied files will be those of the source files.
72 *
73 * But when copying "template" files to "new" files, people prefer the umask
74 * to apply, rather than the template's permissions.
75 * For that case, call setDefaultPermissions(true)
76 */
77 void setDefaultPermissions(bool b);
78
79 /**
80 * Skip copying or moving any file when the destination already exists,
81 * instead of the default behavior (interactive mode: showing a dialog to the user,
82 * non-interactive mode: aborting with an error).
83 * Initially added for a unit test.
84 * \since 4.2
85 */
86 void setAutoSkip(bool autoSkip);
87
88 /**
89 * Rename files automatically 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.7
94 */
95 void setAutoRename(bool autoRename);
96
97 /**
98 * Reuse any directory that already exists, instead of the default behavior
99 * (interactive mode: showing a dialog to the user,
100 * non-interactive mode: aborting with an error).
101 * \since 4.2
102 */
103 void setWriteIntoExistingDirectories(bool overwriteAllDirs);
104
105 /**
106 * Reimplemented for internal reasons
107 */
108 bool doSuspend() override;
109
110 /**
111 * Reimplemented for internal reasons
112 */
113 bool doResume() override;
114
115Q_SIGNALS:
116 /**
117 * Sends the number of processed files.
118 * @param job the job that emitted this signal
119 * @param files the number of processed files
120 */
121 void processedFiles(KIO::Job *job, unsigned long files);
122 /**
123 * Sends the number of processed directories.
124 * @param job the job that emitted this signal
125 * @param dirs the number of processed dirs
126 */
127 void processedDirs(KIO::Job *job, unsigned long dirs);
128
129 /**
130 * The job is copying a file or directory.
131 *
132 * Note: This signal is used for progress dialogs, it's not emitted for
133 * every file or directory (this would be too slow), but every 200ms.
134 *
135 * @param job the job that emitted this signal
136 * @param src the URL of the file or directory that is currently
137 * being copied
138 * @param dest the destination of the current operation
139 */
140 void copying(KIO::Job *job, const QUrl &src, const QUrl &dest);
141 /**
142 * The job is creating a symbolic link.
143 *
144 * Note: This signal is used for progress dialogs, it's not emitted for
145 * every file or directory (this would be too slow), but every 200ms.
146 *
147 * @param job the job that emitted this signal
148 * @param target the URL of the file or directory that is currently
149 * being linked
150 * @param to the destination of the current operation
151 */
152 void linking(KIO::Job *job, const QString &target, const QUrl &to);
153 /**
154 * The job is moving a file or directory.
155 *
156 * Note: This signal is used for progress dialogs, it's not emitted for
157 * every file or directory (this would be too slow), but every 200ms.
158 *
159 * @param job the job that emitted this signal
160 * @param from the URL of the file or directory that is currently
161 * being moved
162 * @param to the destination of the current operation
163 */
164 void moving(KIO::Job *job, const QUrl &from, const QUrl &to);
165 /**
166 * The job is creating the directory @p dir.
167 *
168 * This signal is emitted for every directory being created.
169 *
170 * @param job the job that emitted this signal
171 * @param dir the directory that is currently being created
172 */
173 void creatingDir(KIO::Job *job, const QUrl &dir);
174 /**
175 * The user chose to rename @p from to @p to.
176 *
177 * @param job the job that emitted this signal
178 * @param from the original name
179 * @param to the new name
180 */
181 void renamed(KIO::Job *job, const QUrl &from, const QUrl &to);
182
183 /**
184 * The job emits this signal when copying or moving a file or directory successfully finished.
185 * This signal is mainly for the Undo feature.
186 * If you simply want to know when a copy job is done, use result().
187 *
188 * @param job the job that emitted this signal
189 * @param from the source URL
190 * @param to the destination URL
191 * @param mtime the modification time of the source file, hopefully set on the destination file
192 * too (when the KIO worker supports it).
193 * @param directory indicates whether a file or directory was successfully copied/moved.
194 * true for a directory, false for file
195 * @param renamed indicates that the destination URL was created using a
196 * rename operation (i.e. fast directory moving). true if is has been renamed
197 */
198 void copyingDone(KIO::Job *job, const QUrl &from, const QUrl &to, const QDateTime &mtime, bool directory, bool renamed);
199 /**
200 * The job is copying or moving a symbolic link, that points to target.
201 * The new link is created in @p to. The existing one is/was in @p from.
202 * This signal is mainly for the Undo feature.
203 * @param job the job that emitted this signal
204 * @param from the source URL
205 * @param target the target
206 * @param to the destination URL
207 */
208 void copyingLinkDone(KIO::Job *job, const QUrl &from, const QString &target, const QUrl &to);
209protected Q_SLOTS:
210 void slotResult(KJob *job) override;
211
212protected:
213 KIOCORE_NO_EXPORT explicit CopyJob(CopyJobPrivate &dd);
214 void emitResult();
215
216private:
217 Q_DECLARE_PRIVATE(CopyJob)
218};
219
220/**
221 * Copy a file or directory @p src into the destination @p dest,
222 * which can be a file (including the final filename) or a directory
223 * (into which @p src will be copied).
224 *
225 * This emulates the cp command completely.
226 *
227 * @param src the file or directory to copy
228 * @param dest the destination
229 * @param flags copy() supports HideProgressInfo and Overwrite.
230 * Note: Overwrite has the meaning of both "write into existing directories" and
231 * "overwrite existing files". However if "dest" exists, then src is copied
232 * into a subdir of dest, just like "cp" does. Use copyAs if you don't want that.
233 *
234 * @return the job handling the operation
235 * @see copyAs()
236 */
237KIOCORE_EXPORT CopyJob *copy(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags);
238
239/**
240 * Copy a file or directory @p src into the destination @p dest,
241 * which is the destination name in any case, even for a directory.
242 *
243 * As opposed to copy(), this doesn't emulate cp, but is the only
244 * way to copy a directory, giving it a new name and getting an error
245 * box if a directory already exists with the same name (or writing the
246 * contents of @p src into @p dest, when using Overwrite).
247 *
248 * @param src the file or directory to copy
249 * @param dest the destination
250 * @param flags copyAs() supports HideProgressInfo and Overwrite.
251 * Note: Overwrite has the meaning of both "write into existing directories" and
252 * "overwrite existing files".
253 *
254 * * @return the job handling the operation
255 */
256KIOCORE_EXPORT CopyJob *copyAs(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags);
257
258/**
259 * Copy a list of file/dirs @p src into a destination directory @p dest.
260 *
261 * @param src the list of files and/or directories
262 * @param dest the destination
263 * @param flags copy() supports HideProgressInfo and Overwrite.
264 * Note: Overwrite has the meaning of both "write into existing directories" and
265 * "overwrite existing files". However if "dest" exists, then src is copied
266 * into a subdir of dest, just like "cp" does.
267 * @return the job handling the operation
268 */
269KIOCORE_EXPORT CopyJob *copy(const QList<QUrl> &src, const QUrl &dest, JobFlags flags = DefaultFlags);
270
271/**
272 * Moves a file or directory @p src to the given destination @p dest.
273 *
274 * @param src the file or directory to copy
275 * @param dest the destination
276 * @param flags move() supports HideProgressInfo and Overwrite.
277 * Note: Overwrite has the meaning of both "write into existing directories" and
278 * "overwrite existing files". However if "dest" exists, then src is copied
279 * into a subdir of dest, just like "cp" does.
280 * @return the job handling the operation
281 * @see copy()
282 * @see moveAs()
283 */
284KIOCORE_EXPORT CopyJob *move(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags);
285/**
286 * Moves a file or directory @p src to the given destination @p dest. Unlike move()
287 * this operation will not move @p src into @p dest when @p dest exists: it will
288 * either fail, or move the contents of @p src into it if Overwrite is set.
289 *
290 * @param src the file or directory to copy
291 * @param dest the destination
292 * @param flags moveAs() supports HideProgressInfo and Overwrite.
293 * Note: Overwrite has the meaning of both "write into existing directories" and
294 * "overwrite existing files".
295 * @return the job handling the operation
296 * @see copyAs()
297 */
298KIOCORE_EXPORT CopyJob *moveAs(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags);
299/**
300 * Moves a list of files or directories @p src to the given destination @p dest.
301 *
302 * @param src the list of files or directories to copy
303 * @param dest the destination
304 * @param flags move() 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 * @return the job handling the operation
309 * @see copy()
310 */
311KIOCORE_EXPORT CopyJob *move(const QList<QUrl> &src, const QUrl &dest, JobFlags flags = DefaultFlags);
312
313/**
314 * Create a link.
315 * If the protocols and hosts are the same, a Unix symlink will be created.
316 * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
317 *
318 * @param src The existing file or directory, 'target' of the link.
319 * @param destDir Destination directory where the link will be created.
320 * @param flags link() supports HideProgressInfo only
321 * @return the job handling the operation
322 */
323KIOCORE_EXPORT CopyJob *link(const QUrl &src, const QUrl &destDir, JobFlags flags = DefaultFlags);
324
325/**
326 * Create several links
327 * If the protocols and hosts are the same, a Unix symlink will be created.
328 * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
329 *
330 * @param src The existing files or directories, 'targets' of the link.
331 * @param destDir Destination directory where the links will be created.
332 * @param flags link() supports HideProgressInfo only
333 * @return the job handling the operation
334 * @see link()
335 */
336KIOCORE_EXPORT CopyJob *link(const QList<QUrl> &src, const QUrl &destDir, JobFlags flags = DefaultFlags);
337
338/**
339 * Create a link. Unlike link() this operation will fail when @p dest is an existing
340 * directory rather than the final name for the link.
341 * If the protocols and hosts are the same, a Unix symlink will be created.
342 * Otherwise, a .desktop file of Type Link and pointing to the src URL will be created.
343 *
344 * @param src The existing file or directory, 'target' of the link.
345 * @param dest Destination (i.e. the final symlink)
346 * @param flags linkAs() supports HideProgressInfo only
347 * @return the job handling the operation
348 * @see link ()
349 * @see copyAs()
350 */
351KIOCORE_EXPORT CopyJob *linkAs(const QUrl &src, const QUrl &dest, JobFlags flags = DefaultFlags);
352
353/**
354 * Trash a file or directory.
355 * This is currently only supported for local files and directories.
356 * Use QUrl::fromLocalFile to create a URL from a local file path.
357 *
358 * @param src file to delete
359 * @param flags trash() supports HideProgressInfo only
360 * @return the job handling the operation
361 */
362KIOCORE_EXPORT CopyJob *trash(const QUrl &src, JobFlags flags = DefaultFlags);
363
364/**
365 * Trash a list of files or directories.
366 * This is currently only supported for local files and directories.
367 *
368 * @param src the files to delete
369 * @param flags trash() supports HideProgressInfo only
370 * @return the job handling the operation
371 */
372KIOCORE_EXPORT CopyJob *trash(const QList<QUrl> &src, JobFlags flags = DefaultFlags);
373
374}
375
376#endif
377

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