kjob.h

/*  This file is part of the KDE project
    Copyright (C) 2000 Stephan Kulow <[email protected]>
                       David Faure <[email protected]>
    Copyright (C) 2006 Kevin Ottens <[email protected]>

    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 <kcoreaddons_export.h>
#include <QObject>
#include <QPair>

class KJobUiDelegate;

class KJobPrivate;
class KCOREADDONS_EXPORT KJob : public QObject
{
    Q_OBJECT
    Q_PROPERTY(int error READ error NOTIFY result)
    Q_PROPERTY(QString errorText READ errorText NOTIFY result)
    Q_PROPERTY(QString errorString READ errorString NOTIFY result)
    Q_PROPERTY(unsigned long percent READ percent NOTIFY percent)
    Q_PROPERTY(Capabilities capabilities READ capabilities CONSTANT)

public:
    enum Unit { Bytes, Files, Directories };
    Q_ENUM(Unit)

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

    Q_DECLARE_FLAGS(Capabilities, Capability)
    Q_FLAG(Capabilities)

    
    explicit KJob(QObject *parent = nullptr);

    ~KJob() override;

    void setUiDelegate(KJobUiDelegate *delegate);

    KJobUiDelegate *uiDelegate() const;

    Capabilities capabilities() const;

    bool isSuspended() const;

    Q_SCRIPTABLE virtual void start() = 0;

    enum KillVerbosity { Quietly, EmitResult };
    Q_ENUM(KillVerbosity)

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;

    Q_SCRIPTABLE qulonglong processedAmount(Unit unit) const;

    Q_SCRIPTABLE qulonglong totalAmount(Unit unit) const;

    unsigned long percent() const;

    void setAutoDelete(bool autodelete);

    bool isAutoDelete() const;

Q_SIGNALS:
    void finished(KJob *job
#if !defined(DOXYGEN_SHOULD_SKIP_THIS)
                  , QPrivateSignal
#endif
                 );

    void suspended(KJob *job
#if !defined(DOXYGEN_SHOULD_SKIP_THIS)
                   , QPrivateSignal
#endif
                  );

    void resumed(KJob *job
#if !defined(DOXYGEN_SHOULD_SKIP_THIS)
                 , QPrivateSignal
#endif
                );

    void result(KJob *job
#if !defined(DOXYGEN_SHOULD_SKIP_THIS)
                , QPrivateSignal
#endif
               );

    void description(KJob *job, const QString &title,
                     const QPair<QString, QString> &field1 = QPair<QString, QString>(),
                     const QPair<QString, QString> &field2 = QPair<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:
    // These signals must be connected from KIO::KCoreDirLister (among others),
    // therefore they must be public.
    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:
    void finishJob(bool emitResult);

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

Q_DECLARE_METATYPE(KJob::Unit)
Q_DECLARE_OPERATORS_FOR_FLAGS(KJob::Capabilities)

#endif