KIO::Job Class Reference

`#include <jobclasses.h>`

Inheritance diagram for KIO::Job:

## Signals

void | result (KIO::Job *job)
void | canceled (KIO::Job *job)
void | infoMessage (KIO::Job *job, const QString &msg)
void | warning (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 speed)

## 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 | setAutoWarningHandlingEnabled (bool enable)
bool | isAutoWarningHandlingEnabled () const
void | setInteractive (bool enable)
bool | isInteractive () const
void | setWindow (QWidget *window)
QWidget * | window () const
void | updateUserTimestamp (unsigned long time)
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 speed)
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 speed)
void | emitResult ()
void | setProcessedSize (KIO::filesize_t size)
unsigned long | userTimestamp () const
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

void 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()

Definition at line 405 of file job.cpp.

void 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()

Definition at line 410 of file job.cpp.

void 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.

Definition at line 162 of file job.cpp.

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::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

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 458 of file global.cpp.

void 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

Definition at line 200 of file job.cpp.

void 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.

Definition at line 228 of file job.cpp.

void Job::emitSpeed | ( | unsigned long | speed | ) |

protected

Utility function for inherited jobs.

Emits the speed signal and starts the timer for removing that info

Parameters

  speed | the speed in bytes/s

Definition at line 216 of file job.cpp.

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.

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 208 of file global.cpp.

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::filesize_t Job::getProcessedSize | ( |  | ) |

Returns the processed size for this job.

See also
  processedSize

Since
  3.2

Definition at line 157 of file job.cpp.

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

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

Returns whether automatic error handling is enabled or disabled.

Returns
  true if automatic error handling is enabled

See also
  setAutoErrorHandlingEnabled()

Definition at line 327 of file job.cpp.

bool Job::isAutoWarningHandlingEnabled | ( |  | ) | const

Returns whether automatic warning handling is enabled or disabled.

See also setAutoWarningHandlingEnabled .

Returns
  true if automatic warning handling is enabled

See also
  setAutoWarningHandlingEnabled()

Since
  3.5

Definition at line 337 of file job.cpp.

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

Returns whether message display is enabled or disabled.

Returns
  true if message display is enabled

See also
  setInteractive()

Since
  3.4.1

Definition at line 347 of file job.cpp.

void 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, and KIO::PreviewJob.

Definition at line 239 of file job.cpp.

void 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()

Definition at line 417 of file job.cpp.

MetaData 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

Definition at line 388 of file job.cpp.

Job * 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

Definition at line 383 of file job.cpp.

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

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

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.

QString 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

Definition at line 393 of file job.cpp.

void 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

Definition at line 184 of file job.cpp.

void 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.

Definition at line 189 of file job.cpp.

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 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.

Parameters

  enable | enable or disable automatic error handling
  parentWidget | the parent widget, passed to showErrorDialog. Can be 0 for top-level

See also
  isAutoErrorHandlingEnabled(), showErrorDialog()

Definition at line 321 of file job.cpp.

void Job::setAutoWarningHandlingEnabled | ( | bool | enable | ) |

Enable or disable the automatic warning handling.

When automatic warning handling is enabled and an error occurs, then a message box is displayed with the warning message

The default is true.

See also isAutoWarningHandlingEnabled , showErrorDialog

Parameters

  enable | enable or disable automatic warning handling

See also
  isAutoWarningHandlingEnabled()

Since
  3.5

Definition at line 332 of file job.cpp.

void 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

Definition at line 342 of file job.cpp.

void 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()

Definition at line 400 of file job.cpp.

void 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

Definition at line 376 of file job.cpp.

void Job::setProcessedSize | ( | KIO::filesize_t | size | ) |

protected

Set the processed size, does not emit processedSize.

Since
  3.2

Definition at line 152 of file job.cpp.

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

Associate this job with a window given by `window`.

Parameters

  window | the window to associate to

See also
  window()

Definition at line 352 of file job.cpp.

void 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

Definition at line 294 of file job.cpp.

void 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()

Definition at line 278 of file job.cpp.

void 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 KIO::TransferJob.

Definition at line 260 of file job.cpp.

void Job::slotSpeed | ( | KIO::Job * | job,
|  | unsigned long | speed
| ) |  |

protected slot

Forward signal from subjob.

Parameters

  job | the subjob
  speed | the speed in bytes/s

See also
  speed()

Definition at line 272 of file job.cpp.

void Job::slotSpeedTimeout | ( |  | ) |

protected slot

Remove speed information.

Definition at line 283 of file job.cpp.

void KIO::Job::speed | ( | KIO::Job * | job,
|  | unsigned long | speed
| ) |  |

signal

Emitted to display information about the speed of this job.

Parameters

  job | the job that emitted this signal
  speed | the speed in bytes/s

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

void Job::updateUserTimestamp | ( | unsigned long | time | ) |

Updates the last user action timestamp to the given time.

See KApplication::updateUserTimestamp() .

Since
  3.5.6

Definition at line 363 of file job.cpp.

void KIO::Job::warning | ( | KIO::Job * | job,
|  | const QString & | msg
| ) |  |

signal

Emitted to display a warning about this job, as sent by the slave.

Parameters

  job | the job that emitted this signal
  msg | the info message

Since
  3.5

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

Returns the window this job is associated with.

Returns
  the associated window

See also
  setWindow()

Definition at line 358 of file job.cpp.

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

- jobclasses.h
- global.cpp
- job.cpp

KDE Home | KDE Accessibility Home | Description of Access Keys