kio Library API Documentation

KIO::Job Class Reference

The base class for all jobs. More...

#include <jobclasses.h>

Inheritance diagram for KIO::Job:

QObject KDirSize KIO::ChmodJob KIO::DeleteJob KIO::FileCopyJob KIO::MetaInfoJob KIO::PreviewJob KIO::SimpleJob KIO::TransferJob KIO::DavJob List of all members.

Signals

void result (KIO::Job *job)
 Emitted when the job is finished, in any case (completed, canceled, failed...).

void canceled (KIO::Job *job)
 Emitted when the job is canceled.

void infoMessage (KIO::Job *, const QString &msg)
 Emitted to display information about this job, as sent by the slave.

void connected (KIO::Job *)
 Emitted when the slave successfully connected to the host.

void percent (KIO::Job *job, unsigned long percent)
 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.

void totalSize (KIO::Job *, KIO::filesize_t size)
 Emitted when we know the size of this job (data size for transfers, number of entries for listings).

void processedSize (KIO::Job *, KIO::filesize_t size)
 Regularly emitted to show the progress of this job (current data size for transfers, entries listed).

void speed (KIO::Job *, unsigned long bytes_per_second)
 Emitted to display information about the speed of this job.


Public Member Functions

virtual void kill (bool quietly=true)
 Abort this job.

int error () const
int progressId () const
const QStringerrorText () const
QString errorString () const
 Converts an error code and a non-i18n error message into an error message in the current language.

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

void showErrorDialog (QWidget *parent=0L)
 Display a dialog box to inform the user of the error given by this job.

void setAutoErrorHandlingEnabled (bool enable, QWidget *parentWidget=0)
 Enable or disable the automatic error handling.

bool isAutoErrorHandlingEnabled () const
 Returns whether automatic error handling is enabled or disabled.

void setWindow (QWidget *window)
 Associate this job with a window given by window.

QWidgetwindow () const
 Returns the window this job is associated with.

void setParentJob (Job *parentJob)
 Set the parent Job.

JobparentJob () const
void setMetaData (const KIO::MetaData &)
 Set meta data to be sent to the slave.

void addMetaData (const QString &key, const QString &value)
 Add key/value pair to the meta data that is sent to the slave.

void addMetaData (const QMap< QString, QString > &values)
 Add key/value pairs to the meta data that is sent to the slave.

void mergeMetaData (const QMap< QString, QString > &values)
 Add key/value pairs to the meta data that is sent to the slave.

MetaData outgoingMetaData () const
MetaData metaData () const
 Get meta data received from the slave.

QString queryMetaData (const QString &key)
 Query meta data received from the slave.


Protected Slots

virtual void slotResult (KIO::Job *job)
 Called whenever a subjob finishes.

void slotSpeed (KIO::Job *, unsigned long bytes_per_second)
 Forward signal from subjob.

void slotInfoMessage (KIO::Job *, const QString &)
 Forward signal from subjob.

void slotSpeedTimeout ()
 Remove speed information.


Protected Member Functions

 Job (bool showProgressInfo)
virtual void addSubjob (Job *job, bool inheritMetaData=true)
 Add a job that has to be finished before a result is emitted.

virtual void removeSubjob (Job *job)
 Mark a sub job as being done.

void emitPercent (KIO::filesize_t processedSize, KIO::filesize_t totalSize)
 Utility function for inherited jobs.

void emitSpeed (unsigned long bytes_per_second)
 Utility function for inherited jobs.

void emitResult ()
 Utility function to emit the result signal, and suicide this job.

virtual void virtual_hook (int id, void *data)

Protected Attributes

QPtrList< Jobsubjobs
int m_error
QString m_errorText
unsigned long m_percent
int m_progressId
QTimerm_speedTimer
QGuardedPtr< QWidgetm_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 );

Definition at line 66 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(), and KIO::ProgressBase::slotStop().

int KIO::Job::error  )  const [inline]
 

Returns:
the error code for this job, 0 if no error Error codes are defined in KIO::Error. Only call this method from the slot connected to result().

Definition at line 91 of file jobclasses.h.

Referenced by KIO::PreviewJob::slotResult(), KIO::DeleteJob::slotResult(), KIO::TransferJob::slotResult(), and KIO::ChmodJob::slotResult().

