void MyApp::runAction()
{
    action = KAuth::Action("org.kde.myapp.action");
    KAuth::ExecuteJob *job = action.execute();
    connect(job, &KAuth::ExecuteJob::result, this, &MyApp::actionResult);
    job->start();
}

void MyApp::actionResult(KJob *kjob)
{
    auto job = qobject_cast<KAuth::ExecuteJob *>(kjob);
    qDebug() << job.error() << job.data();
}

Member Function Documentation

Action::Action()

Default constructor

This constructor sets the name to the empty string. Such an action is invalid and cannot be authorized nor executed, so you need to call setName() before you can use the object.

Action::Action(const QString &name)

This creates a new action object with this name name The name of the new action

[since 5.68] Action::Action(const QString &name, const KAuth::Action::DetailsMap &details)

This creates a new action object with this name and details name The name of the new action details The details of the action

This function was introduced in 5.68.

See also setDetailsV2.

Action::Action(const KAuth::Action &action)

Copy constructor

void Action::addArgument(const QString &key, const QVariant &value)

Convenience method to add an argument.

This method adds the pair key/value to the QVariantMap used to send custom data to the helper.

Use this method if you don't want to create a new QVariantMap only to add a new entry.

key The new entry's key

value The value of the new entry

QVariantMap Action::arguments() const

Returns map object used to pass arguments to the helper.

This method returns the variant map that the application can use to pass arbitrary data to the helper when executing the action.

Returns the arguments map that will be passed to the helper.

See also setArguments().

[since 5.68] KAuth::Action::DetailsMap Action::detailsV2() const

Gets the action's details

The details that will be shown in the authorization dialog, if the backend supports it.

Returns The action's details

This function was introduced in 5.68.

See also setDetailsV2().

KAuth::ExecuteJob *Action::execute(KAuth::Action::ExecutionMode mode = ExecuteMode)

Get the job object used to execute the action

Returns the KAuth::ExecuteJob object to be used to run the action.

[since 4.5] bool Action::hasHelper() const

Checks if the action has an helper

This function can be used to check if an helper will be called upon the execution of an action. Such an helper can be set through setHelperId(). If this function returns false, upon execution the action will be just authorized.

Returns Whether the action has an helper or not

This function was introduced in 4.5.

See also setHelperId.

QString Action::helperId() const

Gets the default helper ID used for actions execution

The helper ID is the string that uniquely identifies the helper in the system. It is the string passed to the KAUTH_HELPER_MAIN() macro in the helper source. Because one could have different helpers, you need to specify an helper ID for each execution, or set a default ID by calling setHelperId(). This method returns the current default value.

Returns the default helper ID.

See also setHelperId().

bool Action::isValid() const

Returns if the object represents a valid action

Action names have to respect a simple syntax. They have to be all in lowercase characters, separated by dots. Dots can't appear at the beginning and at the end of the name.

In other words, the action name has to match this perl-like regular expression:

/^[a-z]+(\.[a-z]+)*$/

This method returns false if the action name doesn't match the valid syntax.

If the backend supports it, this method also checks if the action is valid and recognized by the backend itself.

Invalid actions cannot be authorized nor executed. The empty string is not a valid action name, so the default constructor returns an invalid action.

QString Action::name() const

Gets the action's name.

This is the unique attribute that identifies an action object. Two action objects with the same name always refer to the same action.

Returns The action name

See also setName().

[since 6.0] QWindow *Action::parentWindow() const

Returns the parent widget for the authentication dialog for this action

Returns a QWindow which will is being used as the dialog's parent

This function was introduced in 6.0.

See also setParentWindow().

void Action::setArguments(const QVariantMap &arguments)

Sets the map object used to pass arguments to the helper.

This method sets the variant map that the application can use to pass arbitrary data to the helper when executing the action.

Only non-gui variants are supported.

arguments The new arguments map

See also arguments().

[since 5.68] void Action::setDetailsV2(const KAuth::Action::DetailsMap &details)

Sets the action's details

You can use this function to provide the user more details (if the backend supports it) on the action being authorized in the authorization dialog

details the details describing the action. For e.g, "DetailMessage" key can be used to give a customized authentication message.

This function was introduced in 5.68.

See also detailsV2().

void Action::setHelperId(const QString &id)

Sets the default helper ID used for actions execution

This method sets the helper ID which contains the body of this action. If the string is non-empty, the corresponding helper will be fired and the action executed inside the helper. Otherwise, the action will be just authorized.

id The default helper ID.

See also hasHelper and helperId.

void Action::setName(const QString &name)

Sets the action's name.

It's not common to change the action name after its creation. Usually you set the name with the constructor (and you have to, because there's no default constructor)

See also name().

[since 6.0] void Action::setParentWindow(QWindow *parent)

Sets a parent window for the authentication dialog

This function is used for explicitly setting a parent window for an eventual authentication dialog required when authorization is triggered. Some backends, in fact, (like polkit-1) need to have a parent explicitly set for displaying the dialog correctly.

parent A QWidget which will be used as the dialog's parent

This function was introduced in 6.0.

See also parentWindow().

[since 5.29] void Action::setTimeout(int timeout)

Sets the action's timeout.

The timeout of the action in milliseconds -1 means the default D-Bus timeout (usually 25 seconds)

This function was introduced in 5.29.

See also timeout().

[since 5.93] void Action::setTimeout(std::chrono::milliseconds msec)

Convenience overload suporting C++ chrono types. May also be used with chrono literals.

This function was introduced in 5.93.

KAuth::Action::AuthStatus Action::status() const

Gets information about the authorization status of an action

This methods query the authorization backend to know if the user can try to acquire the authorization for this action. If the result is Action::AuthRequired, the user can try to acquire the authorization by authenticating.

It should not be needed to call this method directly, because the execution methods already take care of all the authorization stuff.

Returns

• Action::Denied if the user doesn't have the authorization to execute the action,
• Action::Authorized if the action can be executed,
• Action::AuthRequired if the user could acquire the authorization after authentication,
• Action::UserCancelled if the user cancels the authentication dialog. Not currently supported by the Polkit backend

[since 5.29] int Action::timeout() const

Gets the action's timeout.

The timeout of the action in milliseconds -1 means the default D-Bus timeout (usually 25 seconds)

Returns The action timeouts

This function was introduced in 5.29.

See also setTimeout().

bool Action::operator!=(const KAuth::Action &action) const

Negated comparison operator

Returns the negation of operator==

action the action to compare to

Returns true if the two actions are different and not both invalid

bool Action::operator==(const KAuth::Action &action) const

Comparison operator

This comparison operator compares the names of this and action and returns whether they are the same. It does not care about the arguments stored in the actions. However, if two actions are invalid they'll match as equal, even if the invalid names are different.

Returns true if the two actions are the same or both invalid