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 * @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
31namespace 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 */
44namespace 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 */
58KAUTHCORE_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 */
72KAUTHCORE_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 */
88KAUTHCORE_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 */
103KAUTHCORE_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 */
116KAUTHCORE_EXPORT int callerUid();
117} // namespace HelperSupport
118
119} // namespace Auth
120
121#endif
122

source code of kauth/src/helpersupport.h