KAuth

executejob.h
1 /*
2  SPDX-FileCopyrightText: 2012 Dario Freddi <[email protected]>
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 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  */
39 class KAUTHCORE_EXPORT ExecuteJob : public KJob
40 {
41  Q_OBJECT
42 
43  ExecuteJob(const KAuth::Action &action, KAuth::Action::ExecutionMode mode, QObject *parent);
44 
45  friend class Action;
46 
47  friend class ExecuteJobPrivate;
48  std::unique_ptr<ExecuteJobPrivate> const d;
49 
50  Q_PRIVATE_SLOT(d, void doExecuteAction())
51  Q_PRIVATE_SLOT(d, void doAuthorizeAction())
52  Q_PRIVATE_SLOT(d, void actionPerformedSlot(const QString &action, const KAuth::ActionReply &reply))
53  Q_PRIVATE_SLOT(d, void progressStepSlot(const QString &action, int i))
54  Q_PRIVATE_SLOT(d, void statusChangedSlot(const QString &action, KAuth::Action::AuthStatus status))
55 
56 public:
57  /// Virtual destructor
58  ~ExecuteJob() override;
59 
60  /**
61  * Starts the job asynchronously.
62  * @see KJob::result
63  * @see newData
64  * @see statusChanged
65  */
66  void start() override;
67 
68  /**
69  * @returns the action associated with this job
70  */
71  Action action() const;
72 
73  /**
74  * Use this to get the data set in the action by
75  * HelperSupport::progressStep(QVariant) or returned at the end of the
76  * action.
77  *
78  * This function is particularly useful once the job has completed. During
79  * execution, simply read the data in the newData() signal.
80  *
81  * @returns the data set by the helper
82  *
83  * @see ExecuteJob::newData
84  */
85  QVariantMap data() const;
86 
87 public Q_SLOTS:
88  /**
89  * Attempts to halt the execution of the action associated with this job.
90  * You should listen to the finished and result signals to work out whether
91  * halting was successful (as long running operations can also take time
92  * to shut down cleanly).
93  * @return Always returns @c true
94  *
95  * @see HelperSupport::isStopped()
96  * @see KJob::result
97  * @see KJob::finished
98  */
99  bool kill(KillVerbosity verbosity = Quietly);
100 
101 Q_SIGNALS:
102  /**
103  * @brief Signal emitted by the helper to notify the action's progress
104  *
105  * This signal is emitted every time the helper's code calls the
106  * HelperSupport::progressStep(QVariantMap) method. This is useful to let the
107  * helper notify the execution status of a long action, also providing
108  * some data, for example if you want to achieve some sort of progressive loading.
109  * The meaning of the data passed here is totally application-dependent.
110  * If you only need to pass some percentage, you can use the other signal that
111  * pass an int.
112  *
113  * @param data The progress data from the helper
114  */
115  void newData(const QVariantMap &data);
116 
117  /**
118  * @brief Signal emitted when the authentication status changes
119  * @param status the new authentication status
120  */
121  void statusChanged(KAuth::Action::AuthStatus status);
122 
123 private:
124  Q_DISABLE_COPY(ExecuteJob)
125 };
126 
127 } // namespace Auth
128 
129 #endif
Q_SCRIPTABLE Q_NOREPLY void start()
Job for executing an Action.
Definition: executejob.h:39
AuthStatus
The three values set by authorization methods.
Definition: action.h:82
Class that encapsulates a reply coming from the helper after executing an action.
Definition: actionreply.h:334
Q_SCRIPTABLE CaptureState status()
Definition: action.cpp:18
Class to access, authorize and execute actions.
Definition: action.h:75
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:14:27 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.