kio Library: KIO::Job Class Reference (kio Library)

| # kio Library API Documentation
Overview | Class Hierarchy | Classes | Classes (annotated) | Members | Namespaces | Source Files

# KIO::Job Class Reference

The base class for all jobs. More...

`#include <jobclasses.h>`

Inheritance diagram for KIO::Job:

[legend]
Collaboration diagram for KIO::Job:

[legend]
List of all members.

## Signals
void | result (KIO::Job *job)
void | canceled (KIO::Job *job)
void | infoMessage (KIO::Job *job, const QString &msg)
void | connected (KIO::Job *job)
void | percent (KIO::Job *job, unsigned long percent)
void | totalSize (KIO::Job *job, KIO::filesize_t size)
void | processedSize (KIO::Job *job, KIO::filesize_t size)
void | speed (KIO::Job *job, unsigned long bytes_per_second)
## Public Member Functions
virtual void | kill (bool quietly=true)
int | error () const
int | progressId () const
const QString & | errorText () const
QString | errorString () const
QStringList | detailedErrorStrings (const KURL *reqUrl=0L, int method=-1) const
void | showErrorDialog (QWidget *parent=0L)
void | setAutoErrorHandlingEnabled (bool enable, QWidget *parentWidget=0)
bool | isAutoErrorHandlingEnabled () const
void | setInteractive (bool enable)
bool | isInteractive () const
void | setWindow (QWidget *window)
QWidget * | window () const
void | setParentJob (Job *parentJob)
Job * | parentJob () const
void | setMetaData (const KIO::MetaData &metaData)
void | addMetaData (const QString &key, const QString &value)
void | addMetaData (const QMap< QString, QString > &values)
void | mergeMetaData (const QMap< QString, QString > &values)
MetaData | outgoingMetaData () const
MetaData | metaData () const
QString | queryMetaData (const QString &key)
KIO::filesize_t | getProcessedSize ()
## Protected Types
enum | { EF_TransferJobAsync = (1 << 0), EF_TransferJobNeedData = (1 << 1), EF_TransferJobDataSent = (1 << 2), EF_ListJobUnrestricted = (1 << 3) }
## Protected Slots
virtual void | slotResult (KIO::Job *job)
void | slotSpeed (KIO::Job *job, unsigned long bytes_per_second)
void | slotInfoMessage (KIO::Job *job, const QString &msg)
void | slotSpeedTimeout ()
## Protected Member Functions
| Job (bool showProgressInfo)
virtual void | addSubjob (Job *job, bool inheritMetaData=true)
virtual void | removeSubjob (Job *job)
void | removeSubjob (Job *job, bool mergeMetaData, bool emitResultIfLast)
void | emitPercent (KIO::filesize_t processedSize, KIO::filesize_t totalSize)
void | emitSpeed (unsigned long bytes_per_second)
void | emitResult ()
void | setProcessedSize (KIO::filesize_t size)
int & | extraFlags ()
virtual void | virtual_hook (int id, void *data)
## Protected Attributes
QPtrList< Job > | subjobs
int | m_error
QString | m_errorText
unsigned long | m_percent
int | m_progressId
QTimer * | m_speedTimer
QGuardedPtr< QWidget > | m_window
MetaData | m_outgoingMetaData
MetaData | m_incomingMetaData

## Detailed Description

The base class for all jobs.

For all jobs created in an application, the code looks like

       KIO::Job * job = KIO::someoperation( some parameters );
       connect( job, SIGNAL( result( KIO::Job * ) ),
                this, SLOT( slotResult( KIO::Job * ) ) );

(other connects, specific to the job)

And slotResult is usually at least:

      if ( job->error() )
          job->showErrorDialog( this or 0L  );

See also:
  KIO::Scheduler

  KIO::Slave

Definition at line 68 of file jobclasses.h.

## Member Function Documentation

virtual void KIO::Job::kill | ( | bool | quietly = `true` | ) | `[virtual]`

  | Abort this job. This kills all subjobs and deletes the job. Parameters:
  | quietly | if false, Job will emit signal result and ask kio_uiserver to close the progress window. `quietly` is set to true for subjobs. Whether applications should call with true or false depends on whether they rely on result being emitted or not.
Reimplemented in KIO::SimpleJob. Referenced by KImageFilePreview::clearPreview(), KIO::SimpleJob::kill(), and KIO::ProgressBase::slotStop().

int KIO::Job::error | ( |  | ) | const`[inline]`

