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 | |
17 | namespace KAuth |
18 | { |
19 | class 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 | */ |
41 | class KAUTHCORE_EXPORT ExecuteJob : public KJob |
42 | { |
43 | Q_OBJECT |
44 | |
45 | private: |
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 | |
59 | public: |
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 | |
91 | public 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 | |
105 | Q_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 | |
127 | private: |
128 | Q_DISABLE_COPY(ExecuteJob) |
129 | }; |
130 | |
131 | } // namespace Auth |
132 | |
133 | #endif |
134 | |