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 | |
30 | namespace 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 | */ |
48 | namespace 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 | */ |
62 | KAUTHCORE_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 | */ |
76 | KAUTHCORE_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 | */ |
92 | KAUTHCORE_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 | */ |
110 | KAUTHCORE_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 | */ |
123 | KAUTHCORE_EXPORT int callerUid(); |
124 | } // namespace HelperSupport |
125 | |
126 | } // namespace Auth |
127 | |
128 | #endif |
129 | |