You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdenetwork/kopete/libkopete/kopetetask.h

163 lines
5.2 KiB

/*
kopetetask.h - Kopete Task
Copyright (c) 2004 by Richard Smith <kde@metafoo.co.uk>
Kopete (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
*************************************************************************
* *
* This library is free software; you can redistribute it and/or *
* modify it under the terms of the GNU Lesser General Public *
* License as published by the Free Software Foundation; either *
* version 2 of the License, or (at your option) any later version. *
* *
*************************************************************************
*/
#ifndef KOPETETASK_H
#define KOPETETASK_H
#include <qobject.h>
#include <kdemacros.h>
namespace Kopete
{
/**
* The base class for all tasks.
* For most tasks created in Kopete, the code looks like
*
* \code
* Kopete::Task *task = someobject->someoperation( some parameters );
* connect( task, SIGNAL( result( Kopete::Task * ) ),
* this, SLOT( slotResult( Kopete::Task * ) ) );
* \endcode
* (other connects, specific to the job)
*
* And slotResult is usually at least:
*
* \code
* if ( !task->succeeded() )
* Kopete::UI::Global::showTaskError( task );
* \endcode
*
* Much of the ideas (and some of the documentation and function names) for this
* class come from KIO::Job.
* @author Richard Smith <kde@metafoo.co.uk>
*/
class Task : public QObject
{
Q_OBJECT
protected:
Task();
public:
~Task();
/**
* Returns whether the task completed successfully.
* Only call this method from the slot connected to result().
* @return if the task succeeded, returns true, otherwise returns false.
*/
bool succeeded() 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.
*
* Use this to display the error yourself, but for a dialog box
* use Kopete::UI::Global::showTaskError. Do not call it if succeeded()
* returns true.
* @return the error message and if there is no error, a message
* telling the user that the app is broken, so check with
* succeeded() whether there is an error.
*/
const QString &errorString() const;
/** Flags for the abort() function */
enum AbortFlags { AbortNormal = 0, AbortEmitResult = 1 };
public slots:
/**
* Abort this task.
* This aborts all subtasks and deletes the task.
*
* @param flags a combination of flags from AbortFlags. If AbortEmitResult is
* set, Job will emit the result signal. AbortEmitResult is removed
* from the flags passed to the abort function of subtasks.
*/
virtual void abort( int flags = AbortNormal );
signals:
/**
* Emitted when the task is finished, in any case (completed, canceled,
* failed...). Use error() to find the result.
* @param task the task that emitted this signal
*/
void result( Kopete::Task *task );
/**
* Emitted to display status information about this task.
* Examples of messages are:
* "Removing ICQ contact Joe from server-side list",
* "Loading account plugin", etc.
* @param task the task that emitted this signal
* @param message the info message
*/
void statusMessage( Kopete::Task *task, const QString &message );
protected:
/**
* Add a task that has to be completed before a result is emitted. This
* obviously should not be called after the finish signal is emitted by
* the subtask.
*
* @param task the subtask to add
*/
virtual void addSubtask( Task *task );
enum RemoveSubtaskIfLast { IfLastDoNothing, IfLastEmitResult };
/**
* 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.
*
* @param task the subjob to add
* @param actionIfLast the action to take if this is the last subtask.
* If set to IfLastEmitResult, the error information from @p task
* will be copied to this object, and emitResult() will be called.
*/
virtual void removeSubtask( Task *task, RemoveSubtaskIfLast actionIfLast = IfLastEmitResult );
enum Result { ResultFailed = 0, ResultSucceeded = 1 };
/**
* Utility function to emit the result signal, and suicide this job.
* Sets the stored result and error message to @p result and @p errorMessage.
* You should call this instead of emitting the result() signal yourself.
*/
void emitResult( Result result = ResultSucceeded, const QString &errorMessage = QString::null );
protected slots:
/**
* Called whenever a subtask finishes.
* The default implementation checks for errors and propagates
* them to this task, then calls removeSubtask().
* Override if you want to provide a different @p actionIfLast to
* removeSubtask, or want to perform some other processing in response
* to a subtask finishing
* @param task the subtask that finished
* @see result()
*/
virtual void slotResult( Kopete::Task *task );
private:
class Private;
Private *d;
};
}
#endif
// vim: set noet ts=4 sts=4 sw=4: