# 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