PolkitQt-1

polkitqt1-agent-listener.h
1 /*
2  This file is part of the Polkit-qt project
3  SPDX-FileCopyrightText: 2009 Jaroslav Reznik <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef POLKITQT1_AGENT_LISTENER_H
9 #define POLKITQT1_AGENT_LISTENER_H
10 
11 #include <QObject>
12 #include <QScopedPointer>
13 
14 #include "polkitqt1-agent-session.h"
15 
16 #define POLKIT_AGENT_I_KNOW_API_IS_SUBJECT_TO_CHANGE 1
17 
18 typedef struct _PolkitAgentListener PolkitAgentListener;
19 
20 namespace PolkitQt1
21 {
22 class Subject;
23 class Identity;
24 class Details;
25 }
26 
27 namespace PolkitQt1
28 {
29 
30 namespace Agent
31 {
32 
33 class ListenerPrivate;
34 /**
35  * \class Listener polkitqt1-agent-listener.h Listener
36  * \author Jaroslav Reznik <[email protected]>
37  *
38  * \brief Listener is abstract class used for implementing authentication agents.
39  *
40  * To implement an authentication agent, just subclass this class and implement
41  * virtual functions initiateAuthentication, initiateAuthenticationFinish
42  * and cancelAuthentication.
43  *
44  * You can also use Session class to authenticate users however it isn't required.
45  * \sa Session
46  */
47 class POLKITQT1_AGENT_EXPORT Listener : public QObject
48 {
49  Q_OBJECT
50  Q_DISABLE_COPY(Listener)
51 public:
52  /**
53  * \brief Constructor of Listener class
54  */
55  Listener(QObject *parent = nullptr);
56 
57  /**
58  * \brief Constructor of Listener class from PolkitAgentListener
59  *
60  * \warning Use this only if you are completely aware of what are you doing!
61  *
62  * \param listener Pointer to the PolkitAgentListener
63  * \param parent
64  */
65  explicit Listener(PolkitAgentListener *listener, QObject *parent = nullptr);
66 
67  ~Listener() override;
68 
69  /**
70  * \brief Registers listener with polkit daemon as an authentication agent for \p subject.
71  *
72  * This is implemented by registering a DBus object at \p objectPath on the unique
73  * name assigned by the system message bus.
74  *
75  * Whenever the polkit daemon needs to authenticate a processes that is related to \p subject,
76  * the methods initiateAuthentication and initiateAuthenticationFinish will be evoked.
77  *
78  * \param subject Subject that listener will be registered for
79  * \param objectPath DBus object path
80  * \return \c True if the polkitqt1-agent-listener.has been registered, \c False otherwise
81  */
82  bool registerListener(const PolkitQt1::Subject &subject, const QString &objectPath);
83 
84  /**
85  * \brief Returns pointer to the PolkitAgentListener.
86  *
87  * \warning Use this only if you are completely aware of what are you doing!
88  *
89  * \return PolkitAgentListener
90  */
91  const PolkitAgentListener *listener();
92 
93 public Q_SLOTS:
94  /**
95  * \brief Initiate authentication for the action
96  *
97  * This method will be called on a registered authentication agent when the user owning
98  * the session needs to prove he is one of the identities listed in \p identities.
99  *
100  * \note You have to reimplement this method in the subclass.
101  *
102  * \param actionId The action to authenticate for
103  * \param message The message to present to the user
104  * \param iconName The name of the icon which is representing the action
105  * \param details Details describing the action
106  * \param cookie The cookie for the authentization request
107  * \param identities A list of Identity object that the user can choose to authenticate as
108  * \param result This AsyncResult MUST be completed by using complete() method when the
109  * authentication is done. You can pass it to the constructor of the Session class
110  * and then call session->result()->complete() to mark the action as done.
111  */
112  virtual void initiateAuthentication(const QString &actionId,
113  const QString &message,
114  const QString &iconName,
115  const PolkitQt1::Details &details,
116  const QString &cookie,
117  const PolkitQt1::Identity::List &identities,
118  PolkitQt1::Agent::AsyncResult *result) = 0;
119 
120  /**
121  * TODO: Is this method really required ?
122  * \brief Finishes an authentication request from the polkit daemon.
123  *
124  * \note You have to reimplement this method in the subclass.
125  *
126  * \see initiateAuthentication
127  */
128  virtual bool initiateAuthenticationFinish() = 0;
129 
130  /**
131  * TODO: Is this method really required ?
132  * \brief Cancels an authentication request from the polkit daemon.
133  *
134  * \note You have to reimplement this method in the subclass.
135  *
136  * \see initiateAuthentication
137  */
138  virtual void cancelAuthentication() = 0;
139 
140 private:
142 };
143 }
144 
145 }
146 
147 #endif
This class represents PolicyKit subjects.
Listener is abstract class used for implementing authentication agents.
Subject
Encapsulation of GSimpleAsyncResult to QObject class.
Namespace wrapping Polkit-Qt Agent classes.
Class used for passing details around.
Namespace wrapping Polkit-Qt classes.
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Jun 26 2022 04:06:09 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.