1// -*- c++ -*-
2/* This file is part of the KDE libraries
3 Copyright (C) 2000 Stephan Kulow <coolo@kde.org>
4 2000-2009 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_JOBCLASSES_H
23#define KIO_JOBCLASSES_H
24
25#include <QtCore/QObject>
26#include <QtCore/QLinkedList> // KDE5: remove
27#include <QtCore/QStringList>
28
29#include <kurl.h>
30#include <kio/global.h>
31#include <kio/udsentry.h>
32
33#include <kcompositejob.h>
34
35namespace KIO {
36
37 /**
38 * Flags for the job properties.
39 * Not all flags are supported in all cases. Please see documentation of
40 * the calling function!
41 */
42 enum JobFlag {
43 /**
44 * Show the progress info GUI, no Resume and no Overwrite
45 */
46 DefaultFlags = 0,
47
48 /**
49 * Hide progress information dialog, i.e. don't show a GUI.
50 */
51 HideProgressInfo = 1,
52
53 /**
54 * When set, automatically append to the destination file if it exists already.
55 * WARNING: this is NOT the builtin support for offering the user to resume a previous
56 * partial download. The Resume option is much less used, it allows to append
57 * to an existing file.
58 * This is used by KIO::put(), KIO::file_copy(), KIO::file_move().
59 */
60 Resume = 2,
61
62 /**
63 * When set, automatically overwrite the destination if it exists already.
64 * This is used by KIO::rename(), KIO::put(), KIO::file_copy(), KIO::file_move(), KIO::symlink().
65 * Otherwise the operation will fail with ERR_FILE_ALREADY_EXIST or ERR_DIR_ALREADY_EXIST.
66 */
67 Overwrite = 4
68 };
69 Q_DECLARE_FLAGS(JobFlags, JobFlag)
70 Q_DECLARE_OPERATORS_FOR_FLAGS(JobFlags)
71
72 class JobUiDelegate;
73
74 class JobPrivate;
75 /**
76 * The base class for all jobs.
77 * For all jobs created in an application, the code looks like
78 *
79 * \code
80 * KIO::Job * job = KIO::someoperation( some parameters );
81 * connect( job, SIGNAL( result( KJob * ) ),
82 * this, SLOT( slotResult( KJob * ) ) );
83 * \endcode
84 * (other connects, specific to the job)
85 *
86 * And slotResult is usually at least:
87 *
88 * \code
89 * if ( job->error() )
90 * job->ui()->showErrorMessage();
91 * \endcode
92 * @see KIO::Scheduler
93 */
94 class KIO_EXPORT Job : public KCompositeJob {
95 Q_OBJECT
96
97 protected:
98 Job();
99 Job(JobPrivate &dd);
100
101 public:
102 virtual ~Job();
103 void start() {} // Since KIO autostarts its jobs
104
105 /**
106 * Retrieves the UI delegate of this job.
107 *
108 * This method is basically a convenience for static_cast<KIO::JobUiDelegate*>(uiDelegate()).
109 *
110 * @return the delegate used by the job to communicate with the UI
111 */
112 JobUiDelegate *ui() const;
113
114 protected:
115 /**
116 * Abort this job.
117 * This kills all subjobs and deletes the job.
118 *
119 */
120 virtual bool doKill();
121
122 /**
123 * Suspend this job
124 * @see resume
125 */
126 virtual bool doSuspend();
127
128 /**
129 * Resume this job
130 * @see suspend
131 */
132 virtual bool doResume();
133
134 public:
135 /**
136 * Converts an error code and a non-i18n error message into an
137 * error message in the current language. The low level (non-i18n)
138 * error message (usually a url) is put into the translated error
139 * message using %1.
140 *
141 * Example for errid == ERR_CANNOT_OPEN_FOR_READING:
142 * \code
143 * i18n( "Could not read\n%1" ).arg( errortext );
144 * \endcode
145 * Use this to display the error yourself, but for a dialog box
146 * use ui()->showErrorMessage(). Do not call it if error()
147 * is not 0.
148 * @return the error message and if there is no error, a message
149 * telling the user that the app is broken, so check with
150 * error() whether there is an error
151 */
152 QString errorString() const;
153
154 /**
155 * Converts an error code and a non-i18n error message into i18n
156 * strings suitable for presentation in a detailed error message box.
157 *
158 * @param reqUrl the request URL that generated this error message
159 * @param method the method that generated this error message
160 * (unimplemented)
161 * @return the following strings: caption, error + description,
162 * causes+solutions
163 */
164 QStringList detailedErrorStrings(const KUrl *reqUrl = 0L,
165 int method = -1) const;
166
167 /**
168 * Display a dialog box to inform the user of the error given by
169 * this job.
170 * Only call if error is not 0, and only in the slot connected
171 * to result.
172 * @param parent the parent widget for the dialog box, can be 0 for
173 * top-level
174 * @deprecated you should use job->ui()->setWindow(parent)
175 * and job->ui()->showErrorMessage() instead
176 */
177#ifndef KDE_NO_DEPRECATED
178 KDE_DEPRECATED void showErrorDialog( QWidget *parent = 0 );
179#endif
180
181 /**
182 * Returns whether the user should be asked about things when the job
183 * is unsure, like whether to overwrite existing files etc.
184 * @return true if user interactions are enabled (true by default),
185 * false if setUiDelegate(0) was called.
186 * @see setUiDelegate()
187 */
188 bool isInteractive() const;
189
190 /**
191 * Set the parent Job.
192 * One example use of this is when FileCopyJob calls RenameDialog::open,
193 * it must pass the correct progress ID of the parent CopyJob
194 * (to hide the progress dialog).
195 * You can set the parent job only once. By default a job does not
196 * have a parent job.
197 * @param parentJob the new parent job
198 */
199 void setParentJob( Job* parentJob );
200
201 /**
202 * Returns the parent job, if there is one.
203 * @return the parent job, or 0 if there is none
204 * @see setParentJob
205 */
206 Job* parentJob() const;
207
208 /**
209 * Set meta data to be sent to the slave, replacing existing
210 * meta data.
211 * @param metaData the meta data to set
212 * @see addMetaData()
213 * @see mergeMetaData()
214 */
215 void setMetaData( const KIO::MetaData &metaData);
216
217 /**
218 * Add key/value pair to the meta data that is sent to the slave.
219 * @param key the key of the meta data
220 * @param value the value of the meta data
221 * @see setMetaData()
222 * @see mergeMetaData()
223 */
224 void addMetaData(const QString &key, const QString &value);
225
226 /**
227 * Add key/value pairs to the meta data that is sent to the slave.
228 * If a certain key already existed, it will be overridden.
229 * @param values the meta data to add
230 * @see setMetaData()
231 * @see mergeMetaData()
232 */
233 void addMetaData(const QMap<QString,QString> &values);
234
235 /**
236 * Add key/value pairs to the meta data that is sent to the slave.
237 * If a certain key already existed, it will remain unchanged.
238 * @param values the meta data to merge
239 * @see setMetaData()
240 * @see addMetaData()
241 */
242 void mergeMetaData(const QMap<QString,QString> &values);
243
244 /**
245 * @internal. For the scheduler. Do not use.
246 */
247 MetaData outgoingMetaData() const;
248
249 /**
250 * Get meta data received from the slave.
251 * (Valid when first data is received and/or slave is finished)
252 * @return the job's meta data
253 */
254 MetaData metaData() const;
255
256 /**
257 * Query meta data received from the slave.
258 * (Valid when first data is received and/or slave is finished)
259 * @param key the key of the meta data to retrieve
260 * @return the value of the meta data, or QString() if the
261 * @p key does not exist
262 */
263 QString queryMetaData(const QString &key);
264
265 protected:
266
267 Q_SIGNALS:
268 /**
269 * @deprecated. Don't use !
270 * Emitted when the job is canceled.
271 * Signal result() is emitted as well, and error() is,
272 * in this case, ERR_USER_CANCELED.
273 * @param job the job that emitted this signal
274 */
275 void canceled( KJob *job );
276
277 /**
278 * Emitted when the slave successfully connected to the host.
279 * There is no guarantee the slave will send this, and this is
280 * currently unused (in the applications).
281 * @param job the job that emitted this signal
282 */
283 void connected( KIO::Job *job );
284
285 protected:
286 /**
287 * Add a job that has to be finished before a result
288 * is emitted. This has obviously to be called before
289 * the finish signal is emitted by the slave.
290 *
291 * @param job the subjob to add
292 */
293 virtual bool addSubjob( KJob *job );
294
295 /**
296 * Mark a sub job as being done.
297 *
298 * KDE4 change: this doesn't terminate the parent job anymore, call emitResult to do that.
299 *
300 * @param job the subjob to remove
301 */
302 virtual bool removeSubjob( KJob *job );
303
304 private:
305 /**
306 * Forward signal from subjob.
307 * @param job the subjob
308 * @param speed the speed in bytes/s
309 * @see speed()
310 */
311 Q_PRIVATE_SLOT(d_func(), void slotSpeed( KJob *job, unsigned long speed ))
312 Q_DECLARE_PRIVATE(Job)
313 };
314
315 class SimpleJobPrivate;
316 /**
317 * A simple job (one url and one command).
318 * This is the base class for all jobs that are scheduled.
319 * Other jobs are high-level jobs (CopyJob, DeleteJob, FileCopyJob...)
320 * that manage subjobs but aren't scheduled directly.
321 */
322 class KIO_EXPORT SimpleJob : public KIO::Job {
323 Q_OBJECT
324
325 public:
326 ~SimpleJob();
327
328 protected:
329 /**
330 * Suspend this job
331 * @see resume
332 */
333 virtual bool doSuspend();
334
335 /**
336 * Resume this job
337 * @see suspend
338 */
339 virtual bool doResume();
340
341 /**
342 * Abort job.
343 * This kills all subjobs and deletes the job.
344 */
345 virtual bool doKill();
346
347 public:
348 /**
349 * Returns the SimpleJob's URL
350 * @return the url
351 */
352 const KUrl& url() const;
353
354 /**
355 * Abort job.
356 * Suspends slave to be reused by another job for the same request.
357 */
358 virtual void putOnHold();
359
360 /**
361 * Discard suspended slave.
362 */
363 static void removeOnHold();
364
365 /**
366 * Returns true when redirections are handled internally, the default.
367 *
368 * @since 4.4
369 */
370 bool isRedirectionHandlingEnabled() const;
371
372 /**
373 * Set @p handle to false to prevent the internal handling of redirections.
374 *
375 * When this flag is set, redirection requests are simply forwarded to the
376 * caller instead of being handled internally.
377 *
378 * @since 4.4
379 */
380 void setRedirectionHandlingEnabled(bool handle);
381
382 public Q_SLOTS:
383 /**
384 * @internal
385 * Called on a slave's error.
386 * Made public for the scheduler.
387 */
388 void slotError( int , const QString & );
389
390 protected Q_SLOTS:
391 /**
392 * Called when the slave marks the job
393 * as finished.
394 */
395 virtual void slotFinished( );
396
397 /**
398 * @internal
399 * Called on a slave's warning.
400 */
401 virtual void slotWarning( const QString & );
402
403 /**
404 * MetaData from the slave is received.
405 * @param _metaData the meta data
406 * @see metaData()
407 */
408 virtual void slotMetaData( const KIO::MetaData &_metaData);
409
410 protected:
411 /*
412 * Allow jobs that inherit SimpleJob and are aware
413 * of redirections to store the SSL session used.
414 * Retrieval is handled by SimpleJob::start
415 * @param m_redirectionURL Reference to redirection URL,
416 * used instead of m_url if not empty
417 */
418 void storeSSLSessionFromJob(const KUrl &m_redirectionURL);
419
420 /**
421 * Creates a new simple job. You don't need to use this constructor,
422 * unless you create a new job that inherits from SimpleJob.
423 */
424 SimpleJob(SimpleJobPrivate &dd);
425 private:
426 Q_PRIVATE_SLOT(d_func(), void slotConnected())
427 Q_PRIVATE_SLOT(d_func(), void slotProcessedSize( KIO::filesize_t data_size ))
428 Q_PRIVATE_SLOT(d_func(), void slotSpeed( unsigned long speed ))
429 Q_PRIVATE_SLOT(d_func(), void slotTotalSize( KIO::filesize_t data_size ))
430 Q_PRIVATE_SLOT(d_func(), void _k_slotSlaveInfoMessage(const QString&))
431
432 Q_DECLARE_PRIVATE(SimpleJob)
433 };
434
435 class StatJobPrivate;
436 /**
437 * A KIO job that retrieves information about a file or directory.
438 * @see KIO::stat()
439 */
440 class KIO_EXPORT StatJob : public SimpleJob {
441
442 Q_OBJECT
443
444 public:
445 enum StatSide {
446 SourceSide,
447 DestinationSide
448 };
449
450 ~StatJob();
451
452 /**
453 * A stat() can have two meanings. Either we want to read from this URL,
454 * or to check if we can write to it. First case is "source", second is "dest".
455 * It is necessary to know what the StatJob is for, to tune the kioslave's behavior
456 * (e.g. with FTP).
457 * @param side SourceSide or DestinationSide
458 */
459 void setSide(StatSide side);
460
461 /**
462 * A stat() can have two meanings. Either we want to read from this URL,
463 * or to check if we can write to it. First case is "source", second is "dest".
464 * It is necessary to know what the StatJob is for, to tune the kioslave's behavior
465 * (e.g. with FTP).
466 * @param source true for "source" mode, false for "dest" mode
467 */
468#ifndef KDE_NO_DEPRECATED
469 KDE_DEPRECATED void setSide( bool source );
470#endif
471
472 /**
473 * Selects the level of @p details we want.
474 * By default this is 2 (all details wanted, including modification time, size, etc.),
475 * setDetails(1) is used when deleting: we don't need all the information if it takes
476 * too much time, no need to follow symlinks etc.
477 * setDetails(0) is used for very simple probing: we'll only get the answer
478 * "it's a file or a directory, or it doesn't exist". This is used by KRun.
479 * @param details 2 for all details, 1 for simple, 0 for very simple
480 */
481 void setDetails( short int details );
482
483 /**
484 * @brief Result of the stat operation.
485 * Call this in the slot connected to result,
486 * and only after making sure no error happened.
487 * @return the result of the stat
488 */
489 const UDSEntry & statResult() const;
490
491 /**
492 * @brief most local URL
493 * Call this in the slot connected to result,
494 * and only after making sure no error happened.
495 * @return the most local URL for the URL we were stat'ing.
496 *
497 * Sample usage:
498 * <code>
499 * KIO::StatJob* job = KIO::mostLocalUrl("desktop:/foo");
500 * job->ui()->setWindow(this);
501 * connect(job, SIGNAL(result(KJob*)), this, SLOT(slotMostLocalUrlResult(KJob*)));
502 * [...]
503 * // and in the slot
504 * if (job->error()) {
505 * [...] // doesn't exist
506 * } else {
507 * const KUrl localUrl = job->mostLocalUrl();
508 * // localUrl = file:///$HOME/Desktop/foo
509 * [...]
510 * }
511 *
512 * \since 4.4
513 */
514 KUrl mostLocalUrl() const;
515
516 Q_SIGNALS:
517 /**
518 * Signals a redirection.
519 * Use to update the URL shown to the user.
520 * The redirection itself is handled internally.
521 * @param job the job that is redirected
522 * @param url the new url
523 */
524 void redirection( KIO::Job *job, const KUrl &url );
525
526 /**
527 * Signals a permanent redirection.
528 * The redirection itself is handled internally.
529 * @param job the job that is redirected
530 * @param fromUrl the original URL
531 * @param toUrl the new URL
532 */
533 void permanentRedirection( KIO::Job *job, const KUrl &fromUrl, const KUrl &toUrl );
534
535 protected Q_SLOTS:
536 virtual void slotFinished();
537 virtual void slotMetaData( const KIO::MetaData &_metaData);
538 protected:
539 StatJob(StatJobPrivate &dd);
540
541 private:
542 Q_PRIVATE_SLOT(d_func(), void slotStatEntry( const KIO::UDSEntry & entry ))
543 Q_PRIVATE_SLOT(d_func(), void slotRedirection( const KUrl &url))
544 Q_DECLARE_PRIVATE(StatJob)
545 };
546
547 class FileCopyJobPrivate;
548 class TransferJobPrivate;
549 /**
550 * The transfer job pumps data into and/or out of a Slave.
551 * Data is sent to the slave on request of the slave ( dataReq).
552 * If data coming from the slave can not be handled, the
553 * reading of data from the slave should be suspended.
554 */
555 class KIO_EXPORT TransferJob : public SimpleJob {
556 Q_OBJECT
557
558 public:
559 ~TransferJob();
560
561 /**
562 * Sets the modification time of the file to be created (by KIO::put)
563 * Note that some kioslaves might ignore this.
564 */
565 void setModificationTime( const QDateTime& mtime );
566
567 /**
568 * Checks whether we got an error page. This currently only happens
569 * with HTTP urls. Call this from your slot connected to result().
570 *
571 * @return true if we got an (HTML) error page from the server
572 * instead of what we asked for.
573 */
574 bool isErrorPage() const;
575
576 /**
577 * Enable the async data mode.
578 * When async data is enabled, data should be provided to the job by
579 * calling sendAsyncData() instead of returning data in the
580 * dataReq() signal.
581 */
582 void setAsyncDataEnabled(bool enabled);
583
584 /**
585 * Provide data to the job when async data is enabled.
586 * Should be called exactly once after receiving a dataReq signal
587 * Sending an empty block indicates end of data.
588 */
589 void sendAsyncData(const QByteArray &data);
590
591 /**
592 * When enabled, the job reports the amount of data that has been sent,
593 * instead of the amount of data that that has been received.
594 * @see slotProcessedSize
595 * @see slotSpeed
596 * @deprecated not needed, this is false for KIO::get and true for KIO::put,
597 * automatically since KDE-4.2.1
598 */
599#ifndef KDE_NO_DEPRECATED
600 KDE_DEPRECATED void setReportDataSent(bool enabled);
601#endif
602
603 /**
604 * Returns whether the job reports the amount of data that has been
605 * sent (true), or whether the job reports the amount of data that
606 * has been received (false)
607 * @deprecated not needed, this is false for KIO::get and true for KIO::put,
608 * automatically since KDE-4.2.1 (and not useful as public API)
609 */
610#ifndef KDE_NO_DEPRECATED
611 KDE_DEPRECATED bool reportDataSent() const;
612#endif
613
614 /**
615 * Call this in the slot connected to result,
616 * and only after making sure no error happened.
617 * @return the mimetype of the URL
618 */
619 QString mimetype() const;
620
621 /**
622 * Set the total size of data that we are going to send
623 * in a put job. Helps getting proper progress information.
624 * @since 4.2.1
625 */
626 void setTotalSize(KIO::filesize_t bytes);
627
628 protected:
629 /**
630 * Called when m_subJob finishes.
631 * @param job the job that finished
632 */
633 virtual void slotResult( KJob *job );
634
635 /**
636 * Reimplemented for internal reasons
637 */
638 virtual bool doResume();
639
640 Q_SIGNALS:
641 /**
642 * Data from the slave has arrived.
643 * @param job the job that emitted this signal
644 * @param data data received from the slave.
645 *
646 * End of data (EOD) has been reached if data.size() == 0, however, you
647 * should not be certain of data.size() == 0 ever happening (e.g. in case
648 * of an error), so you should rely on result() instead.
649 */
650 void data( KIO::Job *job, const QByteArray &data );
651
652 /**
653 * Request for data.
654 * Please note, that you shouldn't put too large chunks
655 * of data in it as this requires copies within the frame
656 * work, so you should rather split the data you want
657 * to pass here in reasonable chunks (about 1MB maximum)
658 *
659 * @param job the job that emitted this signal
660 * @param data buffer to fill with data to send to the
661 * slave. An empty buffer indicates end of data. (EOD)
662 */
663 void dataReq( KIO::Job *job, QByteArray &data );
664
665 /**
666 * Signals a redirection.
667 * Use to update the URL shown to the user.
668 * The redirection itself is handled internally.
669 * @param job the job that emitted this signal
670 * @param url the new URL
671 */
672 void redirection( KIO::Job *job, const KUrl &url );
673
674 /**
675 * Signals a permanent redirection.
676 * The redirection itself is handled internally.
677 * @param job the job that emitted this signal
678 * @param fromUrl the original URL
679 * @param toUrl the new URL
680 */
681 void permanentRedirection( KIO::Job *job, const KUrl &fromUrl, const KUrl &toUrl );
682
683 /**
684 * Mimetype determined.
685 * @param job the job that emitted this signal
686 * @param type the mime type
687 */
688 void mimetype( KIO::Job *job, const QString &type );
689
690 /**
691 * @internal
692 * Emitted if the "put" job found an existing partial file
693 * (in which case offset is the size of that file)
694 * and emitted by the "get" job if it supports resuming to
695 * the given offset - in this case @p offset is unused)
696 */
697 void canResume( KIO::Job *job, KIO::filesize_t offset );
698
699
700 protected Q_SLOTS:
701 virtual void slotRedirection( const KUrl &url);
702 virtual void slotFinished();
703 virtual void slotData( const QByteArray &data);
704 virtual void slotDataReq();
705 virtual void slotMimetype( const QString &mimetype );
706 virtual void slotMetaData( const KIO::MetaData &_metaData);
707
708 protected:
709 TransferJob(TransferJobPrivate &dd);
710 private:
711 Q_PRIVATE_SLOT(d_func(), void slotErrorPage())
712 Q_PRIVATE_SLOT(d_func(), void slotCanResume( KIO::filesize_t offset ))
713 Q_PRIVATE_SLOT(d_func(), void slotPostRedirection())
714 Q_PRIVATE_SLOT(d_func(), void slotNeedSubUrlData())
715 Q_PRIVATE_SLOT(d_func(), void slotSubUrlData(KIO::Job*, const QByteArray &))
716 Q_PRIVATE_SLOT(d_func(), void slotDataReqFromDevice())
717 Q_DECLARE_PRIVATE(TransferJob)
718
719 // A FileCopyJob may control one or more TransferJobs
720 friend class FileCopyJob;
721 friend class FileCopyJobPrivate;
722 };
723
724 class StoredTransferJobPrivate;
725 /**
726 * StoredTransferJob is a TransferJob (for downloading or uploading data) that
727 * also stores a QByteArray with the data, making it simpler to use than the
728 * standard TransferJob.
729 *
730 * For KIO::storedGet it puts the data into the member QByteArray, so the user
731 * of this class can get hold of the whole data at once by calling data()
732 * when the result signal is emitted.
733 * You should only use StoredTransferJob to download data if you cannot
734 * process the data by chunks while it's being downloaded, since storing
735 * everything in a QByteArray can potentially require a lot of memory.
736 *
737 * For KIO::storedPut the user of this class simply provides the bytearray from
738 * the start, and the job takes care of uploading it.
739 * You should only use StoredTransferJob to upload data if you cannot
740 * provide the in chunks while it's being uploaded, since storing
741 * everything in a QByteArray can potentially require a lot of memory.
742 */
743 class KIO_EXPORT StoredTransferJob : public KIO::TransferJob {
744 Q_OBJECT
745
746 public:
747 ~StoredTransferJob();
748
749 /**
750 * Set data to be uploaded. This is for put jobs.
751 * Automatically called by KIO::storedPut(const QByteArray &, ...),
752 * do not call this yourself.
753 */
754 void setData( const QByteArray& arr );
755
756 /**
757 * Get hold of the downloaded data. This is for get jobs.
758 * You're supposed to call this only from the slot connected to the result() signal.
759 */
760 QByteArray data() const;
761
762 protected:
763 StoredTransferJob(StoredTransferJobPrivate &dd);
764 private:
765 Q_PRIVATE_SLOT(d_func(), void slotStoredData( KIO::Job *job, const QByteArray &data ))
766 Q_PRIVATE_SLOT(d_func(), void slotStoredDataReq( KIO::Job *job, QByteArray &data ))
767
768 Q_DECLARE_PRIVATE(StoredTransferJob)
769 };
770
771 class MultiGetJobPrivate;
772 /**
773 * The MultiGetJob is a TransferJob that allows you to get
774 * several files from a single server. Don't create directly,
775 * but use KIO::multi_get() instead.
776 * @see KIO::multi_get()
777 */
778 class KIO_EXPORT MultiGetJob : public TransferJob {
779 Q_OBJECT
780
781 public:
782 virtual ~MultiGetJob();
783
784 /**
785 * Get an additional file.
786 *
787 * @param id the id of the file
788 * @param url the url of the file to get
789 * @param metaData the meta data for this request
790 */
791 void get(long id, const KUrl &url, const MetaData &metaData);
792
793 Q_SIGNALS:
794 /**
795 * Data from the slave has arrived.
796 * @param id the id of the request
797 * @param data data received from the slave.
798 * End of data (EOD) has been reached if data.size() == 0
799 */
800 void data( long id, const QByteArray &data);
801
802 /**
803 * Mimetype determined
804 * @param id the id of the request
805 * @param type the mime type
806 */
807 void mimetype( long id, const QString &type );
808
809 /**
810 * File transfer completed.
811 *
812 * When all files have been processed, result(KJob *) gets
813 * emitted.
814 * @param id the id of the request
815 */
816 void result( long id);
817
818 protected Q_SLOTS:
819 virtual void slotRedirection( const KUrl &url);
820 virtual void slotFinished();
821 virtual void slotData( const QByteArray &data);
822 virtual void slotMimetype( const QString &mimetype );
823
824 protected:
825 MultiGetJob(MultiGetJobPrivate &dd);
826 private:
827 Q_DECLARE_PRIVATE(MultiGetJob)
828 };
829
830 class MimetypeJobPrivate;
831 /**
832 * A MimetypeJob is a TransferJob that allows you to get
833 * the mime type of an URL. Don't create directly,
834 * but use KIO::mimetype() instead.
835 * @see KIO::mimetype()
836 */
837 class KIO_EXPORT MimetypeJob : public TransferJob {
838 Q_OBJECT
839
840 public:
841 ~MimetypeJob();
842
843 protected Q_SLOTS:
844 virtual void slotFinished( );
845 protected:
846 MimetypeJob(MimetypeJobPrivate &dd);
847 private:
848 Q_DECLARE_PRIVATE(MimetypeJob)
849 };
850
851 /**
852 * The FileCopyJob copies data from one place to another.
853 * @see KIO::file_copy()
854 * @see KIO::file_move()
855 */
856 class KIO_EXPORT FileCopyJob : public Job {
857 Q_OBJECT
858
859 public:
860 ~FileCopyJob();
861 /**
862 * If you know the size of the source file, call this method
863 * to inform this job. It will be displayed in the "resume" dialog.
864 * @param size the size of the source file
865 */
866 void setSourceSize(KIO::filesize_t size);
867
868 /**
869 * Sets the modification time of the file
870 *
871 * Note that this is ignored if a direct copy (SlaveBase::copy) can be done,
872 * in which case the mtime of the source is applied to the destination (if the protocol
873 * supports the concept).
874 */
875 void setModificationTime( const QDateTime& mtime );
876
877 /**
878 * Returns the source URL.
879 * @return the source URL
880 */
881 KUrl srcUrl() const;
882
883 /**
884 * Returns the destination URL.
885 * @return the destination URL
886 */
887 KUrl destUrl() const;
888
889 bool doSuspend();
890 bool doResume();
891
892 Q_SIGNALS:
893 /**
894 * Mimetype determined during a file copy.
895 * This is never emitted during a move, and might not be emitted during
896 * a file copy, depending on the slave. But when a get and a put are
897 * being used (which is the common case), this signal forwards the
898 * mimetype information from the get job.
899 *
900 * @param job the job that emitted this signal
901 * @param type the mime type
902 */
903 void mimetype( KIO::Job *job, const QString &type );
904
905 protected Q_SLOTS:
906 /**
907 * Called whenever a subjob finishes.
908 * @param job the job that emitted this signal
909 */
910 virtual void slotResult( KJob *job );
911
912 protected:
913 FileCopyJob(FileCopyJobPrivate &dd);
914
915 private:
916 Q_PRIVATE_SLOT(d_func(), void slotStart())
917 Q_PRIVATE_SLOT(d_func(), void slotData( KIO::Job *, const QByteArray &data))
918 Q_PRIVATE_SLOT(d_func(), void slotDataReq( KIO::Job *, QByteArray &data))
919 Q_PRIVATE_SLOT(d_func(), void slotMimetype( KIO::Job*, const QString& type ))
920 Q_PRIVATE_SLOT(d_func(), void slotProcessedSize( KJob *job, qulonglong size ))
921 Q_PRIVATE_SLOT(d_func(), void slotTotalSize( KJob *job, qulonglong size ))
922 Q_PRIVATE_SLOT(d_func(), void slotPercent( KJob *job, unsigned long pct ))
923 Q_PRIVATE_SLOT(d_func(), void slotCanResume( KIO::Job *job, KIO::filesize_t offset ))
924
925 Q_DECLARE_PRIVATE(FileCopyJob)
926 };
927
928 class ListJobPrivate;
929 /**
930 * A ListJob is allows you to get the get the content of a directory.
931 * Don't create the job directly, but use KIO::listRecursive() or
932 * KIO::listDir() instead.
933 * @see KIO::listRecursive()
934 * @see KIO::listDir()
935 */
936 class KIO_EXPORT ListJob : public SimpleJob {
937 Q_OBJECT
938
939 public:
940 ~ListJob();
941
942 /**
943 * Returns the ListJob's redirection URL. This will be invalid if there
944 * was no redirection.
945 * @return the redirection url
946 */
947 const KUrl& redirectionUrl() const;
948
949 /**
950 * Do not apply any KIOSK restrictions to this job.
951 */
952 void setUnrestricted(bool unrestricted);
953
954 Q_SIGNALS:
955 /**
956 * This signal emits the entry found by the job while listing.
957 * The progress signals aren't specific to ListJob. It simply
958 * uses SimpleJob's processedSize (number of entries listed) and
959 * totalSize (total number of entries, if known),
960 * as well as percent.
961 * @param job the job that emitted this signal
962 * @param list the list of UDSEntries
963 */
964 void entries( KIO::Job *job, const KIO::UDSEntryList& list); // TODO KDE5: use KIO::ListJob* argument to avoid casting
965
966 /**
967 * This signal is emitted when a sub-directory could not be listed.
968 * The job keeps going, thus doesn't result in an overall error.
969 * @param job the job that emitted the signal
970 * @param subJob the job listing a sub-directory, which failed. Use
971 * url(), error() and errorText() on that job to find
972 * out more.
973 */
974 void subError( KIO::ListJob *job, KIO::ListJob *subJob );
975
976 /**
977 * Signals a redirection.
978 * Use to update the URL shown to the user.
979 * The redirection itself is handled internally.
980 * @param job the job that is redirected
981 * @param url the new url
982 */
983 void redirection( KIO::Job *job, const KUrl &url );
984
985 /**
986 * Signals a permanent redirection.
987 * The redirection itself is handled internally.
988 * @param job the job that emitted this signal
989 * @param fromUrl the original URL
990 * @param toUrl the new URL
991 */
992 void permanentRedirection( KIO::Job *job, const KUrl &fromUrl, const KUrl &toUrl );
993
994 protected Q_SLOTS:
995 virtual void slotFinished( );
996 virtual void slotMetaData( const KIO::MetaData &_metaData);
997 virtual void slotResult( KJob *job );
998
999 protected:
1000 ListJob(ListJobPrivate &dd);
1001
1002 private:
1003 Q_PRIVATE_SLOT(d_func(), void slotListEntries( const KIO::UDSEntryList& list ))
1004 Q_PRIVATE_SLOT(d_func(), void slotRedirection( const KUrl &url ))
1005 Q_PRIVATE_SLOT(d_func(), void gotEntries( KIO::Job * subjob, const KIO::UDSEntryList& list ))
1006 Q_DECLARE_PRIVATE(ListJob)
1007 };
1008
1009 class SpecialJobPrivate;
1010 /**
1011 * A class that sends a special command to an ioslave.
1012 * This allows you to send a binary blob to an ioslave and handle
1013 * its responses. The ioslave will receive the binary data as an
1014 * argument to the "special" function (inherited from SlaveBase::special()).
1015 *
1016 * Use this only on ioslaves that belong to your application. Sending
1017 * special commands to other ioslaves may cause unexpected behaviour.
1018 *
1019 * @see KIO::special
1020 */
1021 class KIO_EXPORT SpecialJob : public TransferJob
1022 {
1023 Q_OBJECT
1024 public:
1025 /**
1026 * Creates a KIO::SpecialJob.
1027 *
1028 * @param url the URL to be passed to the ioslave
1029 * @param data the data to be sent to the SlaveBase::special() function.
1030 */
1031 explicit SpecialJob(const KUrl &url, const QByteArray &data = QByteArray());
1032
1033 /**
1034 * Sets the QByteArray that is passed to SlaveBase::special() on
1035 * the ioslave.
1036 */
1037 void setArguments(const QByteArray &data);
1038
1039 /**
1040 * Returns the QByteArray data that will be sent (or has been sent) to the
1041 * ioslave.
1042 */
1043 QByteArray arguments() const;
1044
1045 public:
1046 ~SpecialJob();
1047
1048 private:
1049 Q_DECLARE_PRIVATE(SpecialJob)
1050 };
1051}
1052
1053#endif
1054