diff --git a/src/kauthaction.h b/src/kauthaction.h
--- a/src/kauthaction.h
+++ b/src/kauthaction.h
@@ -84,7 +84,7 @@
Q_GADGET
public:
/**
- * The three values returned by authorization methods
+ * The three values set by authorization methods
*/
enum AuthStatus {
DeniedStatus, ///< The authorization has been denied by the authorization backend
@@ -344,34 +344,9 @@
AuthStatus status() const;
/**
- * @brief Synchronously executes the action
+ * @brief Get the job object used to execute the action
*
- * This is the simpler of all the action execution methods. It sends an execution request to the
- * caller, and returns the reply directly to the caller. The ActionReply object will contain the
- * custom data coming from the helper.
- *
- * The method blocks the execution, and will
- * return only when the action has been completed (or failed). Take note, however, that with the D-Bus
- * helper proxy (currently the only one implemented on all the supported platforms), the request is
- * sent using the QDBus::BlockWithGui flag.
- *
- * This means the method will enter a local eventloop to wait
- * for the reply. This allows the application GUI to stay responsive, but you have to be prepared to
- * receive other events in the meantime.
- *
- * All the signals from the ActionWatcher class are emitted also with this method (although they're more
- * useful with the asynchronous calls)
- *
- * The method checks for authorization before to execute the action. If the user is not authorized, the
- * return value will be ActionReply::AuthorizationDeniedReply.
- * If the user cancels the authentication, the return value should be ActionReply::UserCancelledReply.
- * Due to policykit limitations, this currently only with the Mac OS X backend.
- *
- * If the helper is busy executing another action (or action group) the reply will be ActionReply::HelperBusyReply
- *
- * If the request cannot be sent for bus errors, the method returns ActionReply::DBusErrorReply.
- *
- * @return The reply from the helper, or an error reply if something's wrong.
+ * @return The KJob::ExecuteJob object to be used to run the action.
*/
ExecuteJob *execute(ExecutionMode mode = ExecuteMode);
diff --git a/src/kauthactionreply.h b/src/kauthactionreply.h
--- a/src/kauthactionreply.h
+++ b/src/kauthactionreply.h
@@ -323,45 +323,15 @@
class ActionReplyData;
/**
-* @brief Class that encapsulates a reply coming from the helper after executing
-* an action
-*
-* An instance of ActionReply is returned every time you execute an action with
-* the Action class. You get the reply directly from the Action::execute() method
-* or indirectly as a parameter of the ActionWatcher::actionPerformed() signal.
-*
-* ActionReply objects can contain both data from a successful action or an error
-* indicator. In case of success, the errorCode() is ActionReply::NoError (zero)
-* and the type() is ActionReply::Success. The data() method returns a
-* QVariantMap object that may contain custom data sent back by the helper.
-*
-* In case of errors coming from the library, the type() is
-* ActionReply::KAuthError. In this case, errorCode() will always be one of the
-* predefined errors from the ActionReply::Error enum. An error reply of
-* KAuthError type always contains an empty data() object. For some kind of
-* errors you could get a human-readable description with errorDescription().
-*
-* If, instead, the helper itself has to report some errors occurred during the
-* action execution, the type() will be (and has to be) ActionReply::HelperError.
-* In this case the data() object can contain custom data from the helper, and
-* the errorCode() and errorDescription() values are application-dependent.
-*
-* In the helper, to create an action reply object you have two choices: using
-* the constructor, or the predefined replies. For example, to create a
-* successful reply you can use the default constructor but to create a helper
-* error reply, instead of writing ActionReply(ActionReply::HelperError)
-* you could use the more convenient ActionReply::HelperErrorReply
-* constant.
-*
-* You should not use the predefined error replies to create and return new
-* errors. Replies with the KAuthError type are intended to be returned by the
-* library only. However, you can use them for comparisons.
-*
-* To quickly check for success or failure of an action, you can use succeeded()
-* or failed().
-*
-* @since 4.4
-*/
+ * @brief Class that encapsulates a reply coming from the helper after executing
+ * an action
+ *
+ * Helper applications will return this to describe the result of the action.
+ *
+ * Callers should access the reply though the KAuth::ExecuteJob job.
+ *
+ * @since 4.4
+ */
class KAUTH_EXPORT ActionReply
{
public:
diff --git a/src/kauthexecutejob.h b/src/kauthexecutejob.h
--- a/src/kauthexecutejob.h
+++ b/src/kauthexecutejob.h
@@ -17,8 +17,8 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA .
*/
-#ifndef ASYNC_ACTION_H
-#define ASYNC_ACTION_H
+#ifndef EXECUTE_JOB_H
+#define EXECUTE_JOB_H
#include
@@ -31,7 +31,19 @@
{
/**
- * @brief Job executing an Action
+ * @brief Job for executing an Action
+ *
+ * To run the action synchonously use KJob::exec() and check the return code for
+ * success.
+ *
+ * For longer tasks connect KJob::result(KJob*) and any other signals such as
+ * percent(KJob*, unsigned long) and newData(const QVariantMap &) then run start().
+ *
+ * To check for authentiation success or problems connect to
+ * statusChanged(KAuth::Action::AuthStatus status) signal.
+ *
+ * Use data() to get the return result of the action.
+ *
* @since 5.0
*/
class KAUTH_EXPORT ExecuteJob : public KJob
@@ -70,7 +82,15 @@
Action action() const;
/**
- * @returns the data sent by the helper
+ * Use this to get the data set in the action by
+ * HelperSupport::progressStep(QVariant) or returned at the end of the
+ * action.
+ *
+ * This function is particularly useful once the job has completed. During
+ * execution, simply read the data in the newData signal.
+ *
+ * @see ExecuteJob::newData
+ * @returns the data set by the helper
*/
QVariantMap data() const;
diff --git a/src/kauthhelpersupport.h b/src/kauthhelpersupport.h
--- a/src/kauthhelpersupport.h
+++ b/src/kauthhelpersupport.h
@@ -48,8 +48,8 @@
* @brief Send a progressStep signal to the caller application
*
* You can use this method to notify progress information about the
- * action execution. When you call this method, the ActionWatcher
- * object associated with the current action will emit the progressStep(int)
+ * action execution. When you call this method, the KAuth::ExecuteJob
+ * object associated with the current action will emit the KJob::percent(KJob*, unsigned long)
* signal. The meaning of the integer passed here is totally application dependent,
* but you'll want to use it as a sort of percentage.
* If you need to be more expressive, use the other overload which takes a QVariantMap
@@ -62,9 +62,10 @@
* @brief Send a progressStep signal to the caller application
*
* You can use this method to notify progress information about the
-* action execution. When you call this method, the ActionWatcher
+* action execution. When you call this method, the KAuth::ExecuteJob
* object associated with the current action will emit the progressStep(QVariantMap)
* signal. The meaning of the data passed here is totally application dependent.
+*
* If you only need a simple percentage value, use the other overload which takes an int.
*
* @param data The progress data
@@ -78,6 +79,7 @@
* execution of the current action. If this happens, your helper should
* return (NOT exit). The meaning of the data you return in this case is
* application-dependent.
+ *
* It's good practice to check it regularly if you have a long-running action
*
* @return true if the helper has been asked to stop, false otherwise