KIO::Job Class Reference

#include <jobclasses.h>

Inheritance diagram for KIO::Job:

QObject KIO::ChmodJob KIO::CopyJob KIO::DeleteJob KIO::FileCopyJob KIO::MetaInfoJob KIO::PreviewJob KIO::SimpleJob KIO::DirectCopyJob KIO::ListJob KIO::MkdirJob KIO::StatJob KIO::TransferJob KIO::DavJob KIO::MimetypeJob KIO::MultiGetJob KIO::StoredTransferJob List of all members.

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.


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 ~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 setAutoWarningHandlingEnabled (bool enable)
bool isAutoWarningHandlingEnabled () const
void setInteractive (bool enable)
bool isInteractive () const
void setWindow (QWidget *window)
QWidgetwindow () const
void updateUserTimestamp (unsigned long time)
void setParentJob (Job *parentJob)
JobparentJob () 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< 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

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

Definition at line 239 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.

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

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

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.

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.

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.

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

Reimplemented in KIO::CopyJob.

Definition at line 342 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::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.

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.

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

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

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.

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

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

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

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

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

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::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::slotSpeedTimeout (  )  [protected, slot]

Remove speed information.

Definition at line 283 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 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 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::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.

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


The documentation for this class was generated from the following files:
KDE Home | KDE Accessibility Home | Description of Access Keys