KAuth

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

KDE's Doxygen guidelines are available online.