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