# class KJob

### abstract

Module | kdecore
Namespace |
Class | KJob
Inherits | QObject

The base class for all jobs. For all jobs created in an application, the code looks like

    KJob * job = someoperation( some parameters );
    connect( job, SIGNAL( result( KJob * ) ),
    this, SLOT( slotResult( KJob * ) ) );
    job->start();

(other connects, specific to the job)

And slotResult is usually at least:

    if ( job->error() )
    doSomething();

With the synchronous interface the code looks like

    KJob *job = someoperation( some parameters );
    if ( !job->exec() )
    {
    // An error occurred
    }
    else
    {
    // Do something
    }

@note: KJob and its subclasses is meant to be used in a fire-and-forget way. It's deleting itself when it has finished using deleteLater() so the job instance disappears after the next event loop run.

### enums

- Capability { NoCapabilities, Killable, Suspendable }
  typesafe object: Capabilities
- KillVerbosity { Quietly, EmitResult }
- Unit { Bytes, Files, Directories }
- anonymous { NoError, KilledJobError, UserDefinedError }

enum details

### methods

- KJob (parent)

  returns ctor
  KDE 4.1.0 and later only

  Argument | Type | Default
  --- | --- | ---
  parent | QObject | 0

  Creates a new KJob object.

  parent - the parent QObject

- KJob (dd, parent)

  returns ctor
  Not implemented

  Argument | Type | Default
  --- | --- | ---
  dd | KJobPrivate |
  parent | QObject |

- KJob (a0)

  returns ctor
  before KDE 4.1.0 only

  Argument | Type | Default
  --- | --- | ---
  a0 | QObject | 0

- capabilities ( )

  returns KJob.Capabilities

  Returns the capabilities of this job.

  Returns the capabilities that this job supports

  See also setCapabilities()

- description (job, title, field1, field2)

  returns Nothing
  SIGNAL ("description (KJob*, const QString&, const QPair<QString,QString>&, const QPair<QString,QString>&)")

  Argument | Type | Default
  --- | --- | ---
  job | KJob |
  title | QString |
  field1 | QPair<QString,QString> | qMakePair(QString(),QString())
  field2 | QPair<QString,QString> | qMakePair(QString(),QString())

  Emitted to display general description of this job. A description has a title and two optional fields which can be used to complete the description.

  Examples of titles are "Copying", "Creating resource", etc. The fields of the description can be "Source" with an URL, and, "Destination" with an URL for a "Copying" description.

  job - the job that emitted this signal

  title - the general description of the job

  field1 - first field (localized name and value)

  field2 - second field (localized name and value)

- doKill ( )

  returns bool

  Aborts this job quietly. This simply kills the job, no error reporting or job deletion should be involved.

  Returns true if the operation is supported and succeeded, false otherwise

- doResume ( )

  returns bool

  Resumes this job.

  Returns true if the operation is supported and succeeded, false otherwise

- doSuspend ( )

  returns bool

  Suspends this job.

  Returns true if the operation is supported and succeeded, false otherwise

- emitPercent (processedAmount, totalAmount)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  processedAmount | qulonglong |
  totalAmount | qulonglong |

  Utility function for inherited jobs. Emits the percent signal if bigger than previous value, after calculating it from the parameters.

  processedAmount - the processed amount

  totalAmount - the total amount

  See also percent()

- emitResult ( )

  returns Nothing

  Utility function to emit the result signal, and suicide this job. It first notifies the observers to hide the progress for this job using the finished() signal.

  @note: Deletes this job using deleteLater().

  See also result()

  See also finished()

- emitSpeed (speed)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  speed | unsigned long |

  Utility function for inherited jobs. Emits the speed signal and starts the timer for removing that info

  speed - the speed in bytes/s

- error ( )

  returns int

  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.

- errorString ( )

  returns QString

  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" , errorText() );

  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

- errorText ( )

  returns QString

  Returns the error text if there has been an error. Only call if error is not 0. This is really internal, better use errorString.

  Returns a string to help understand the error, usually the url related to the error. Only valid if error() is not 0.

- exec ( )

  returns bool

  Executes the job synchronously.

  Returns true if the job has been executed without error, false otherwise

- infoMessage (job, plain, rich)

  returns Nothing
  SIGNAL ("infoMessage (KJob*, const QString&, const QString&)")

  Argument | Type | Default
  --- | --- | ---
  job | KJob |
  plain | QString |
  rich | QString | QString()

  Emitted to display state information about this job. Examples of message are "Resolving host", "Connecting to host...", etc.

  job - the job that emitted this signal

  plain - the info message

  rich - the rich text version of the message, or QString() is none is available

- isAutoDelete ( )

  returns bool
  KDE 4.1.0 and later only

  Returns whether this job automatically deletes itself once the job is finished.

  Returns whether the job is deleted automatically after finishing.

