File indexing completed on 2024-07-21 09:28:29

0001 /*
0002     SPDX-FileCopyrightText: 2008 Nicola Gigante <nicola.gigante@gmail.com>
0003     SPDX-FileCopyrightText: 2020 Harald Sitter <sitter@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.1-or-later
0006 */
0007 
0008 #ifndef KAUTH_HELPER_SUPPORT_H
0009 #define KAUTH_HELPER_SUPPORT_H
0010 
0011 #include <QObject>
0012 #include <QVariant>
0013 
0014 #include "kauthcore_export.h"
0015 
0016 /**
0017  * @relates KAuth
0018  *
0019  * The main macro for writing a helper tool.
0020  * @param ID The helper ID as passed to the macro
0021  * @param HelperClass The class name of the responder object for the helper
0022  *
0023  * @see @ref kauth_helper
0024  */
0025 #define KAUTH_HELPER_MAIN(ID, HelperClass)                                                                                                                     \
0026     int main(int argc, char **argv)                                                                                                                            \
0027     {                                                                                                                                                          \
0028         return KAuth::HelperSupport::helperMain(argc, argv, ID, new HelperClass());                                                                            \
0029     }
0030 
0031 namespace KAuth
0032 {
0033 /**
0034  * @brief Support class with some KAUTHCORE_EXPORT methods useful to the helper's code
0035  *
0036  * This class provides the API to write the helper tool that executes your actions.
0037  * You don't create instances of HelperSupport. Instead, you use its KAUTHCORE_EXPORT methods.
0038  *
0039  * This them you can notify the application of progress in your action's execution
0040  * and you can check if the application asked you to terminate it.
0041  *
0042  * @since 4.4
0043  */
0044 namespace HelperSupport
0045 {
0046 /**
0047  * @brief Send a progressStep signal to the caller application
0048  *
0049  * You can use this method to notify progress information about the
0050  * action execution. When you call this method, the KAuth::ExecuteJob
0051  * object associated with the current action will emit the KJob::percent(KJob*, unsigned long)
0052  * signal. The meaning of the integer passed here is totally application dependent,
0053  * but you'll want to use it as a sort of percentage.
0054  * If you need to be more expressive, use the other overload which takes a QVariantMap
0055  *
0056  * @param step The progress indicator
0057  */
0058 KAUTHCORE_EXPORT void progressStep(int step);
0059 
0060 /**
0061  * @brief Send a progressStep signal to the caller application
0062  *
0063  * You can use this method to notify progress information about the
0064  * action execution. When you call this method, the KAuth::ExecuteJob
0065  * object associated with the current action will emit the progressStep(QVariantMap)
0066  * signal. The meaning of the data passed here is totally application dependent.
0067  *
0068  * If you only need a simple percentage value, use the other overload which takes an int.
0069  *
0070  * @param data The progress data
0071  */
0072 KAUTHCORE_EXPORT void progressStep(const QVariantMap &data);
0073 
0074 /**
0075  * @brief Check if the caller asked the helper to stop the execution
0076  *
0077  * This method will return @c true if the helper has been asked to stop the
0078  * execution of the current action. If this happens, your helper should
0079  * return (NOT exit). The meaning of the data you return in this case is
0080  * application-dependent.
0081  *
0082  * It's good practice to check it regularly if you have a long-running action
0083  *
0084  * @return @c true if the helper has been asked to stop, @c false otherwise
0085  *
0086  * @see ExecuteJob::kill
0087  */
0088 KAUTHCORE_EXPORT bool isStopped();
0089 
0090 /**
0091  * @brief Method that implements the main function of the helper tool. Do not call directly
0092  *
0093  * This method is called in the proper way by the code generated by the KAUTH_HELPER_MAIN() macro,
0094  * which creates a main() function for the helper tool.
0095  * You shouldn't call this method directly.
0096  *
0097  * @param argc The argc parameter from the main() function.
0098  * @param argv The argv parameter from the main() function.
0099  * @param id The helper ID as passed to the macro
0100  * @param responder The responder object for the helper. The macro passes a default-constructed,
0101  *                  heap-allocated object of the class specified as the last macro parameter
0102  */
0103 KAUTHCORE_EXPORT int helperMain(int argc, char **argv, const char *id, QObject *responder);
0104 
0105 /**
0106  * @brief Obtains the caller user id if available.
0107  *
0108  * This method offers a way to obtain the unprivileged client's UID if possible.
0109  * For example when a D-Bus-based backend is used this will resolve the caller
0110  * of the D-Bus method and obtain its process' UID.
0111  *
0112  * @since 5.74
0113  *
0114  * @return caller UID or -1 when not available
0115  */
0116 KAUTHCORE_EXPORT int callerUid();
0117 } // namespace HelperSupport
0118 
0119 } // namespace Auth
0120 
0121 #endif