.TH "KIO::Job" 3 "28 Jan 2004" "kio Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KIO::Job \- The base class for all jobs.  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <jobclasses.h>\fP
.PP
Inherits \fBQObject\fP.
.PP
Inherited by \fBKDirSize\fP, \fBKIO::ChmodJob\fP, KIO::CopyJob, \fBKIO::DeleteJob\fP, \fBKIO::FileCopyJob\fP, \fBKIO::MetaInfoJob\fP, \fBKIO::PreviewJob\fP, and \fBKIO::SimpleJob\fP.
.PP
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBresult\fP (\fBKIO::Job\fP *job)"
.br
.RI "\fIEmitted when the job is finished, in any case (completed, canceled, failed...). \fP"
.ti -1c
.RI "void \fBcanceled\fP (\fBKIO::Job\fP *job)"
.br
.RI "\fIEmitted when the job is canceled. \fP"
.ti -1c
.RI "void \fBinfoMessage\fP (\fBKIO::Job\fP *, const  \fBQString\fP &msg)"
.br
.RI "\fIEmitted to display information about this job, as sent by the slave. \fP"
.ti -1c
.RI "void \fBconnected\fP (\fBKIO::Job\fP *)"
.br
.RI "\fIEmitted when the slave successfully connected to the host. \fP"
.ti -1c
.RI "void \fBpercent\fP (\fBKIO::Job\fP *job, unsigned long percent)"
.br
.RI "\fIProgress 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. \fP"
.ti -1c
.RI "void \fBtotalSize\fP (\fBKIO::Job\fP *, KIO::filesize_t size)"
.br
.RI "\fIEmitted when we know the size of this job (data size for transfers, number of entries for listings). \fP"
.ti -1c
.RI "void \fBprocessedSize\fP (\fBKIO::Job\fP *, KIO::filesize_t size)"
.br
.RI "\fIRegularly emitted to show the progress of this job (current data size for transfers, entries listed). \fP"
.ti -1c
.RI "void \fBspeed\fP (\fBKIO::Job\fP *, unsigned long bytes_per_second)"
.br
.RI "\fIEmitted to display information about the speed of this job. \fP"
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "virtual void \fBkill\fP (bool quietly=true)"
.br
.RI "\fIAbort this job. \fP"
.ti -1c
.RI "int \fBerror\fP () const "
.br
.ti -1c
.RI "int \fBprogressId\fP () const "
.br
.ti -1c
.RI "const  \fBQString\fP & \fBerrorText\fP () const "
.br
.ti -1c
.RI "\fBQString\fP \fBerrorString\fP () const "
.br
.RI "\fIConverts an error code and a non-i18n error message into an error message in the current language. \fP"
.ti -1c
.RI "\fBQStringList\fP \fBdetailedErrorStrings\fP (const  \fBKURL\fP *reqUrl=0L, int method=-1) const "
.br
.RI "\fIConverts an error code and a non-i18n error message into i18n strings suitable for presentation in a detailed error message box. \fP"
.ti -1c
.RI "void \fBshowErrorDialog\fP (\fBQWidget\fP *\fBparent\fP=0L)"
.br
.RI "\fIDisplay a dialog box to inform the user of the error given by this job. \fP"
.ti -1c
.RI "void \fBsetAutoErrorHandlingEnabled\fP (bool enable, \fBQWidget\fP *parentWidget=0)"
.br
.RI "\fIEnable or disable the automatic error handling. \fP"
.ti -1c
.RI "bool \fBisAutoErrorHandlingEnabled\fP () const "
.br
.RI "\fIReturns whether automatic error handling is enabled or disabled. \fP"
.ti -1c
.RI "void \fBsetWindow\fP (\fBQWidget\fP *window)"
.br
.RI "\fIAssociate this job with a window given by \fCwindow\fP. \fP"
.ti -1c
.RI "\fBQWidget\fP * \fBwindow\fP () const "
.br
.RI "\fIReturns the window this job is associated with. \fP"
.ti -1c
.RI "void \fBsetParentJob\fP (\fBJob\fP *parentJob)"
.br
.RI "\fISet the parent \fBJob\fP. \fP"
.ti -1c
.RI "\fBJob\fP * \fBparentJob\fP () const "
.br
.ti -1c
.RI "void \fBsetMetaData\fP (const  KIO::MetaData &)"
.br
.RI "\fISet meta data to be sent to the slave. \fP"
.ti -1c
.RI "void \fBaddMetaData\fP (const  \fBQString\fP &key, const  \fBQString\fP &value)"
.br
.RI "\fIAdd key/value pair to the meta data that is sent to the slave. \fP"
.ti -1c
.RI "void \fBaddMetaData\fP (const  \fBQMap\fP< \fBQString\fP, \fBQString\fP > &values)"
.br
.RI "\fIAdd key/value pairs to the meta data that is sent to the slave. \fP"
.ti -1c
.RI "void \fBmergeMetaData\fP (const  \fBQMap\fP< \fBQString\fP, \fBQString\fP > &values)"
.br
.RI "\fIAdd key/value pairs to the meta data that is sent to the slave. \fP"
.ti -1c
.RI "MetaData \fBoutgoingMetaData\fP () const "
.br
.ti -1c
.RI "MetaData \fBmetaData\fP () const "
.br
.RI "\fIGet meta data received from the slave. \fP"
.ti -1c
.RI "\fBQString\fP \fBqueryMetaData\fP (const  \fBQString\fP &key)"
.br
.RI "\fIQuery meta data received from the slave. \fP"
.in -1c
.SS "Protected Slots"

.in +1c
.ti -1c
.RI "virtual void \fBslotResult\fP (\fBKIO::Job\fP *job)"
.br
.RI "\fICalled whenever a subjob finishes. \fP"
.ti -1c
.RI "void \fBslotSpeed\fP (\fBKIO::Job\fP *, unsigned long bytes_per_second)"
.br
.RI "\fIForward signal from subjob. \fP"
.ti -1c
.RI "void \fBslotInfoMessage\fP (\fBKIO::Job\fP *, const  \fBQString\fP &)"
.br
.RI "\fIForward signal from subjob. \fP"
.ti -1c
.RI "void \fBslotSpeedTimeout\fP ()"
.br
.RI "\fIRemove speed information. \fP"
.in -1c
.SS "Protected Member Functions"

.in +1c
.ti -1c
.RI "\fBJob\fP (bool showProgressInfo)"
.br
.ti -1c
.RI "virtual void \fBaddSubjob\fP (\fBJob\fP *job, bool inheritMetaData=true)"
.br
.RI "\fIAdd a job that has to be finished before a result is emitted. \fP"
.ti -1c
.RI "virtual void \fBremoveSubjob\fP (\fBJob\fP *job)"
.br
.RI "\fIMark a sub job as being done. \fP"
.ti -1c
.RI "void \fBemitPercent\fP (KIO::filesize_t processedSize, KIO::filesize_t totalSize)"
.br
.RI "\fIUtility function for inherited jobs. \fP"
.ti -1c
.RI "void \fBemitSpeed\fP (unsigned long bytes_per_second)"
.br
.RI "\fIUtility function for inherited jobs. \fP"
.ti -1c
.RI "void \fBemitResult\fP ()"
.br
.RI "\fIUtility function to emit the result signal, and suicide this job. \fP"
.ti -1c
.RI "virtual void \fBvirtual_hook\fP (int id, void *data)"
.br
.in -1c
.SS "Protected Attributes"