| Returns the error code, if there has been an error. Only call this method from the slot connected to result(). Returns: the error code for this job, 0 if no error. Error codes are defined in KIO::Error. Definition at line 95 of file jobclasses.h. Referenced by KIO::DeleteJob::slotResult(), KIO::TransferJob::slotResult(), and KIO::ChmodJob::slotResult().

int KIO::Job::progressId | ( |  | ) | const`[inline]`

| Returns the progress id for this job. Returns: the progress id for this job, as returned by uiserver Definition at line 101 of file jobclasses.h.

const QString& KIO::Job::errorText | ( |  | ) | const`[inline]`

| Returns the error text if there has been an error. Only call if error is not 0. This is really internal, better use errorString or errorDialog. Returns: a string to help understand the error, usually the url related to the error. Only valid if error() is not 0. Definition at line 111 of file jobclasses.h.

KIO_EXPORT QString KIO::Job::errorString | ( |  | ) | const

| Converts an error code and a non-i18n error message into an error message in the current language. The low level (non-i18n) error message (usually a url) is put into the translated error message using 1. Example for errid == ERR_CANNOT_OPEN_FOR_READING:
       i18n( "Could not read\n%1" ).arg( errortext );
Use this to display the error yourself, but for a dialog box use Job::showErrorDialog. Do not call it if error() is not 0. Returns: the error message and if there is no error, a message telling the user that the app is broken, so check with error() whether there is an error Definition at line 195 of file global.cpp. References KIO::buildErrorString().

KIO_EXPORT QStringList KIO::Job::detailedErrorStrings | ( | const KURL * | reqUrl = `0L`,
|  | int | method = `-1`
| ) | const

  | Converts an error code and a non-i18n error message into i18n strings suitable for presentation in a detailed error message box. Parameters:
  | reqUrl | the request URL that generated this error message
  | method | the method that generated this error message (unimplemented)
Returns: the following strings: caption, error + description, causes+solutions Definition at line 445 of file global.cpp. References QString::arg(), KLocale::formatDateTime(), QString::fromLatin1(), QString::isNull(), QStringList::join(), KGlobal::locale(), and KIO::rawErrorDetail().

void KIO::Job::showErrorDialog | ( | QWidget * | parent = `0L` | ) |

  | Display a dialog box to inform the user of the error given by this job. Only call if error is not 0, and only in the slot connected to result. Parameters:
  | parent | the parent widget for the dialog box, can be 0 for top-level
Referenced by KDirLister::handleError().

void KIO::Job::setAutoErrorHandlingEnabled | ( | bool | enable,
|  | QWidget * | parentWidget = `0`
| ) |

  | Enable or disable the automatic error handling. When automatic error handling is enabled and an error occurs, then showErrorDialog() is called with the specified `parentWidget` (if supplied) , right before the emission of the result signal. The default is false. See also isAutoErrorHandlingEnabled , showErrorDialog Parameters:
  | enable | enable or disable automatic error handling
  | parentWidget | the parent widget, passed to showErrorDialog. Can be 0 for top-level
See also: isAutoErrorHandlingEnabled() Referenced by KDirOperator::del(), and KDirOperator::trash().

bool KIO::Job::isAutoErrorHandlingEnabled | ( |  | ) | const

| Returns whether automatic error handling is enabled or disabled. See also setAutoErrorHandlingEnabled . Returns: true if automatic error handling is enabled See also: setAutoErrorHandlingEnabled()

void KIO::Job::setInteractive | ( | bool | enable | ) |

  | Enable or disable the message display from the job. The default is true. Parameters:
  | enable | enable or disable message display
Since: 3.4.1 Reimplemented in KIO::CopyJob. Referenced by KIO::CopyJob::setInteractive().

bool KIO::Job::isInteractive | ( |  | ) | const

| Returns whether message display is enabled or disabled. See also setInteractive . Returns: true if message display is enabled See also: setInteractive() Since: 3.4.1

void KIO::Job::setWindow | ( | QWidget * | window | ) |

  | Associate this job with a window given by `window`. Parameters:
  | window | the window to associate to
See also: window() Referenced by KDirOperator::del(), and KDirOperator::trash().

QWidget* KIO::Job::window | ( |  | ) | const

| Returns the window this job is associated with. Returns: the associated window See also: setWindow()

void KIO::Job::setParentJob | ( | Job * | parentJob | ) |

  | Set the parent Job. One example use of this is when FileCopyJob calls open_RenameDlg, it must pass the correct progress ID of the parent CopyJob (to hide the progress dialog). You can set the parent job only once. By default a job does not have a parent job. Parameters:
  | parentJob | the new parent job
Since: 3.1

Job* KIO::Job::parentJob | ( |  | ) | const