int KIO::Job::progressId  )  const [inline]
 

Returns:
the progress id for this job, as returned by uiserver

Definition at line 96 of file jobclasses.h.

Referenced by Observer::open_RenameDlg(), Observer::open_SkipDlg(), and Observer::slotTransferring().

const QString& KIO::Job::errorText  )  const [inline]
 

Returns:
a string to help understand the error, usually the url related to the error. Only call if error is not 0. This is really internal, better use errorString or errorDialog.

Definition at line 104 of file jobclasses.h.

Referenced by KIO::TransferJob::slotResult(), and KIO::ChmodJob::slotResult().

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.

Definition at line 173 of file global.cpp.

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.

reqUrl the request URL that generated this error message method the method that generated this error message (unimplemented)

Returns strings: caption, error + description, causes+solutions

Definition at line 383 of file global.cpp.

References QString::arg(), QDateTime::currentDateTime(), KStdAccel::description(), KLocale::formatDateTime(), QString::fromLatin1(), KURL::htmlURL(), QStringList::join(), KGlobal::locale(), and KURL::protocol().

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

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

Referenced by KDirOperator::del().

bool KIO::Job::isAutoErrorHandlingEnabled  )  const
 

Returns whether automatic error handling is enabled or disabled.

See also setAutoErrorHandlingEnabled .

void KIO::Job::setWindow QWidget window  ) 
 

Associate this job with a window given by window.

QWidget* KIO::Job::window  )  const
 

Returns the window this job is associated with.

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

Since:
3.1

Job* KIO::Job::parentJob  )  const
 

See also:
setParentJob
Since:
3.1

void KIO::Job::setMetaData const KIO::MetaData &   ) 
 

Set meta data to be sent to the slave.

void KIO::Job::addMetaData const QString key,
const QString value
 

Add key/value pair to the meta data that is sent to the slave.

Referenced by KIO::get(), and KIO::TransferJob::slotFinished().

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.

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.

MetaData KIO::Job::metaData  )  const
 

Get meta data received from the slave.

(Valid when first data is received and/or slave is finished)

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)

Referenced by KIO::TransferJob::slotFinished().

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.

Referenced by KIO::PreviewJob::availablePlugins(), KIO::MetaInfoJob::availablePlugins(), KIO::PreviewJob::supportedMimeTypes(), and KIO::MetaInfoJob::supportedMimeTypes().

void KIO::Job::canceled KIO::Job job  )  [signal]
 

Emitted when the job is canceled.

This class or method is obsolete, it is provided for compatibility only.. Don't use ! Signal result is emitted as well, and error() is, in this case, ERR_USER_CANCELED.

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

Referenced by KIO::SimpleJob::slotInfoMessage().

void KIO::Job::connected KIO::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).

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 (i.e. percent is never 100).

Referenced by KIO::DeleteJob::slotProcessedSize().

void KIO::Job::totalSize KIO::Job ,
KIO::filesize_t  size
[signal]
 

Emitted when we know the size of this job (data size for transfers, number of entries for listings).

Referenced by KIO::SimpleJob::slotTotalSize().

void KIO::Job::processedSize KIO::Job ,
KIO::filesize_t  size
[signal]
 

Regularly emitted to show the progress of this job (current data size for transfers, entries listed).

Referenced by KIO::DeleteJob::slotProcessedSize(), and KIO::SimpleJob::slotProcessedSize().

void KIO::Job::speed KIO::Job ,
unsigned long  bytes_per_second
[signal]
 

Emitted to display information about the speed of this job.

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.

Reimplemented in KDirSize, KIO::ChmodJob, KIO::TransferJob, KIO::FileCopyJob, KIO::DeleteJob, KIO::MetaInfoJob, and KIO::PreviewJob.

Referenced by KDirSize::slotResult().

void KIO::Job::slotSpeed KIO::Job ,
unsigned long  bytes_per_second
[protected, slot]
 

Forward signal from subjob.

void KIO::Job::slotInfoMessage KIO::Job ,
const QString
[protected, slot]
 

Forward signal from subjob.

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.

If inheritMetaData is 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.

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.

Referenced by 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

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


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.4.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Sun Feb 27 22:15:38 2005 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001