.in +1c
.ti -1c
.RI "\fBQPtrList\fP< \fBJob\fP > \fBsubjobs\fP"
.br
.ti -1c
.RI "int \fBm_error\fP"
.br
.ti -1c
.RI "\fBQString\fP \fBm_errorText\fP"
.br
.ti -1c
.RI "unsigned long \fBm_percent\fP"
.br
.ti -1c
.RI "int \fBm_progressId\fP"
.br
.ti -1c
.RI "\fBQTimer\fP * \fBm_speedTimer\fP"
.br
.ti -1c
.RI "\fBQGuardedPtr\fP< \fBQWidget\fP > \fBm_window\fP"
.br
.ti -1c
.RI "MetaData \fBm_outgoingMetaData\fP"
.br
.ti -1c
.RI "MetaData \fBm_incomingMetaData\fP"
.br
.in -1c
.SH "Detailed Description"
.PP 
The base class for all jobs. 

For all jobs created in an application, the code looks like
.PP
.PP
.nf

   KIO::Job * job = KIO::someoperation( some parameters );
   connect( job, SIGNAL( \fBresult( KIO::Job * )\fP ),
            this, SLOT( \fBslotResult( KIO::Job * )\fP ) );
 
.PP
 (other connects, specific to the job)
.PP
And slotResult is usually at least:
.PP
.PP
.nf

  if ( job->\fBerror()\fP )
      job->showErrorDialog( this or 0L  );
 
.PP
 
.PP
Definition at line 66 of file jobclasses.h.
.SH "Member Function Documentation"
.PP 
.SS "virtual void KIO::Job::kill (bool quietly = true)\fC [virtual]\fP"
.PP
Abort this job. This kills all subjobs and deletes the job. 
.PP
\fBParameters:\fP
.RS 4
\fIquietly\fP if false, \fBJob\fP will emit signal \fBresult\fP and ask kio_uiserver to close the progress window. \fCquietly\fP 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. 
.RE
.PP
Reimplemented in \fBKIO::SimpleJob\fP.
.PP
Referenced by KImageFilePreview::clearPreview(), and KIO::ProgressBase::slotStop().
.SS "int KIO::Job::error () const\fC [inline]\fP"
.PP
\fBReturns:\fP
.RS 4
the error code for this job, 0 if no error Error codes are defined in \fBKIO::Error\fP. Only call this method from the slot connected to \fBresult\fP(). 
.RE
.PP
Definition at line 91 of file jobclasses.h.
.PP
Referenced by KIO::PreviewJob::slotResult(), KIO::DeleteJob::slotResult(), KIO::TransferJob::slotResult(), and KIO::ChmodJob::slotResult().
.SS "int KIO::Job::progressId () const\fC [inline]\fP"
.PP
\fBReturns:\fP
.RS 4
the progress id for this job, as returned by uiserver 
.RE
.PP
Definition at line 96 of file jobclasses.h.
.PP
Referenced by Observer::open_RenameDlg(), Observer::open_SkipDlg(), and Observer::slotTransferring().
.SS "const \fBQString\fP& KIO::Job::errorText () const\fC [inline]\fP"
.PP
\fBReturns:\fP
.RS 4
a string to help understand the error, usually the url related to the error. Only call if \fBerror\fP is not 0. This is really internal, better use errorString or errorDialog. 
.RE
.PP
Definition at line 104 of file jobclasses.h.
.PP
Referenced by KIO::TransferJob::slotResult(), and KIO::ChmodJob::slotResult().
.SS "\fBQString\fP KIO::Job::errorString () const"
.PP
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.
.PP
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 \fBJob::showErrorDialog\fP. Definition at line 173 of file global.cpp.
.SS "\fBQStringList\fP KIO::Job::detailedErrorStrings (const \fBKURL\fP * reqUrl = 0L, int method = -1) const"
.PP
Converts an error code and a non-i18n error message into i18n strings suitable for presentation in a detailed error message box. \fCreqUrl\fP the request URL that generated this error message \fCmethod\fP the method that generated this error message (unimplemented)
.PP
Returns strings: caption, error + description, causes+solutions Definition at line 383 of file global.cpp.
.PP
References QString::arg(), QDateTime::currentDateTime(), KStdAccel::description(), KLocale::formatDateTime(), QString::fromLatin1(), KURL::htmlURL(), QStringList::join(), KGlobal::locale(), and KURL::protocol().
.SS "void KIO::Job::showErrorDialog (\fBQWidget\fP * parent = 0L)"
.PP
Display a dialog box to inform the user of the error given by this job. Only call if \fBerror\fP is not 0, and only in the slot connected to \fBresult\fP. 
.PP
\fBParameters:\fP
.RS 4
\fIparent\fP the parent widget for the dialog box 
.RE
.PP
Referenced by KDirLister::handleError().
.SS "void KIO::Job::setAutoErrorHandlingEnabled (bool enable, \fBQWidget\fP * parentWidget = 0)"
.PP
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.
.PP
The default is false.
.PP
See also \fBisAutoErrorHandlingEnabled\fP , \fBshowErrorDialog\fP
.PP
\fBParameters:\fP
.RS 4
\fIenable\fP enable or disable automatic error handling 
.br
\fIparentWidget\fP the parent widget, passed to \fBshowErrorDialog\fP 
.RE
.PP
Referenced by KDirOperator::del().
.SS "bool KIO::Job::isAutoErrorHandlingEnabled () const"
.PP
Returns whether automatic error handling is enabled or disabled. See also \fBsetAutoErrorHandlingEnabled\fP . 
.SS "void KIO::Job::setWindow (\fBQWidget\fP * window)"
.PP
Associate this job with a window given by \fCwindow\fP. 
.SS "\fBQWidget\fP* KIO::Job::window () const"
.PP
Returns the window this job is associated with. 
.SS "void KIO::Job::setParentJob (\fBJob\fP * parentJob)"
.PP
Set the parent \fBJob\fP. One example use of this is when \fBFileCopyJob\fP calls open_RenameDlg, it must pass the correct progress ID of the parent CopyJob (to hide the progress dialog). 
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP

.SS "\fBJob\fP* KIO::Job::parentJob () const"
.PP
\fBSee also:\fP
.RS 4
\fBsetParentJob\fP 
.RE
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP

.SS "void KIO::Job::setMetaData (const KIO::MetaData &)"
.PP
Set meta data to be sent to the slave. 
.SS "void KIO::Job::addMetaData (const \fBQString\fP & key, const \fBQString\fP & value)"
.PP
Add key/value pair to the meta data that is sent to the slave. Referenced by KIO::get(), and KIO::TransferJob::slotFinished().
.SS "void KIO::Job::addMetaData (const \fBQMap\fP< \fBQString\fP, \fBQString\fP > & values)"
.PP
Add key/value pairs to the meta data that is sent to the slave. If a certain key already existed, it will be overridden. 
.SS "void KIO::Job::mergeMetaData (const \fBQMap\fP< \fBQString\fP, \fBQString\fP > & values)"
.PP
Add key/value pairs to the meta data that is sent to the slave. If a certain key already existed, it will remain unchanged. 
.SS "MetaData KIO::Job::metaData () const"
.PP
Get meta data received from the slave. (Valid when first data is received and/or slave is finished) 
.SS "\fBQString\fP KIO::Job::queryMetaData (const \fBQString\fP & key)"
.PP
Query meta data received from the slave. (Valid when first data is received and/or slave is finished) Referenced by KIO::TransferJob::slotFinished().
.SS "void KIO::Job::result (\fBKIO::Job\fP * job)\fC [signal]\fP"
.PP
Emitted when the job is finished, in any case (completed, canceled, failed...). Use \fBerror\fP to know the result. Referenced by KIO::PreviewJob::availablePlugins(), KIO::MetaInfoJob::availablePlugins(), KIO::PreviewJob::supportedMimeTypes(), and KIO::MetaInfoJob::supportedMimeTypes().
.SS "void KIO::Job::canceled (\fBKIO::Job\fP * job)\fC [signal]\fP"
.PP
Emitted when the job is canceled. \fBThis class or method is obsolete, it is provided for compatibility only.\fP. Don't use ! Signal \fCresult\fP is emitted as well, and \fBerror()\fP is, in this case, ERR_USER_CANCELED. 
.SS "void KIO::Job::infoMessage (\fBKIO::Job\fP *, const \fBQString\fP & msg)\fC [signal]\fP"
.PP
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().
.SS "void KIO::Job::connected (\fBKIO::Job\fP *)\fC [signal]\fP"
.PP
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().
.SS "void KIO::Job::percent (\fBKIO::Job\fP * job, unsigned long percent)\fC [signal]\fP"
.PP
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 \fBKProgress\fP). Note that this signal is not emitted for finished jobs (i.e. percent is never 100). Referenced by KIO::DeleteJob::slotProcessedSize().
.SS "void KIO::Job::totalSize (\fBKIO::Job\fP *, KIO::filesize_t size)\fC [signal]\fP"
.PP
Emitted when we know the size of this job (data size for transfers, number of entries for listings). Referenced by KIO::SimpleJob::slotTotalSize().
.SS "void KIO::Job::processedSize (\fBKIO::Job\fP *, KIO::filesize_t size)\fC [signal]\fP"
.PP
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().
.SS "void KIO::Job::speed (\fBKIO::Job\fP *, unsigned long bytes_per_second)\fC [signal]\fP"
.PP
Emitted to display information about the speed of this job. 
.SS "virtual void KIO::Job::slotResult (\fBKIO::Job\fP * job)\fC [protected, virtual, slot]\fP"
.PP
Called whenever a subjob finishes. Default implementation checks for errors and propagates to parent job, then calls \fBremoveSubjob\fP. Override if you don't want subjobs errors to be propagated. Reimplemented in \fBKDirSize\fP, \fBKIO::ChmodJob\fP, \fBKIO::TransferJob\fP, \fBKIO::FileCopyJob\fP, \fBKIO::DeleteJob\fP, \fBKIO::MetaInfoJob\fP, and \fBKIO::PreviewJob\fP.
.PP
Referenced by KDirSize::slotResult().
.SS "void KIO::Job::slotSpeed (\fBKIO::Job\fP *, unsigned long bytes_per_second)\fC [protected, slot]\fP"
.PP
Forward signal from subjob. 
.SS "void KIO::Job::slotInfoMessage (\fBKIO::Job\fP *, const \fBQString\fP &)\fC [protected, slot]\fP"
.PP
Forward signal from subjob. 
.SS "void KIO::Job::slotSpeedTimeout ()\fC [protected, slot]\fP"
.PP
Remove speed information. 
.SS "virtual void KIO::Job::addSubjob (\fBJob\fP * job, bool inheritMetaData = true)\fC [protected, virtual]\fP"
.PP
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.
.PP
If \fCinheritMetaData\fP is true, the subjob will inherit the meta data from this job. Referenced by KIO::DeleteJob::slotResult().
.SS "virtual void KIO::Job::removeSubjob (\fBJob\fP * job)\fC [protected, virtual]\fP"
.PP
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. 
.SS "void KIO::Job::emitPercent (KIO::filesize_t processedSize, KIO::filesize_t totalSize)\fC [protected]\fP"
.PP
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().
.SS "void KIO::Job::emitSpeed (unsigned long bytes_per_second)\fC [protected]\fP"
.PP
Utility function for inherited jobs. Emits the speed signal and starts the timer for removing that info Referenced by KIO::SimpleJob::slotSpeed().
.SS "void KIO::Job::emitResult ()\fC [protected]\fP"
.PP
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().

.SH "Author"
.PP 
Generated automatically by Doxygen for kio Library from the source code.
