1/*
2 SPDX-FileCopyrightText: 2012 Dario Freddi <drf@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-or-later
5*/
6
7#ifndef KAUTH_EXECUTE_JOB_H
8#define KAUTH_EXECUTE_JOB_H
9
10#include <kjob.h>
11
12#include "action.h"
13#include "actionreply.h"
14
15#include <memory>
16
17namespace KAuth
18{
19class ExecuteJobPrivate;
20
21/*!
22 * \class KAuth::ExecuteJob
23 * \inmodule KAuth
24 * \inheaderfile KAuth/ExecuteJob
25 *
26 * \brief Job for executing an Action.
27 *
28 * To run the action synchonously use KJob::exec() and check the return code for
29 * success.
30 *
31 * For longer tasks connect KJob::result(KJob*) and any other signals such as
32 * percent(KJob*, unsigned long) and newData(const QVariantMap &) then run start().
33 *
34 * To check for authentiation success or problems connect to
35 * statusChanged(KAuth::Action::AuthStatus status) signal.
36 *
37 * Use data() to get the return result of the action.
38 *
39 * \since 5.0
40 */
41class KAUTHCORE_EXPORT ExecuteJob : public KJob
42{
43 Q_OBJECT
44
45private:
46 KAUTHCORE_NO_EXPORT ExecuteJob(const KAuth::Action &action, KAuth::Action::ExecutionMode mode, QObject *parent);
47
48 friend class Action;
49
50 friend class ExecuteJobPrivate;
51 std::unique_ptr<ExecuteJobPrivate> const d;
52
53 Q_PRIVATE_SLOT(d, void doExecuteAction())
54 Q_PRIVATE_SLOT(d, void doAuthorizeAction())
55 Q_PRIVATE_SLOT(d, void actionPerformedSlot(const QString &action, const KAuth::ActionReply &reply))
56 Q_PRIVATE_SLOT(d, void progressStepSlot(const QString &action, int i))
57 Q_PRIVATE_SLOT(d, void statusChangedSlot(const QString &action, KAuth::Action::AuthStatus status))
58
59public:
60 ~ExecuteJob() override;
61
62 /*!
63 * \reimp
64 *
65 * Starts the job asynchronously.
66 * \sa KJob::result
67 * \sa newData
68 * \sa statusChanged
69 */
70 void start() override;
71
72 /*!
73 * Returns the action associated with this job
74 */
75 Action action() const;
76
77 /*!
78 * Use this to get the data set in the action by
79 * HelperSupport::progressStep(QVariant) or returned at the end of the
80 * action.
81 *
82 * This function is particularly useful once the job has completed. During
83 * execution, simply read the data in the newData() signal.
84 *
85 * Returns the data set by the helper
86 *
87 * \sa ExecuteJob::newData
88 */
89 QVariantMap data() const;
90
91public Q_SLOTS:
92 /*!
93 * Attempts to halt the execution of the action associated with this job.
94 * You should listen to the finished and result signals to work out whether
95 * halting was successful (as long running operations can also take time
96 * to shut down cleanly).
97 * Always returns \c true
98 *
99 * \sa HelperSupport::isStopped()
100 * \sa KJob::result
101 * \sa KJob::finished
102 */
103 bool kill(KillVerbosity verbosity = Quietly);
104
105Q_SIGNALS:
106 /*!
107 * \brief Signal emitted by the helper to notify the action's progress
108 *
109 * This signal is emitted every time the helper's code calls the
110 * HelperSupport::progressStep(QVariantMap) method. This is useful to let the
111 * helper notify the execution status of a long action, also providing
112 * some data, for example if you want to achieve some sort of progressive loading.
113 * The meaning of the data passed here is totally application-dependent.
114 * If you only need to pass some percentage, you can use the other signal that
115 * pass an int.
116 *
117 * \a data The progress data from the helper
118 */
119 void newData(const QVariantMap &data);
120
121 /*!
122 * \brief Signal emitted when the authentication status changes
123 * \a status the new authentication status
124 */
125 void statusChanged(KAuth::Action::AuthStatus status);
126
127private:
128 Q_DISABLE_COPY(ExecuteJob)
129};
130
131} // namespace Auth
132
133#endif
134

source code of kauth/src/executejob.h