kjob.h

Go to the documentation of this file.

/*  This file is part of the KDE project
    Copyright (C) 2000 Stephan Kulow <coolo@kde.org>
                       David Faure <faure@kde.org>
    Copyright (C) 2006 Kevin Ottens <ervin@kde.org>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License version 2 as published by the Free Software Foundation.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.

*/

#ifndef KJOB_H
#define KJOB_H

#include <kdecore_export.h>
#include <QtCore/QObject>
#include <QtCore/QPair>

class KJobUiDelegate;

class KJobPrivate;
class KDECORE_EXPORT KJob : public QObject
{
    Q_OBJECT
    Q_ENUMS( KillVerbosity Capability Unit )
    Q_FLAGS( Capabilities )

public:
    enum Unit { Bytes, Files, Directories };

    enum Capability { NoCapabilities = 0x0000,
                      Killable       = 0x0001,
                      Suspendable    = 0x0002 };

    Q_DECLARE_FLAGS( Capabilities, Capability )

    
    explicit KJob( QObject *parent = 0 );

    virtual ~KJob();

    void setUiDelegate( KJobUiDelegate *delegate );

    KJobUiDelegate *uiDelegate() const;

    Capabilities capabilities() const;

    bool isSuspended() const;

    virtual void start() = 0;

    enum KillVerbosity { Quietly, EmitResult };

public Q_SLOTS:
    bool kill( KillVerbosity verbosity = Quietly );

    bool suspend();

    bool resume();

protected:
    virtual bool doKill();

    virtual bool doSuspend();

    virtual bool doResume();

    void setCapabilities( Capabilities capabilities );

public:
    bool exec();

    enum
    {
        /*** Indicates there is no error */
        NoError = 0,
        /*** Indicates the job was killed */
        KilledJobError = 1,
        /*** Subclasses should define error codes starting at this value */
        UserDefinedError = 100
    };


    int error() const;

    QString errorText() const;

    virtual QString errorString() const;


    qulonglong processedAmount(Unit unit) const;

    qulonglong totalAmount(Unit unit) const;

    unsigned long percent() const;

    void setAutoDelete( bool autodelete );

    bool isAutoDelete() const;

Q_SIGNALS:
#if !defined(Q_MOC_RUN) && !defined(DOXYGEN_SHOULD_SKIP_THIS) && !defined(IN_IDE_PARSER)
private: // don't tell moc, doxygen or kdevelop, but those signals are in fact private
#endif

    void finished(KJob *job);

    void suspended(KJob *job);

    void resumed(KJob *job);

    void result(KJob *job);

Q_SIGNALS:
    void description(KJob *job, const QString &title,
                     const QPair<QString, QString> &field1 = qMakePair(QString(), QString()),
                     const QPair<QString, QString> &field2 = qMakePair(QString(), QString()));

    void infoMessage( KJob *job, const QString &plain, const QString &rich = QString() );

    void warning( KJob *job, const QString &plain, const QString &rich = QString() );


Q_SIGNALS:
#if !defined(Q_MOC_RUN) && !defined(DOXYGEN_SHOULD_SKIP_THIS) && !defined(IN_IDE_PARSER)
private: // don't tell moc, doxygen or kdevelop, but those signals are in fact private
#endif

    void totalAmount(KJob *job, KJob::Unit unit, qulonglong amount);

    void processedAmount(KJob *job, KJob::Unit unit, qulonglong amount);

    void totalSize(KJob *job, qulonglong size);

    void processedSize(KJob *job, qulonglong size);

    void percent( KJob *job, unsigned long percent );

    void speed(KJob *job, unsigned long speed);

protected:
    void setError( int errorCode );

    void setErrorText( const QString &errorText );


    void setProcessedAmount(Unit unit, qulonglong amount);

    void setTotalAmount(Unit unit, qulonglong amount);

    void setPercent( unsigned long percentage );


    void emitResult();

    void emitPercent( qulonglong processedAmount, qulonglong totalAmount );

    void emitSpeed(unsigned long speed);

protected:
    KJobPrivate *const d_ptr;
    KJob(KJobPrivate &dd, QObject *parent);

private:
    Q_PRIVATE_SLOT(d_func(), void _k_speedTimeout())
    Q_DECLARE_PRIVATE(KJob)
};

Q_DECLARE_OPERATORS_FOR_FLAGS( KJob::Capabilities )

#endif