kjob.h

/*
    This file is part of the KDE project

    SPDX-FileCopyrightText: 2000 Stephan Kulow <[email protected]>
    SPDX-FileCopyrightText: 2000 David Faure <[email protected]>
    SPDX-FileCopyrightText: 2006 Kevin Ottens <[email protected]>

    SPDX-License-Identifier: LGPL-2.0-only
*/

#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(ulong percent READ percent NOTIFY percent) // KF6 TODO: make "int", is enough
    Q_PROPERTY(Capabilities capabilities READ capabilities CONSTANT)

public:
    enum Unit {
        Bytes,          
        Files,          
        Directories,    
        Items,          
    };
    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(K_DOXYGEN)
                  , QPrivateSignal
#endif
                 );

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

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

    void result(KJob *job
#if !defined(K_DOXYGEN)
                , 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:
    bool isFinished() const;

    void setError(int errorCode);

    void setErrorText(const QString &errorText);

    void setProcessedAmount(Unit unit, qulonglong amount);

    void setTotalAmount(Unit unit, qulonglong amount);

    void setProgressUnit(Unit unit);

    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