File indexing completed on 2025-04-20 12:19:12
0001 /* 0002 SPDX-FileCopyrightText: 2012 Dario Freddi <drf@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.1-or-later 0005 */ 0006 0007 #ifndef KAUTH_EXECUTE_JOB_H 0008 #define KAUTH_EXECUTE_JOB_H 0009 0010 #include <kjob.h> 0011 0012 #include "action.h" 0013 #include "actionreply.h" 0014 0015 #include <memory> 0016 0017 namespace KAuth 0018 { 0019 class ExecuteJobPrivate; 0020 0021 /** 0022 * @class ExecuteJob executejob.h <KAuth/ExecuteJob> 0023 * 0024 * @brief Job for executing an Action 0025 * 0026 * To run the action synchonously use KJob::exec() and check the return code for 0027 * success. 0028 * 0029 * For longer tasks connect KJob::result(KJob*) and any other signals such as 0030 * percent(KJob*, unsigned long) and newData(const QVariantMap &) then run start(). 0031 * 0032 * To check for authentiation success or problems connect to 0033 * statusChanged(KAuth::Action::AuthStatus status) signal. 0034 * 0035 * Use data() to get the return result of the action. 0036 * 0037 * @since 5.0 0038 */ 0039 class KAUTHCORE_EXPORT ExecuteJob : public KJob 0040 { 0041 Q_OBJECT 0042 0043 private: 0044 KAUTHCORE_NO_EXPORT ExecuteJob(const KAuth::Action &action, KAuth::Action::ExecutionMode mode, QObject *parent); 0045 0046 friend class Action; 0047 0048 friend class ExecuteJobPrivate; 0049 std::unique_ptr<ExecuteJobPrivate> const d; 0050 0051 Q_PRIVATE_SLOT(d, void doExecuteAction()) 0052 Q_PRIVATE_SLOT(d, void doAuthorizeAction()) 0053 Q_PRIVATE_SLOT(d, void actionPerformedSlot(const QString &action, const KAuth::ActionReply &reply)) 0054 Q_PRIVATE_SLOT(d, void progressStepSlot(const QString &action, int i)) 0055 Q_PRIVATE_SLOT(d, void statusChangedSlot(const QString &action, KAuth::Action::AuthStatus status)) 0056 0057 public: 0058 /// Virtual destructor 0059 ~ExecuteJob() override; 0060 0061 /** 0062 * Starts the job asynchronously. 0063 * @see KJob::result 0064 * @see newData 0065 * @see statusChanged 0066 */ 0067 void start() override; 0068 0069 /** 0070 * @returns the action associated with this job 0071 */ 0072 Action action() const; 0073 0074 /** 0075 * Use this to get the data set in the action by 0076 * HelperSupport::progressStep(QVariant) or returned at the end of the 0077 * action. 0078 * 0079 * This function is particularly useful once the job has completed. During 0080 * execution, simply read the data in the newData() signal. 0081 * 0082 * @returns the data set by the helper 0083 * 0084 * @see ExecuteJob::newData 0085 */ 0086 QVariantMap data() const; 0087 0088 public Q_SLOTS: 0089 /** 0090 * Attempts to halt the execution of the action associated with this job. 0091 * You should listen to the finished and result signals to work out whether 0092 * halting was successful (as long running operations can also take time 0093 * to shut down cleanly). 0094 * @return Always returns @c true 0095 * 0096 * @see HelperSupport::isStopped() 0097 * @see KJob::result 0098 * @see KJob::finished 0099 */ 0100 bool kill(KillVerbosity verbosity = Quietly); 0101 0102 Q_SIGNALS: 0103 /** 0104 * @brief Signal emitted by the helper to notify the action's progress 0105 * 0106 * This signal is emitted every time the helper's code calls the 0107 * HelperSupport::progressStep(QVariantMap) method. This is useful to let the 0108 * helper notify the execution status of a long action, also providing 0109 * some data, for example if you want to achieve some sort of progressive loading. 0110 * The meaning of the data passed here is totally application-dependent. 0111 * If you only need to pass some percentage, you can use the other signal that 0112 * pass an int. 0113 * 0114 * @param data The progress data from the helper 0115 */ 0116 void newData(const QVariantMap &data); 0117 0118 /** 0119 * @brief Signal emitted when the authentication status changes 0120 * @param status the new authentication status 0121 */ 0122 void statusChanged(KAuth::Action::AuthStatus status); 0123 0124 private: 0125 Q_DISABLE_COPY(ExecuteJob) 0126 }; 0127 0128 } // namespace Auth 0129 0130 #endif