| Returns the parent job, if there is one. Returns: the parent job, or 0 if there is none See also: setParentJob Since: 3.1

void KIO::Job::setMetaData | ( | const KIO::MetaData & | metaData | ) |

  | Set meta data to be sent to the slave, replacing existing meta data. Parameters:
  | metaData | the meta data to set
See also: addMetaData() mergeMetaData()

void KIO::Job::addMetaData | ( | const QString & | key,
|  | const QString & | value
| ) |

  | Add key/value pair to the meta data that is sent to the slave. Parameters:
  | key | the key of the meta data
  | value | the value of the meta data
See also: setMetaData() mergeMetaData() Referenced by KIO::davPropFind(), KIO::get(), KIO::TransferJob::slotFinished(), and KIO::storedGet().

void KIO::Job::addMetaData | ( | const QMap< QString, QString > & | values | ) |

  | Add key/value pairs to the meta data that is sent to the slave. If a certain key already existed, it will be overridden. Parameters:
  | values | the meta data to add
See also: setMetaData() mergeMetaData()

void KIO::Job::mergeMetaData | ( | const QMap< QString, QString > & | values | ) |

  | Add key/value pairs to the meta data that is sent to the slave. If a certain key already existed, it will remain unchanged. Parameters:
  | values | the meta data to merge
See also: setMetaData() addMetaData()

MetaData KIO::Job::metaData | ( |  | ) | const

| Get meta data received from the slave. (Valid when first data is received and/or slave is finished) Returns: the job's meta data

QString KIO::Job::queryMetaData | ( | const QString & | key | ) |

  | Query meta data received from the slave. (Valid when first data is received and/or slave is finished) Parameters:
  | key | the key of the meta data to retrieve
Returns: the value of the meta data, or QString::null if the `key` does not exist Referenced by KIO::ListJob::slotFinished(), KIO::MimetypeJob::slotFinished(), KIO::TransferJob::slotFinished(), KIO::StatJob::slotFinished(), and KIO::MkdirJob::slotFinished().

KIO::filesize_t KIO::Job::getProcessedSize | ( |  | ) |

| Returns the processed size for this job. See also: processedSize Since: 3.2 Referenced by KIO::TransferJob::sendAsyncData().

void KIO::Job::result | ( | KIO::Job * | job | ) | `[signal]`

  | Emitted when the job is finished, in any case (completed, canceled, failed...). Use error to know the result. Parameters:
  | job | the job that emitted this signal

void KIO::Job::canceled | ( | KIO::Job * | job | ) | `[signal]`

  | Deprecated: . Don't use ! Emitted when the job is canceled. Signal result() is emitted as well, and error() is, in this case, ERR_USER_CANCELED. Parameters:
  | job | the job that emitted this signal

void KIO::Job::infoMessage | ( | KIO::Job * | job,
|  | const QString & | msg
| ) | `[signal]`

  | Emitted to display information about this job, as sent by the slave. Examples of message are "Resolving host", "Connecting to host...", etc. Parameters:
  | job | the job that emitted this signal
  | msg | the info message
Referenced by KIO::SimpleJob::slotInfoMessage().

void KIO::Job::connected | ( | KIO::Job * | job | ) | `[signal]`

  | Emitted when the slave successfully connected to the host. There is no guarantee the slave will send this, and this is currently unused (in the applications). Parameters:
  | job | the job that emitted this signal
Referenced by KIO::SimpleJob::slotConnected().

void KIO::Job::percent | ( | KIO::Job * | job,
|  | unsigned long | percent
| ) | `[signal]`

  | Progress signal showing the overall progress of the job This is valid for any kind of job, and allows using a a progress bar very easily. (see KProgress). Note that this signal is not emitted for finished jobs. Parameters:
  | job | the job that emitted this signal
  | percent | the percentage
Referenced by KIO::DeleteJob::slotProcessedSize().

void KIO::Job::totalSize | ( | KIO::Job * | job,
|  | KIO::filesize_t | size
| ) | `[signal]`

  | Emitted when we know the size of this job (data size for transfers, number of entries for listings). Parameters:
  | job | the job that emitted this signal
  | size | the total size in bytes
Referenced by KIO::SimpleJob::slotTotalSize().

void KIO::Job::processedSize | ( | KIO::Job * | job,
|  | KIO::filesize_t | size
| ) | `[signal]`

  | Regularly emitted to show the progress of this job (current data size for transfers, entries listed). Parameters:
  | job | the job that emitted this signal
  | size | the processed size in bytes
Referenced by KIO::TransferJob::sendAsyncData(), KIO::DeleteJob::slotProcessedSize(), and KIO::SimpleJob::slotProcessedSize().

