1/*
2 SPDX-FileCopyrightText: 2008 Nicola Gigante <nicola.gigante@gmail.com>
3 SPDX-FileCopyrightText: 2020 Harald Sitter <sitter@kde.org>
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 * The main macro for writing a helper tool.
18 *
19 * \a ID The helper ID as passed to the macro
20 *
21 * \a HelperClass The class name of the responder object for the helper
22 *
23 */
24#define KAUTH_HELPER_MAIN(ID, HelperClass) \
25 int main(int argc, char **argv) \
26 { \
27 return KAuth::HelperSupport::helperMain(argc, argv, ID, new HelperClass()); \
28 }
29
30namespace KAuth
31{
32/*!
33 *
34 * \namespace KAuth::HelperSupport
35 * \inmodule KAuth
36 * \inheaderfile KAuth/HelperSupport
37 *
38 * \brief Support class with some KAUTHCORE_EXPORT methods useful to the helper's code.
39 *
40 * This class provides the API to write the helper tool that executes your actions.
41 * You don't create instances of HelperSupport. Instead, you use its KAUTHCORE_EXPORT methods.
42 *
43 * This them you can notify the application of progress in your action's execution
44 * and you can check if the application asked you to terminate it.
45 *
46 * \since 4.4
47 */
48namespace HelperSupport
49{
50/*!
51 * \brief Send a progressStep signal to the caller application
52 *
53 * You can use this method to notify progress information about the
54 * action execution. When you call this method, the KAuth::ExecuteJob
55 * object associated with the current action will emit the KJob::percent(KJob*, unsigned long)
56 * signal. The meaning of the integer passed here is totally application dependent,
57 * but you'll want to use it as a sort of percentage.
58 * If you need to be more expressive, use the other overload which takes a QVariantMap
59 *
60 * \a step The progress indicator
61 */
62KAUTHCORE_EXPORT void progressStep(int step);
63
64/*!
65 * \brief Send a progressStep signal to the caller application
66 *
67 * You can use this method to notify progress information about the
68 * action execution. When you call this method, the KAuth::ExecuteJob
69 * object associated with the current action will emit the progressStep(QVariantMap)
70 * signal. The meaning of the data passed here is totally application dependent.
71 *
72 * If you only need a simple percentage value, use the other overload which takes an int.
73 *
74 * \a data The progress data
75 */
76KAUTHCORE_EXPORT void progressStep(const QVariantMap &data);
77
78/*!
79 * \brief Check if the caller asked the helper to stop the execution
80 *
81 * This method will return \c true if the helper has been asked to stop the
82 * execution of the current action. If this happens, your helper should
83 * return (NOT exit). The meaning of the data you return in this case is
84 * application-dependent.
85 *
86 * It's good practice to check it regularly if you have a long-running action
87 *
88 * Returns \c true if the helper has been asked to stop, \c false otherwise
89 *
90 * \sa ExecuteJob::kill
91 */
92KAUTHCORE_EXPORT bool isStopped();
93
94/*!
95 * \brief Method that implements the main function of the helper tool. Do not call directly
96 *
97 * This method is called in the proper way by the code generated by the KAUTH_HELPER_MAIN() macro,
98 * which creates a main() function for the helper tool.
99 * You shouldn't call this method directly.
100 *
101 * \a argc The argc parameter from the main() function.
102 *
103 * \a argv The argv parameter from the main() function.
104 *
105 * \a id The helper ID as passed to the macro
106 *
107 * \a responder The responder object for the helper. The macro passes a default-constructed,
108 * heap-allocated object of the class specified as the last macro parameter
109 */
110KAUTHCORE_EXPORT int helperMain(int argc, char **argv, const char *id, QObject *responder);
111
112/*!
113 * \brief Obtains the caller user id if available.
114 *
115 * This method offers a way to obtain the unprivileged client's UID if possible.
116 * For example when a D-Bus-based backend is used this will resolve the caller
117 * of the D-Bus method and obtain its process' UID.
118 *
119 * \since 5.74
120 *
121 * Return caller UID or -1 when not available
122 */
123KAUTHCORE_EXPORT int callerUid();
124} // namespace HelperSupport
125
126} // namespace Auth
127
128#endif
129

source code of kauth/src/helpersupport.h