KAuth

action.h
1 /*
2  SPDX-FileCopyrightText: 2009-2012 Dario Freddi <[email protected]>
3  SPDX-FileCopyrightText: 2008 Nicola Gigante <[email protected]>
4  SPDX-FileCopyrightText: 2022 Harald Sitter <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.1-or-later
7 */
8 
9 #ifndef KAUTH_ACTION_H
10 #define KAUTH_ACTION_H
11 
12 #include "kauthcore_export.h"
13 
14 #include <QHash>
15 #include <QSharedDataPointer>
16 #include <QString>
17 #include <QVariant>
18 
19 #if __has_include(<chrono>)
20 #include <chrono>
21 #endif
22 
23 namespace KAuth
24 {
25 class ExecuteJob;
26 
27 class ActionData;
28 /**
29  * @class Action action.h <KAuth/Action>
30  *
31  * @brief Class to access, authorize and execute actions.
32  *
33  * This is the main class of the KAuth API. It provides the interface to
34  * manipulate actions. Every action is identified by its name. Every instance
35  * of the Action class with the same name refers to the same action.
36  *
37  * Once you have an action object you can tell the helper to execute it
38  * (asking the user to authenticate if needed) with the execute() method.
39  * The simplest thing to do is to execute a single action synchronously
40  * blocking for the reply by calling KJob::exec() on the job object returned by
41  * execute().
42  *
43  * For asynchronous calls, use KAuth::ExecuteJob::start() instead.
44  * It sends the request
45  * to the helper and returns immediately. Before doing so you should however
46  * connect to at least the KJob::result(KJob *) signal to receive a slot call
47  * once the action is done executing.
48  *
49  * To use the execute() method you have to set the default helper's ID using
50  * the setHelperId() static method. Alternatively, you can specify the helperID using
51  * the overloaded version of the methods that takes it as a parameter.
52  *
53  * Each action object contains a QVariantMap object that is passed directly to the
54  * helper when the action is executed. You can access this map using the arguments()
55  * method. You can insert into it any kind of custom data you need to pass to the helper.
56  *
57  * @code
58  * void MyApp::runAction()
59  * {
60  * action = KAuth::Action("org.kde.myapp.action");
61  * KAuth::ExecuteJob *job = action.execute();
62  * connect(job, &KAuth::ExecuteJob::result, this, &MyApp::actionResult);
63  * job->start();
64  * }
65  *
66  * void MyApp::actionResult(KJob *kjob)
67  * {
68  * auto job = qobject_cast<KAuth::ExecuteJob *>(kjob);
69  * qDebug() << job.error() << job.data();
70  * }
71  * @endcode
72  *
73  * @since 4.4
74  */
75 class KAUTHCORE_EXPORT Action
76 {
77  Q_GADGET
78 public:
79  /**
80  * The three values set by authorization methods
81  */
82  enum AuthStatus {
83  DeniedStatus, ///< The authorization has been denied by the authorization backend
84  ErrorStatus, ///< An error occurred
85  InvalidStatus, ///< An invalid action cannot be authorized
86  AuthorizedStatus, ///< The authorization has been granted by the authorization backend
87  AuthRequiredStatus, ///< The user could obtain the authorization after authentication
88  UserCancelledStatus, ///< The user pressed Cancel the authentication dialog. Currently used only on the mac
89  };
90  Q_ENUM(AuthStatus)
91 
92  enum ExecutionMode {
93  ExecuteMode,
94  AuthorizeOnlyMode,
95  };
96  Q_ENUM(ExecutionMode)
97 
98  /**
99  * The backend specific details.
100  */
101  enum class AuthDetail {
102  DetailOther = 0,
103  DetailMessage, ///< The message to show in authentication dialog.
104  };
105  Q_ENUM(AuthDetail)
106 
107  /**
108  * Map of details.
109  */
111 
112  /**
113  * @brief Default constructor
114  *
115  * This constructor sets the name to the empty string.
116  * Such an action is invalid and cannot be authorized nor executed, so
117  * you need to call setName() before you can use the object.
118  */
119  Action();
120 
121  /** Copy constructor */
122  Action(const Action &action);
123 
124  /**
125  * This creates a new action object with this name
126  * @param name The name of the new action
127  */
128  Action(const QString &name);
129 
130 #if KAUTHCORE_ENABLE_DEPRECATED_SINCE(5, 71)
131  /**
132  * This creates a new action object with this name and details
133  * @param name The name of the new action
134  * @param details The details of the action
135  *
136  * @see setDetails
137  * @deprecated since 5.68, use constructor with DetailsMap
138  */
139  KAUTHCORE_DEPRECATED_VERSION_BELATED(5, 71, 5, 68, "Use constructor with DetailsMap")
140  Action(const QString &name, const QString &details);
141 #endif
142 
143  /**
144  * This creates a new action object with this name and details
145  * @param name The name of the new action
146  * @param details The details of the action
147  *
148  * @see setDetails
149  * @since 5.68
150  */
151  Action(const QString &name, const DetailsMap &details);
152 
153  /// Virtual destructor
154  ~Action();
155 
156  /// Assignment operator
157  Action &operator=(const Action &action);
158 
159  /**
160  * @brief Comparison operator
161  *
162  * This comparison operator compares the <b>names</b> of two
163  * actions and returns whether they are the same. It does not
164  * care about the arguments stored in the actions. However,
165  * if two actions are invalid they'll match as equal, even
166  * if the invalid names are different.
167  *
168  * @returns true if the two actions are the same or both invalid
169  */
170  bool operator==(const Action &action) const;
171 
172  /**
173  * @brief Negated comparison operator
174  *
175  * Returns the negation of operator==
176  *
177  * @returns true if the two actions are different and not both invalid
178  */
179  bool operator!=(const Action &action) const;
180 
181  /**
182  * @brief Gets the action's name.
183  *
184  * This is the unique attribute that identifies
185  * an action object. Two action objects with the same
186  * name always refer to the same action.
187  *
188  * @return The action name
189  */
190  QString name() const;
191 
192  /**
193  * @brief Sets the action's name.
194  *
195  * It's not common to change the action name
196  * after its creation. Usually you set the name
197  * with the constructor (and you have to, because
198  * there's no default constructor)
199  */
200  void setName(const QString &name);
201 
202  /**
203  * @brief Gets the action's timeout.
204  *
205  * The timeout of the action in milliseconds
206  * -1 means the default D-Bus timeout (usually 25 seconds)
207  *
208  * @since 5.29
209  *
210  * @return The action timeouts
211  */
212  int timeout() const;
213 
214  /**
215  * @brief Sets the action's timeout.
216  *
217  * The timeout of the action in milliseconds
218  * -1 means the default D-Bus timeout (usually 25 seconds)
219  *
220  * @since 5.29
221  *
222  */
223  void setTimeout(int timeout);
224 
225 #if __has_include(<chrono>)
226  /**
227  * Convenience overload suporting C++ chrono types. May also be used with chrono literals.
228  * @since 5.93
229  */
230  void setTimeout(std::chrono::milliseconds msec)
231  {
232  setTimeout(int(msec.count()));
233  }
234 #endif
235 
236 #if KAUTHCORE_ENABLE_DEPRECATED_SINCE(5, 71)
237  /**
238  * @brief Sets the action's details
239  *
240  * You can use this function to provide the user more details
241  * (if the backend supports it) on the action being authorized in
242  * the authorization dialog
243  *
244  * @deprecated since 5.68, use setDetailsV2() with DetailsMap.
245  */
246  KAUTHCORE_DEPRECATED_VERSION_BELATED(5, 71, 5, 68, "Use setDetailsV2() with DetailsMap")
247  void setDetails(const QString &details);
248 #endif
249 
250  /**
251  * @brief Sets the action's details
252  *
253  * You can use this function to provide the user more details
254  * (if the backend supports it) on the action being authorized in
255  * the authorization dialog
256  *
257  * @param details the details describing the action. For e.g, "DetailMessage" key can
258  * be used to give a customized authentication message.
259  *
260  * @since 5.68
261  */
262  void setDetailsV2(const DetailsMap &details);
263 
264 #if KAUTHCORE_ENABLE_DEPRECATED_SINCE(5, 71)
265  /**
266  * @brief Gets the action's details
267  *
268  * The details that will be shown in the authorization dialog, if the
269  * backend supports it.
270  *
271  * @return The action's details
272  * @deprecated since 5.68, use detailsV2() with DetailsMap.
273  */
274  KAUTHCORE_DEPRECATED_VERSION_BELATED(5, 71, 5, 68, "Use detailsV2() with DetailsMap")
275  QString details() const;
276 #endif
277 
278  /**
279  * @brief Gets the action's details
280  *
281  * The details that will be shown in the authorization dialog, if the
282  * backend supports it.
283  *
284  * @return The action's details
285  * @since 5.68
286  */
287  DetailsMap detailsV2() const;
288 
289  /**
290  * @brief Returns if the object represents a valid action
291  *
292  * Action names have to respect a simple syntax.
293  * They have to be all in lowercase characters, separated
294  * by dots. Dots can't appear at the beginning and at the end of
295  * the name.
296  *
297  * In other words, the action name has to match this perl-like
298  * regular expression:
299  * @code
300  * /^[a-z]+(\.[a-z]+)*$/
301  * @endcode
302  *
303  * This method returns @c false if the action name doesn't match the
304  * valid syntax.
305  *
306  * If the backend supports it, this method also checks if the action is
307  * valid and recognized by the backend itself.
308  * @note This may spawn a nested event loop.
309  *
310  * Invalid actions cannot be authorized nor executed.
311  * The empty string is not a valid action name, so the default
312  * constructor returns an invalid action.
313  */
314  bool isValid() const;
315 
316  /**
317  * @brief Gets the default helper ID used for actions execution
318  *
319  * The helper ID is the string that uniquely identifies the helper in
320  * the system. It is the string passed to the KAUTH_HELPER_MAIN() macro
321  * in the helper source. Because one could have different helpers,
322  * you need to specify an helper ID for each execution, or set a default
323  * ID by calling setHelperId(). This method returns the current default
324  * value.
325  *
326  * @return The default helper ID.
327  */
328  QString helperId() const;
329 
330  /**
331  * @brief Sets the default helper ID used for actions execution
332  *
333  * This method sets the helper ID which contains the body of this action.
334  * If the string is non-empty, the corresponding helper will be fired and
335  * the action executed inside the helper. Otherwise, the action will be just
336  * authorized.
337  *
338  * @note To unset a previously set helper, just pass an empty string
339  *
340  * @param id The default helper ID.
341  *
342  * @see hasHelper
343  * @see helperId
344  */
345  void setHelperId(const QString &id);
346 
347  /**
348  * @brief Checks if the action has an helper
349  *
350  * This function can be used to check if an helper will be called upon the
351  * execution of an action. Such an helper can be set through setHelperId(). If
352  * this function returns false, upon execution the action will be just authorized.
353  *
354  * @since 4.5
355  *
356  * @return Whether the action has an helper or not
357  *
358  * @see setHelperId
359  */
360  bool hasHelper() const;
361 
362  /**
363  * @brief Sets the map object used to pass arguments to the helper.
364  *
365  * This method sets the variant map that the application
366  * can use to pass arbitrary data to the helper when executing the action.
367  *
368  * Only non-gui variants are supported.
369  *
370  * @param arguments The new arguments map
371  */
372  void setArguments(const QVariantMap &arguments);
373 
374  /**
375  * @brief Returns map object used to pass arguments to the helper.
376  *
377  * This method returns the variant map that the application
378  * can use to pass arbitrary data to the helper when executing the action.
379  *
380  * @return The arguments map that will be passed to the helper.
381  */
382  QVariantMap arguments() const;
383 
384  /**
385  * @brief Convenience method to add an argument.
386  *
387  * This method adds the pair @c key/value to the QVariantMap used to
388  * send custom data to the helper.
389  *
390  * Use this method if you don't want to create a new QVariantMap only to
391  * add a new entry.
392  *
393  * @param key The new entry's key
394  * @param value The value of the new entry
395  */
396  void addArgument(const QString &key, const QVariant &value);
397 
398  /**
399  * @brief Gets information about the authorization status of an action
400  *
401  * This methods query the authorization backend to know if the user can try
402  * to acquire the authorization for this action. If the result is Action::AuthRequired,
403  * the user can try to acquire the authorization by authenticating.
404  *
405  * It should not be needed to call this method directly, because the execution methods
406  * already take care of all the authorization stuff.
407  *
408  * @return @c Action::Denied if the user doesn't have the authorization to execute the action,
409  * @c Action::Authorized if the action can be executed,
410  * @c Action::AuthRequired if the user could acquire the authorization after authentication,
411  * @c Action::UserCancelled if the user cancels the authentication dialog. Not currently supported by the Polkit backend
412  */
413  AuthStatus status() const;
414 
415  /**
416  * @brief Get the job object used to execute the action
417  *
418  * @return The KAuth::ExecuteJob object to be used to run the action.
419  */
420  ExecuteJob *execute(ExecutionMode mode = ExecuteMode);
421 
422  /**
423  * @brief Sets a parent widget for the authentication dialog
424  *
425  * This function is used for explicitly setting a parent window for an eventual authentication dialog required when
426  * authorization is triggered. Some backends, in fact, (like polkit-1) need to have a parent explicitly set for displaying
427  * the dialog correctly.
428  *
429  * @note If you are using KAuth through one of KDE's GUI components (KPushButton, KCModule...) you do not need and should not
430  * call this function, as it is already done by the component itself.
431  *
432  * @since 4.6
433  *
434  * @param parent A QWidget which will be used as the dialog's parent
435  */
436  void setParentWidget(QWidget *parent);
437 
438  /**
439  * @brief Returns the parent widget for the authentication dialog for this action
440  *
441  * @since 4.6
442  *
443  * @returns A QWidget which will is being used as the dialog's parent
444  */
445  QWidget *parentWidget() const;
446 
447 private:
449 };
450 
451 } // namespace Auth
452 
453 #endif
@ AuthorizedStatus
The authorization has been granted by the authorization backend.
Definition: action.h:86
Job for executing an Action.
Definition: executejob.h:39
AuthStatus
The three values set by authorization methods.
Definition: action.h:82
Q_SCRIPTABLE CaptureState status()
Definition: action.cpp:18
@ InvalidStatus
An invalid action cannot be authorized.
Definition: action.h:85
@ UserCancelledStatus
The user pressed Cancel the authentication dialog. Currently used only on the mac.
Definition: action.h:88
Class to access, authorize and execute actions.
Definition: action.h:75
@ DeniedStatus
The authorization has been denied by the authorization backend.
Definition: action.h:83
AuthDetail
The backend specific details.
Definition: action.h:101
@ ErrorStatus
An error occurred.
Definition: action.h:84
@ AuthRequiredStatus
The user could obtain the authorization after authentication.
Definition: action.h:87
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Feb 5 2023 04:14:58 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.