/*
    SPDX-FileCopyrightText: 2008 Nicola Gigante <nicola.gigante@gmail.com>
    SPDX-FileCopyrightText: 2020 Harald Sitter <sitter@kde.org>

    SPDX-License-Identifier: LGPL-2.1-or-later
*/

#ifndef KAUTH_HELPER_SUPPORT_H
#define KAUTH_HELPER_SUPPORT_H

#include <QObject>
#include <QVariant>

#include "kauthcore_export.h"

/*!
 * The main macro for writing a helper tool.
 *
 * \a ID The helper ID as passed to the macro
 *
 * \a HelperClass The class name of the responder object for the helper
 *
 */
#define KAUTH_HELPER_MAIN(ID, HelperClass)                                                                                                                     \
    int main(int argc, char **argv)                                                                                                                            \
    {                                                                                                                                                          \
        return KAuth::HelperSupport::helperMain(argc, argv, ID, new HelperClass());                                                                            \
    }

namespace KAuth
{
/*!
 *
 * \namespace KAuth::HelperSupport
 * \inmodule KAuth
 * \inheaderfile KAuth/HelperSupport
 *
 * \brief Support class with some KAUTHCORE_EXPORT methods useful to the helper's code.
 *
 * This class provides the API to write the helper tool that executes your actions.
 * You don't create instances of HelperSupport. Instead, you use its KAUTHCORE_EXPORT methods.
 *
 * This them you can notify the application of progress in your action's execution
 * and you can check if the application asked you to terminate it.
 *
 * \since 4.4
 */
namespace HelperSupport
{
/*!
 * \brief Send a progressStep signal to the caller application
 *
 * You can use this method to notify progress information about the
 * action execution. When you call this method, the KAuth::ExecuteJob
 * object associated with the current action will emit the KJob::percent(KJob*, unsigned long)
 * signal. The meaning of the integer passed here is totally application dependent,
 * but you'll want to use it as a sort of percentage.
 * If you need to be more expressive, use the other overload which takes a QVariantMap
 *
 * \a step The progress indicator
 */
KAUTHCORE_EXPORT void progressStep(int step);

/*!
 * \brief Send a progressStep signal to the caller application
 *
 * You can use this method to notify progress information about the
 * action execution. When you call this method, the KAuth::ExecuteJob
 * object associated with the current action will emit the progressStep(QVariantMap)
 * signal. The meaning of the data passed here is totally application dependent.
 *
 * If you only need a simple percentage value, use the other overload which takes an int.
 *
 * \a data The progress data
 */
KAUTHCORE_EXPORT void progressStep(const QVariantMap &data);

/*!
 * \brief Check if the caller asked the helper to stop the execution
 *
 * This method will return \c true if the helper has been asked to stop the
 * execution of the current action. If this happens, your helper should
 * return (NOT exit). The meaning of the data you return in this case is
 * application-dependent.
 *
 * It's good practice to check it regularly if you have a long-running action
 *
 * Returns \c true if the helper has been asked to stop, \c false otherwise
 *
 * \sa ExecuteJob::kill
 */
KAUTHCORE_EXPORT bool isStopped();

/*!
 * \brief Method that implements the main function of the helper tool. Do not call directly
 *
 * This method is called in the proper way by the code generated by the KAUTH_HELPER_MAIN() macro,
 * which creates a main() function for the helper tool.
 * You shouldn't call this method directly.
 *
 * \a argc The argc parameter from the main() function.
 *
 * \a argv The argv parameter from the main() function.
 *
 * \a id The helper ID as passed to the macro
 *
 * \a responder The responder object for the helper. The macro passes a default-constructed,
 *                  heap-allocated object of the class specified as the last macro parameter
 */
KAUTHCORE_EXPORT int helperMain(int argc, char **argv, const char *id, QObject *responder);

/*!
 * \brief Obtains the caller user id if available.
 *
 * This method offers a way to obtain the unprivileged client's UID if possible.
 * For example when a D-Bus-based backend is used this will resolve the caller
 * of the D-Bus method and obtain its process' UID.
 *
 * \since 5.74
 *
 * Return caller UID or -1 when not available
 */
KAUTHCORE_EXPORT int callerUid();
} // namespace HelperSupport

} // namespace Auth

#endif