void KIO::Job::speed | ( | KIO::Job * | job,
|  | unsigned long | bytes_per_second
| ) | `[signal]`

  | Emitted to display information about the speed of this job. Parameters:
  | job | the job that emitted this signal
  | bytes_per_second | the speed in bytes/s

virtual void KIO::Job::slotResult | ( | KIO::Job * | job | ) | `[protected, virtual, slot]`

  | Called whenever a subjob finishes. Default implementation checks for errors and propagates to parent job, then calls removeSubjob. Override if you don't want subjobs errors to be propagated. Parameters:
  | job | the subjob
See also: result() Reimplemented in KDirSize, KIO::ChmodJob, KIO::TransferJob, KIO::FileCopyJob, KIO::ListJob, KIO::CopyJob, KIO::DeleteJob, KIO::MetaInfoJob, and KIO::PreviewJob. Referenced by KDirSize::slotResult(), and KIO::DeleteJob::slotResult().

void KIO::Job::slotSpeed | ( | KIO::Job * | job,
|  | unsigned long | bytes_per_second
| ) | `[protected, slot]`

  | Forward signal from subjob. Parameters:
  | job | the subjob
  | bytes_per_second | the speed in bytes/s
See also: speed()

void KIO::Job::slotInfoMessage | ( | KIO::Job * | job,
|  | const QString & | msg
| ) | `[protected, slot]`

  | Forward signal from subjob. Parameters:
  | job | the subjob
  | msg | the info message
See also: infoMessage()

void KIO::Job::slotSpeedTimeout | ( |  | ) | `[protected, slot]`

| Remove speed information.

virtual void KIO::Job::addSubjob | ( | Job * | job,
|  | bool | inheritMetaData = `true`
| ) | `[protected, virtual]`

  | Add a job that has to be finished before a result is emitted. This has obviously to be called before the finish signal is emitted by the slave. Parameters:
  | job | the subjob to add
  | inheritMetaData | if true, the subjob will inherit the meta data from this job.
Referenced by KIO::DeleteJob::slotResult().

virtual void KIO::Job::removeSubjob | ( | Job * | job | ) | `[protected, virtual]`

  | Mark a sub job as being done. If it's the last to wait on the job will emit a result - jobs with two steps might want to override slotResult in order to avoid calling this method. Parameters:
  | job | the subjob to add
Referenced by KIO::ListJob::slotResult(), and KIO::TransferJob::slotResult().

void KIO::Job::removeSubjob | ( | Job * | job,
|  | bool | mergeMetaData,
|  | bool | emitResultIfLast
| ) | `[protected]`

  | Overloaded version of removeSubjob. Parameters:
  | job | the subjob to remove
  | mergeMetaData | if set, the metadata received by the subjob is merged into this job.
  | emitResultIfLast | if this was the last subjob, emit result, i.e. terminate this job.

void KIO::Job::emitPercent | ( | KIO::filesize_t | processedSize,
|  | KIO::filesize_t | totalSize
| ) | `[protected]`

  | Utility function for inherited jobs. Emits the percent signal if bigger than m_percent, after calculating it from the parameters. Parameters:
  | processedSize | the processed size in bytes
  | totalSize | the total size in bytes
Referenced by KIO::TransferJob::sendAsyncData(), and KIO::SimpleJob::slotProcessedSize().

void KIO::Job::emitSpeed | ( | unsigned long | bytes_per_second | ) | `[protected]`

  | Utility function for inherited jobs. Emits the speed signal and starts the timer for removing that info Parameters:
  | bytes_per_second | the speed in bytes_per_second
Referenced by KIO::SimpleJob::slotSpeed().

void KIO::Job::emitResult | ( |  | ) | `[protected]`

| Utility function to emit the result signal, and suicide this job. It first tells the observer to hide the progress dialog for this job. Referenced by KIO::MetaInfoJob::MetaInfoJob(), KIO::SimpleJob::slotFinished(), KIO::TransferJob::slotResult(), and KIO::ChmodJob::slotResult().

void KIO::Job::setProcessedSize | ( | KIO::filesize_t | size | ) | `[protected]`

| Set the processed size, does not emit processedSize Since: 3.2. Referenced by KIO::TransferJob::sendAsyncData(), KIO::DeleteJob::slotProcessedSize(), and KIO::SimpleJob::slotProcessedSize().

The documentation for this class was generated from the following files:

- jobclasses.h
- global.cpp

This file is part of the documentation for kio Library Version 3.4.1.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat Jun 11 20:25:59 2005 by doxygen 1.4.1 written by Dimitri van Heesch, © 1997-2003