File indexing completed on 2024-07-21 03:41:07

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2009 Michael Leupold <lemma@confuego.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0006 */
0007 
0008 #ifndef KPASSWDSERVERCLIENT_H
0009 #define KPASSWDSERVERCLIENT_H
0010 
0011 #include <kiocore_export.h>
0012 #include <qglobal.h>
0013 
0014 #include <memory>
0015 
0016 class QString;
0017 class OrgKdeKPasswdServerInterface;
0018 
0019 namespace KIO
0020 {
0021 class AuthInfo;
0022 }
0023 
0024 class KPasswdServerClientPrivate;
0025 
0026 /**
0027  * @class KPasswdServerClient kpasswdserverclient.h <KPasswdServerClient>
0028  *
0029  * Interface class for kpasswdserver.
0030  * KIO workers should not use this directly but via the WorkerBase API.
0031  * @since 5.30
0032  */
0033 class KIOCORE_EXPORT KPasswdServerClient
0034 {
0035 public:
0036     /**
0037      * Creates a client instance for kpasswdserver.
0038      * The instance should be kept for the lifetime of the process, not created for each request.
0039      */
0040     KPasswdServerClient();
0041     /**
0042      * Destructor.
0043      */
0044     ~KPasswdServerClient();
0045 
0046     KPasswdServerClient(const KPasswdServerClient &) = delete;
0047     KPasswdServerClient &operator=(const KPasswdServerClient &) = delete;
0048 
0049     /**
0050      * Check if kpasswdserver has cached authentication information regarding
0051      * an AuthInfo object.
0052      * @param info information to check cache for
0053      * @param windowId used as parent for dialogs, comes from QWidget::winId() on the toplevel widget
0054      * @param usertime the X11 user time from the calling application, so that any dialog
0055      *                 (e.g. wallet password) respects focus-prevention rules.
0056      *                 Use KUserTimestamp::userTimestamp in the GUI application from which the request originates.
0057      * @return true if kpasswdserver provided cached information, false if not
0058      * @remarks info will contain the results of the check. To see if
0059      *          information was retrieved, check info.isModified().
0060      */
0061     bool checkAuthInfo(KIO::AuthInfo *info, qlonglong windowId, qlonglong usertime);
0062 
0063     /**
0064      * Let kpasswdserver ask the user for authentication information.
0065      * @param info information to query the user for
0066      * @param errorMsg error message that will be displayed to the user
0067      * @param windowId used as parent for dialogs, comes from QWidget::winId() on the toplevel widget
0068      * @param usertime the X11 user time from the calling application, so that the dialog
0069      *                 (e.g. wallet password) respects focus-prevention rules.
0070      *                 Use KUserTimestamp::userTimestamp in the GUI application from which the request originates.
0071      * @return a KIO error code: KJob::NoError (0) on success, otherwise ERR_USER_CANCELED if the user canceled,
0072      *  or ERR_PASSWD_SERVER if we couldn't communicate with kpasswdserver.
0073      * @remarks If NoError is returned, then @p info will contain the authentication information that was retrieved.
0074      */
0075     int queryAuthInfo(KIO::AuthInfo *info, const QString &errorMsg, qlonglong windowId, qlonglong usertime);
0076 
0077     /**
0078      * Manually add authentication information to kpasswdserver's cache.
0079      * @param info information to add
0080      * @param windowId used as parent window for dialogs, comes from QWidget::winId() on the toplevel widget
0081      */
0082     void addAuthInfo(const KIO::AuthInfo &info, qlonglong windowId);
0083 
0084     /**
0085      * Manually remove authentication information from kpasswdserver's cache.
0086      * @param host hostname of the information to remove
0087      * @param protocol protocol to remove information for
0088      * @param user username to remove information for
0089      */
0090     void removeAuthInfo(const QString &host, const QString &protocol, const QString &user);
0091 
0092 private:
0093     OrgKdeKPasswdServerInterface *m_interface;
0094     std::unique_ptr<KPasswdServerClientPrivate> d;
0095 };
0096 
0097 #endif