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 | |
35 | namespace 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 | |