File indexing completed on 2024-07-21 03:38:57

0001 /*
0002     SPDX-FileCopyrightText: 2012 Dario Freddi <drf@kde.org>
0003 
0004     SPDX-License-Identifier: LGPL-2.1-or-later
0005 */
0006 
0007 #ifndef KAUTH_EXECUTE_JOB_H
0008 #define KAUTH_EXECUTE_JOB_H
0009 
0010 #include <kjob.h>
0011 
0012 #include "action.h"
0013 #include "actionreply.h"
0014 
0015 #include <memory>
0016 
0017 namespace KAuth
0018 {
0019 class ExecuteJobPrivate;
0020 
0021 /**
0022  * @class ExecuteJob executejob.h <KAuth/ExecuteJob>
0023  *
0024  * @brief Job for executing an Action
0025  *
0026  * To run the action synchonously use KJob::exec() and check the return code for
0027  * success.
0028  *
0029  * For longer tasks connect KJob::result(KJob*) and any other signals such as
0030  * percent(KJob*, unsigned long) and newData(const QVariantMap &) then run start().
0031  *
0032  * To check for authentiation success or problems connect to
0033  * statusChanged(KAuth::Action::AuthStatus status) signal.
0034  *
0035  * Use data() to get the return result of the action.
0036  *
0037  * @since 5.0
0038  */
0039 class KAUTHCORE_EXPORT ExecuteJob : public KJob
0040 {
0041     Q_OBJECT
0042 
0043 private:
0044     KAUTHCORE_NO_EXPORT ExecuteJob(const KAuth::Action &action, KAuth::Action::ExecutionMode mode, QObject *parent);
0045 
0046     friend class Action;
0047 
0048     friend class ExecuteJobPrivate;
0049     std::unique_ptr<ExecuteJobPrivate> const d;
0050 
0051     Q_PRIVATE_SLOT(d, void doExecuteAction())
0052     Q_PRIVATE_SLOT(d, void doAuthorizeAction())
0053     Q_PRIVATE_SLOT(d, void actionPerformedSlot(const QString &action, const KAuth::ActionReply &reply))
0054     Q_PRIVATE_SLOT(d, void progressStepSlot(const QString &action, int i))
0055     Q_PRIVATE_SLOT(d, void statusChangedSlot(const QString &action, KAuth::Action::AuthStatus status))
0056 
0057 public:
0058     /// Virtual destructor
0059     ~ExecuteJob() override;
0060 
0061     /**
0062      * Starts the job asynchronously.
0063      * @see KJob::result
0064      * @see newData
0065      * @see statusChanged
0066      */
0067     void start() override;
0068 
0069     /**
0070      * @returns the action associated with this job
0071      */
0072     Action action() const;
0073 
0074     /**
0075      * Use this to get the data set in the action by
0076      * HelperSupport::progressStep(QVariant) or returned at the end of the
0077      * action.
0078      *
0079      * This function is particularly useful once the job has completed. During
0080      * execution, simply read the data in the newData() signal.
0081      *
0082      * @returns the data set by the helper
0083      *
0084      * @see ExecuteJob::newData
0085      */
0086     QVariantMap data() const;
0087 
0088 public Q_SLOTS:
0089     /**
0090      * Attempts to halt the execution of the action associated with this job.
0091      * You should listen to the finished and result signals to work out whether
0092      * halting was successful (as long running operations can also take time
0093      * to shut down cleanly).
0094      * @return Always returns @c true
0095      *
0096      * @see HelperSupport::isStopped()
0097      * @see KJob::result
0098      * @see KJob::finished
0099      */
0100     bool kill(KillVerbosity verbosity = Quietly);
0101 
0102 Q_SIGNALS:
0103     /**
0104      * @brief Signal emitted by the helper to notify the action's progress
0105      *
0106      * This signal is emitted every time the helper's code calls the
0107      * HelperSupport::progressStep(QVariantMap) method. This is useful to let the
0108      * helper notify the execution status of a long action, also providing
0109      * some data, for example if you want to achieve some sort of progressive loading.
0110      * The meaning of the data passed here is totally application-dependent.
0111      * If you only need to pass some percentage, you can use the other signal that
0112      * pass an int.
0113      *
0114      * @param data The progress data from the helper
0115      */
0116     void newData(const QVariantMap &data);
0117 
0118     /**
0119      * @brief Signal emitted when the authentication status changes
0120      * @param status the new authentication status
0121      */
0122     void statusChanged(KAuth::Action::AuthStatus status);
0123 
0124 private:
0125     Q_DISABLE_COPY(ExecuteJob)
0126 };
0127 
0128 } // namespace Auth
0129 
0130 #endif