KAuth

helpersupport.h
1 /*
2  SPDX-FileCopyrightText: 2008 Nicola Gigante <[email protected]>
3  SPDX-FileCopyrightText: 2020 Harald Sitter <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.1-or-later
6 */
7 
8 #ifndef KAUTH_HELPER_SUPPORT_H
9 #define KAUTH_HELPER_SUPPORT_H
10 
11 #include <QObject>
12 #include <QVariant>
13 
14 #include "kauthcore_export.h"
15 
16 /**
17  * @relates KAuth
18  *
19  * The main macro for writing a helper tool.
20  * @param ID The helper ID as passed to the macro
21  * @param HelperClass The class name of the responder object for the helper
22  *
23  * @see @ref kauth_helper
24  */
25 #define KAUTH_HELPER_MAIN(ID, HelperClass) \
26  int main(int argc, char **argv) \
27  { \
28  return KAuth::HelperSupport::helperMain(argc, argv, ID, new HelperClass()); \
29  }
30 
31 namespace KAuth
32 {
33 /**
34  * @brief Support class with some KAUTHCORE_EXPORT methods useful to the helper's code
35  *
36  * This class provides the API to write the helper tool that executes your actions.
37  * You don't create instances of HelperSupport. Instead, you use its KAUTHCORE_EXPORT methods.
38  *
39  * This them you can notify the application of progress in your action's execution
40  * and you can check if the application asked you to terminate it.
41  *
42  * @since 4.4
43  */
44 namespace HelperSupport
45 {
46 /**
47  * @brief Send a progressStep signal to the caller application
48  *
49  * You can use this method to notify progress information about the
50  * action execution. When you call this method, the KAuth::ExecuteJob
51  * object associated with the current action will emit the KJob::percent(KJob*, unsigned long)
52  * signal. The meaning of the integer passed here is totally application dependent,
53  * but you'll want to use it as a sort of percentage.
54  * If you need to be more expressive, use the other overload which takes a QVariantMap
55  *
56  * @param step The progress indicator
57  */
58 KAUTHCORE_EXPORT void progressStep(int step);
59 
60 /**
61  * @brief Send a progressStep signal to the caller application
62  *
63  * You can use this method to notify progress information about the
64  * action execution. When you call this method, the KAuth::ExecuteJob
65  * object associated with the current action will emit the progressStep(QVariantMap)
66  * signal. The meaning of the data passed here is totally application dependent.
67  *
68  * If you only need a simple percentage value, use the other overload which takes an int.
69  *
70  * @param data The progress data
71  */
72 KAUTHCORE_EXPORT void progressStep(const QVariantMap &data);
73 
74 /**
75  * @brief Check if the caller asked the helper to stop the execution
76  *
77  * This method will return @c true if the helper has been asked to stop the
78  * execution of the current action. If this happens, your helper should
79  * return (NOT exit). The meaning of the data you return in this case is
80  * application-dependent.
81  *
82  * It's good practice to check it regularly if you have a long-running action
83  *
84  * @return @c true if the helper has been asked to stop, @c false otherwise
85  *
86  * @see ExecuteJob::kill
87  */
88 KAUTHCORE_EXPORT bool isStopped();
89 
90 /**
91  * @brief Method that implements the main function of the helper tool. Do not call directly
92  *
93  * This method is called in the proper way by the code generated by the KAUTH_HELPER_MAIN() macro,
94  * which creates a main() function for the helper tool.
95  * You shouldn't call this method directly.
96  *
97  * @param argc The argc parameter from the main() function.
98  * @param argv The argv parameter from the main() function.
99  * @param id The helper ID as passed to the macro
100  * @param responder The responder object for the helper. The macro passes a default-constructed,
101  * heap-allocated object of the class specified as the last macro parameter
102  */
103 KAUTHCORE_EXPORT int helperMain(int argc, char **argv, const char *id, QObject *responder);
104 
105 /**
106  * @brief Obtains the caller user id if available.
107  *
108  * This method offers a way to obtain the unprivileged client's UID if possible.
109  * For example when a D-Bus-based backend is used this will resolve the caller
110  * of the D-Bus method and obtain its process' UID.
111  *
112  * @since 5.74
113  *
114  * @return caller UID or -1 when not available
115  */
116 KAUTHCORE_EXPORT int callerUid();
117 } // namespace HelperSupport
118 
119 } // namespace Auth
120 
121 #endif
Definition: action.cpp:18
KAUTHCORE_EXPORT void progressStep(int step)
Send a progressStep signal to the caller application.
KAUTHCORE_EXPORT int callerUid()
Obtains the caller user id if available.
KAUTHCORE_EXPORT bool isStopped()
Check if the caller asked the helper to stop the execution.
KAUTHCORE_EXPORT int helperMain(int argc, char **argv, const char *id, QObject *responder)
Method that implements the main function of the helper tool.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:14:27 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.