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

source code of kauth/src/executejob.h