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::CopyJob KIO::DeleteJob KIO::FileCopyJob KIO::MetaInfoJob KIO::PreviewJob KIO::SimpleJob 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 Methods

virtual ~Job ()
virtual void kill (bool quietly=true)
int error () const
int progressId () const
const QStringerrorText () 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 setWindow (QWidget *window)
QWidgetwindow () 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 Methods

 Job (bool showProgressInfo)
virtual void addSubjob (Job *job, bool inheritMetaData=true)
virtual void removeSubjob (Job *job)
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
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  );
See also:
KIO::Scheduler , KIO::Slave

Definition at line 68 of file jobclasses.h.


Member Function Documentation

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.

Definition at line 211 of file job.cpp.

References canceled(), QPtrList< Job >::clear(), QPtrListIterator::current(), emitResult(), Observer::jobFinished(), and Observer::self().

Referenced by KImageFilePreview::clearPreview(), 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::PreviewJob::slotResult(), KIO::DeleteJob::slotResult(), KIO::CopyJob::slotResult(), KIO::FileCopyJob::slotResult(), KIO::TransferJob::slotResult(), slotResult(), KIO::ChmodJob::slotResult(), and KIO::CopyJob::slotResultStating().

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.

Referenced by Observer::slotTransferring().

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.

Referenced by KIO::FileCopyJob::slotResult(), KIO::TransferJob::slotResult(), 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. 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 173 of file global.cpp.

References KIO::buildErrorString().

Referenced by showErrorDialog().

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

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

Referenced by showErrorDialog().

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 266 of file job.cpp.

References detailedErrorStrings(), errorString(), KMessageBox::queuedDetailedError(), and KMessageBox::queuedMessageBox().

Referenced by emitResult(), and KDirLister::handleError().

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.

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

Definition at line 293 of file job.cpp.

Referenced by KDirOperator::del().

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

Definition at line 299 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 304 of file job.cpp.

References KIO::Scheduler::registerWindow().

Referenced by addSubjob(), and KDirOperator::del().

QWidget * Job::window   const
 

Returns the window this job is associated with.

Returns:
the associated window
See also:
setWindow()

Definition at line 310 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 315 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 322 of file job.cpp.

Referenced by KIO::FileCopyJob::slotCanResume().

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 339 of file job.cpp.

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 344 of file job.cpp.

References QMap< QString, QString >::insert(), and KStdAccel::key().

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

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 349 of file job.cpp.

References QMap::begin(), QMapConstIterator::data(), QMap::end(), QMap< QString, QString >::insert(), and QMapConstIterator::key().

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 356 of file job.cpp.

References QMap::begin(), QMapConstIterator::data(), QMap::end(), QMap< QString, QString >::insert(), and QMapConstIterator::key().

Referenced by addSubjob().

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 327 of file job.cpp.

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 332 of file job.cpp.

References QMap< QString, QString >::contains(), and KStdAccel::key().

Referenced by KIO::ListJob::slotFinished(), KIO::MimetypeJob::slotFinished(), KIO::TransferJob::slotFinished(), and KIO::StatJob::slotFinished().

KIO::filesize_t Job::getProcessedSize  
 

Returns the processed size for this job.

See also:
processedSize
Since:
3.2

Definition at line 138 of file job.cpp.

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

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

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

Referenced by kill().

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 addSubjob(), KIO::SimpleJob::slotInfoMessage(), and 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 emitPercent(), KIO::FileCopyJob::slotPercent(), and 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 emitPercent(), KIO::CopyJob::slotProcessedSize(), KIO::CopyJob::slotTotalSize(), KIO::FileCopyJob::slotTotalSize(), and 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(), KIO::CopyJob::slotProcessedSize(), KIO::FileCopyJob::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

Referenced by addSubjob(), emitSpeed(), and slotSpeedTimeout().

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 KDirSize, KIO::ChmodJob, KIO::TransferJob, KIO::FileCopyJob, KIO::ListJob, KIO::CopyJob, KIO::DeleteJob, KIO::MetaInfoJob, and KIO::PreviewJob.

Definition at line 232 of file job.cpp.

References error(), errorText(), and removeSubjob().

Referenced by addSubjob(), and KDirSize::slotResult().

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

Definition at line 244 of file job.cpp.

References emitSpeed().

Referenced by addSubjob().

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 250 of file job.cpp.

References infoMessage().

Referenced by addSubjob().

void Job::slotSpeedTimeout   [protected, slot]
 

Remove speed information.

Definition at line 255 of file job.cpp.

References speed(), and QTimer::stop().

Referenced by emitSpeed().

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 143 of file job.cpp.

References QPtrList< Job >::append(), QObject::connect(), infoMessage(), mergeMetaData(), result(), setWindow(), slotInfoMessage(), slotResult(), slotSpeed(), and speed().

Referenced by KIO::FileCopyJob::slotCanResume(), KIO::DeleteJob::slotResult(), KIO::CopyJob::slotResult(), KIO::FileCopyJob::slotResult(), and KIO::CopyJob::slotStart().

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 164 of file job.cpp.

References emitResult(), QPtrList< Job >::isEmpty(), and QPtrList< Job >::remove().

Referenced by KIO::ListJob::slotResult(), KIO::FileCopyJob::slotResult(), and slotResult().

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 172 of file job.cpp.

References percent(), and totalSize().

Referenced by KIO::TransferJob::sendAsyncData(), KIO::CopyJob::slotProcessedSize(), KIO::FileCopyJob::slotProcessedSize(), and KIO::SimpleJob::slotProcessedSize().

void 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

Definition at line 188 of file job.cpp.

References QObject::connect(), slotSpeedTimeout(), speed(), and QTimer::start().

Referenced by KIO::SimpleJob::slotSpeed(), and slotSpeed().

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 200 of file job.cpp.

References Observer::jobFinished(), result(), Observer::self(), and showErrorDialog().

Referenced by kill(), KIO::MetaInfoJob::MetaInfoJob(), removeSubjob(), KIO::FileCopyJob::slotCanResume(), KIO::SimpleJob::slotFinished(), KIO::CopyJob::slotResult(), KIO::FileCopyJob::slotResult(), KIO::TransferJob::slotResult(), KIO::ChmodJob::slotResult(), and KIO::CopyJob::slotResultStating().

void Job::setProcessedSize KIO::filesize_t    size [protected]
 

Set the processed size, does not emit processedSize

Since:
3.2.

Definition at line 133 of file job.cpp.

Referenced by KIO::TransferJob::sendAsyncData(), KIO::DeleteJob::slotProcessedSize(), KIO::CopyJob::slotProcessedSize(), KIO::FileCopyJob::slotProcessedSize(), and KIO::SimpleJob::slotProcessedSize().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kio Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sun May 16 22:03:38 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003