KIO

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

KDE's Doxygen guidelines are available online.