- isSuspended ( )

  returns bool

  Returns if the job was suspended with the suspend() call.

  Returns if the job was suspended

  See also suspend() resume()

- kill (verbosity)

  returns bool

  Argument | Type | Default
  --- | --- | ---
  verbosity | KJob.KillVerbosity | KJob.Quietly

  Aborts this job. This kills and deletes the job.

  verbosity - if equals to EmitResult, Job will emit signal result and ask uiserver to close the progress window. verbosity is set to EmitResult for subjobs. Whether applications should call with Quietly or EmitResult depends on whether they rely on result being emitted or not. Returns true if the operation is supported and succeeded, false otherwise

- percent ( )

  returns unsigned long

  Returns the overall progress of this job.

  Returns the overall progress of this job

- processedAmount (unit)

  returns qulonglong

  Argument | Type | Default
  --- | --- | ---
  unit | KJob.Unit |

  Returns the processed amount of a given unit for this job.

  unit - the unit of the requested amount Returns the processed size

- resume ( )

  returns bool

  Resumes this job.

  Returns true if the operation is supported and succeeded, false otherwise

- setAutoDelete (autodelete)

  returns Nothing
  KDE 4.1.0 and later only

  Argument | Type | Default
  --- | --- | ---
  autodelete | bool |

  set the auto-delete property of the job. If autodelete is set to false the job will not delete itself once its finished.

  The default for any KJob is to automatically delete itself.

  autodelete - set to false to disable automatic deletion of the job.

- setCapabilities (capabilities)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  capabilities | KJob.Capabilities |

  Sets the capabilities for this job.

  capabilities - are the capabilities supported by this job

  See also capabilities()

- setError (errorCode)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  errorCode | int |

  Sets the error code. It should be called when an error is encountered in the job, just before calling emitResult().

  errorCode - the error code

  See also emitResult()

- setErrorText (errorText)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  errorText | QString |

  Sets the error text. It should be called when an error is encountered in the job, just before calling emitResult().

  errorText - the error text

  See also emitResult()

- setPercent (percentage)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  percentage | unsigned long |

  Sets the overall progress of the job. The percent() signal is emitted if the value changed.

  percentage - the new overall progress

- setProcessedAmount (unit, amount)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  unit | KJob.Unit |
  amount | qulonglong |

  Sets the processed size. The processedAmount() and percent() signals are emitted if the values changed. The percent() signal is emitted only for the progress unit.

  unit - the unit of the new processed amount

  amount - the new processed amount

- setTotalAmount (unit, amount)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  unit | KJob.Unit |
  amount | qulonglong |

  Sets the total size. The totalSize() and percent() signals are emitted if the values changed. The percent() signal is emitted only for the progress unit.

  unit - the unit of the new total amount

  amount - the new total amount

- setUiDelegate (delegate)

  returns Nothing

  Argument | Type | Default
  --- | --- | ---
  delegate | KJobUiDelegate |

  Attach a UI delegate to this job.

  If the job had another UI delegate, it's automatically deleted. Once attached to the job, the UI delegate will be deleted with the job.

  delegate - the new UI delegate to use

  See also KJobUiDelegate

- start ( )

  returns Nothing
  pure virtual

  Starts the job asynchronously. When the job is finished, result() is emitted.

- suspend ( )

  returns bool

  Suspends this job. The job should be kept in a state in which it is possible to resume it.

  Returns true if the operation is supported and succeeded, false otherwise

- totalAmount (unit)

  returns qulonglong

  Argument | Type | Default
  --- | --- | ---
  unit | KJob.Unit |

  Returns the total amount of a given unit for this job.

  unit - the unit of the requested amount Returns the total size

- uiDelegate ( )

  returns KJobUiDelegate

  Retrieves the delegate attached to this job.

  Returns the delegate attached to this job, or 0 if there's no such delegate

- warning (job, plain, rich)

  returns Nothing
  SIGNAL ("warning (KJob*, const QString&, const QString&)")

  Argument | Type | Default
  --- | --- | ---
  job | KJob |
  plain | QString |
  rich | QString | QString()

  Emitted to display a warning about this job.

  job - the job that emitted this signal

  plain - the warning message

  rich - the rich text version of the message, or QString() is none is available

### enums - detail

- Capability { NoCapabilities, Killable, Suspendable }

  typesafe object: Capabilities

NoCapabilities - 0x0000 -
Killable - 0x0001 -
Suspendable - 0x0002 -

- KillVerbosity { Quietly, EmitResult }

  | Quietly | - | - |
  | EmitResult | - | - |

- Unit { Bytes, Files, Directories }

  | Bytes | - | - |
  | Files | - | - |
  | Directories | - | - |

- anonymous { NoError, KilledJobError, UserDefinedError }

  | NoError | - 0 | - |
  | KilledJobError | - 1 | - |
  | UserDefinedError | - 100 | - |