PolkitQt-1

polkitqt1-authority.h
1/*
2 This file is part of the Polkit-qt project
3 SPDX-FileCopyrightText: 2009 Daniel Nicoletti <dantti85-pk@yahoo.com.br>
4 SPDX-FileCopyrightText: 2009 Dario Freddi <drf@kde.org>
5 SPDX-FileCopyrightText: 2009 Jaroslav Reznik <jreznik@redhat.com>
6 SPDX-FileCopyrightText: 2009 Radek Novacek <rnovacek@redhat.com>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef POLKITQT1_AUTHORITY_H
12#define POLKITQT1_AUTHORITY_H
13
14#include "polkitqt1-core-export.h"
15#include "polkitqt1-identity.h"
16#include "polkitqt1-subject.h"
17#include "polkitqt1-temporaryauthorization.h"
18#include "polkitqt1-actiondescription.h"
19
20#include <QObject>
21#include <QMetaType>
22#include <QStringList>
23
24typedef struct _PolkitAuthority PolkitAuthority;
25
26/**
27 * \namespace PolkitQt1 PolkitQt
28 *
29 * \brief Namespace wrapping Polkit-Qt classes
30 *
31 * This namespace wraps all Polkit-Qt classes.
32 */
33namespace PolkitQt1
34{
35
36typedef QMap<QString, QString> DetailsMap;
37
38/**
39 * \class Authority polkitqt1-authority.h Authority
40 * \author Daniel Nicoletti <dantti85-pk@yahoo.com.br>
41 * \author Dario Freddi <drf@kde.org>
42 * \author Jaroslav Reznik <jreznik@redhat.com>
43 *
44 * \brief Convenience class for Qt/KDE applications
45 *
46 * This class is a singleton that provides makes easy the usage
47 * of PolKitAuthority. It emits configChanged()
48 * whenever PolicyKit files change (e.g. the PolicyKit.conf
49 * or .policy files) or when ConsoleKit reports activities changes.
50 *
51 * \note This class is a singleton, its constructor is private.
52 * Call Authority::instance() to get an instance of the Authority object.
53 * Do not delete Authority::instance(), cleanup will be done automatically.
54 */
55class POLKITQT1_CORE_EXPORT Authority : public QObject
56{
57 Q_OBJECT
58 Q_DISABLE_COPY(Authority)
59public:
60 enum Result {
61 /** Result unknown */
62 Unknown = 0x00,
63 /** The subject is authorized for the specified action */
64 Yes = 0x01,
65 /** The subject is not authorized for the specified action */
66 No = 0x02,
67 /** The subject is authorized if more information is provided */
68 Challenge = 0x03
69 };
70 Q_ENUM(Result)
71
73 /** No flags set **/
74 None = 0x00,
75 /** If the subject can obtain the authorization through authentication,
76 * and an authentication agent is available, then attempt to do so.
77 *
78 * Note, this means that the method used for checking authorization is likely
79 * to block for a long time. **/
80 AllowUserInteraction = 0x01
81 };
82 Q_DECLARE_FLAGS(AuthorizationFlags, AuthorizationFlag)
83
84 /** Error codes for the authority class */
85 enum ErrorCode {
86 /** No error occurred **/
87 E_None = 0x00,
88 /** Authority cannot be obtained **/
89 E_GetAuthority = 0x01,
90 /** Authority check failed **/
91 E_CheckFailed = 0x02,
92 /** Wrong or empty subject was given **/
93 E_WrongSubject = 0x03,
94 /** Action returned unknown result **/
95 E_UnknownResult = 0x04,
96 /** Enumerating actions failed **/
97 E_EnumFailed = 0x05,
98 /** Registration of authentication agent failed **/
99 E_RegisterFailed = 0x06,
100 /** Unregistration of authentication agent failed **/
101 E_UnregisterFailed = 0x07,
102 /** Cookie or polkitqt1-identity.handled to the action is empty **/
103 E_CookieOrIdentityEmpty = 0x08,
104 /** Response of auth agent failed **/
105 E_AgentResponseFailed = 0x09,
106 /** Revoke temporary authorizations failed **/
107 E_RevokeFailed = 0x0A
108 };
109 Q_ENUM(ErrorCode)
110
111 /**
112 * \brief Returns the instance of Authority
113 *
114 * Returns the current instance of Authority. Call this function whenever
115 * you need to access the Authority class.
116 *
117 * \note Authority is a singleton. Memory is handled by polkit-qt, so you just
118 * need to call this function to get a working instance of Authority.
119 * Don't delete the object after having used it.
120 *
121 * \param authority use this if you want to set an explicit PolkitAuthority. If you
122 * don't know what this implies, simply ignore the parameter. In case
123 * you want to use it, be sure of streaming it the first time you call
124 * this function, otherwise it will have no effect.
125 *
126 * \return The current authority instance
127 */
128 static Authority *instance(PolkitAuthority *authority = nullptr);
129
130 ~Authority() override;
131
132 /**
133 * You should always call this method after every action. No action will be allowed
134 * if the object is in error state. Use clearError() to clear the error message.
135 *
136 * \see lastError
137 * \see clearError
138 *
139 * \return \c true if an error occurred, \c false if the library is ready
140 */
141 bool hasError() const;
142
143 /**
144 * \return the code of last error
145 */
146 ErrorCode lastError() const;
147
148 /**
149 * Get detail information about error that occurred.
150 *
151 * \return detail message
152 */
153 const QString errorDetails() const;
154
155 /**
156 * Use this method to clear the error message.
157 */
158 void clearError();
159
160 /**
161 * Returns the current instance of PolkitAuthority. If you are handling
162 * it through Polkit-qt (which is quite likely, since you are calling
163 * this function), DO NOT use any PolicyKit API's specific method that
164 * modifies the instance on it, unless you're completely aware of what you're doing and
165 * of the possible consequencies. Use this instance only to gather information.
166 *
167 * \return the current PolkitAuthority instance
168 */
169 PolkitAuthority *polkitAuthority() const;
170
171 /**
172 * This function should be used by mechanisms (e.g.: helper applications).
173 * It returns the action should be carried out, so if the caller was
174 * actually authorized to perform it. The result is in form of a Result, so that
175 * you can have more control over the whole process, and detect an eventual error.
176 * Most of the times you simply want to check if the result is == to \c Result::Yes,
177 * if you don't have specific needs.
178 *
179 * It is CRITICAL that you call this function
180 * and check what it returns before doing anything in your helper, since otherwise
181 * you could be actually performing an action from an unknown or unauthorized caller.
182 *
183 * When operation is finished, signal checkAuthorizationFinish is emitted
184 * with result of authorization check in its parameter.
185 *
186 * \see checkAuthorizationSync Synchronous version of this method.
187 * \see checkAuthorizationFinished Signal that is emitted when this method finishes.
188 * \see checkAuthorizationCancel Use it to cancel execution of this method.
189 *
190 * \param actionId the Id of the action in question
191 * \param subject subject that the action is authorized for (e.g. unix process)
192 * \param flags flags that influences the authorization checking
193 */
194 void checkAuthorization(const QString &actionId, const Subject &subject,
195 AuthorizationFlags flags);
196
197 /**
198 * This function does the same as checkAuthorization(const QString&, const
199 * Subject&, AuthorizationFlags), but also accepts a
200 * DetailsMap parameter. This map can contain key/value pairs that, for
201 * example, are used to expand placeholders in polkit authentication
202 * messages that are formatted like "Authentication required to access
203 * $(device)". For this example, when a key "device" exists in the map,
204 * the "$(device)" will be replaced by the corresponding value in the map.
205 *
206 * \see checkAuthorization(const QString&, const Subject&, AuthorizationFlags) Base version of this method.
207 */
208 // TODO: merge with checkAuthorization when we decide to break binary compatibility probably in Plasma 6
209 void checkAuthorizationWithDetails(
210 const QString &actionId, const Subject &subject,
211 AuthorizationFlags flags, const DetailsMap &details);
212
213 /**
214 * Synchronous version of the checkAuthorization method.
215 *
216 * \param actionId the Id of the action in question
217 * \param subject subject that the action is authorized for (e.g. unix process)
218 * \param flags flags that influences the authorization checking
219 *
220 * \see checkAuthorization Asynchronous version of this method.
221 */
222 Result checkAuthorizationSync(const QString &actionId, const Subject &subject,
223 AuthorizationFlags flags);
224
225 /**
226 * This function does the same as checkAuthorizationSync(const QString&,
227 * const Subject&, AuthorizationFlags), but also accepts a DetailsMap
228 * parameter.
229 *
230 * \see checkAuthorization(const QString&, const Subject&, AuthorizationFlags, const DetailsMap&) for a description of the details parameter.
231 *
232 * \see checkAuthorizationSync(const QString&, const Subject, AuthorizationFlags) Base version of this method.
233 */
234 Result checkAuthorizationSyncWithDetails(const QString &actionId, const Subject &subject,
235 AuthorizationFlags flags, const DetailsMap &details);
236
237 /**
238 * This method can be used to cancel last authorization check.
239 */
240 void checkAuthorizationCancel();
241
242 /**
243 * Asynchronously retrieves all registered actions.
244 *
245 * When operation is finished, signal checkAuthorizationFinish is emitted
246 * with result of authorization check in its parameter.
247 *
248 * \see enumerateActionsSync Synchronous version of this method.
249 * \see enumerateActionsFinished Signal that is emitted when this method finishes.
250 * \see enumerateActionsCancel Use it to cancel execution of this method.
251 */
252 void enumerateActions();
253
254 /**
255 * Synchronously retrieves all registered actions.
256 *
257 * \see enumerateActions Asynchronous version of this method.
258 *
259 * \return a list of Action IDs
260 */
261 ActionDescription::List enumerateActionsSync();
262
263 /**
264 * This method can be used to cancel enumeration of actions
265 */
266 void enumerateActionsCancel();
267
268 /**
269 * Registers an authentication agent.
270 *
271 * \see registerAuthenticationAgentSync Synchronous version of this method.
272 * \see registerAuthenticationAgentFinished Signal that is emitted when this method finishes.
273 * \see registerAuthenticationAgentCancel Use it to cancel execution of this method.
274 *
275 * \param subject caller subject
276 * \param locale the locale of the authentication agent
277 * \param objectPath the object path for the authentication agent
278 */
279 void registerAuthenticationAgent(const Subject &subject, const QString &locale,
280 const QString &objectPath);
281
282 /**
283 * Registers an authentication agent.
284 *
285 * \see registerAuthenticationAgent Asynchronous version of this method.
286 *
287 * \param subject caller subject
288 * \param locale the locale of the authentication agent
289 * \param objectPath the object path for the authentication agent
290 *
291 * \return \c true if the Authentication agent has been successfully registered
292 * \c false if the Authentication agent registration failed
293 */
294 bool registerAuthenticationAgentSync(const Subject &subject, const QString &locale,
295 const QString &objectPath);
296
297 /**
298 * This method can be used to cancel the registration of the authentication agent.
299 */
300 void registerAuthenticationAgentCancel();
301
302 /**
303 * Unregisters an Authentication agent.
304 *
305 * \see unregisterAuthenticationAgentSync Synchronous version of this method.
306 * \see unregisterAuthenticationAgentFinished Signal that is emitted when this method finishes.
307 * \see unregisterAuthenticationAgentCancel Use it to cancel execution of this method.
308 *
309 * \param subject caller subject
310 * \param objectPath the object path for the Authentication agent
311 *
312 * \return \c true if the Authentication agent has been successfully unregistered
313 * \c false if the Authentication agent unregistration failed
314 */
315 void unregisterAuthenticationAgent(const Subject &subject, const QString &objectPath);
316
317 /**
318 * Unregisters an Authentication agent.
319 *
320 * \see unregisterAuthenticationAgent Asynchronous version of this method.
321 *
322 * \param subject caller subject
323 * \param objectPath the object path for the Authentication agent
324 *
325 * \return \c true if the Authentication agent has been successfully unregistered
326 * \c false if the Authentication agent unregistration failed
327 */
328 bool unregisterAuthenticationAgentSync(const Subject &subject, const QString &objectPath);
329
330 /**
331 * This method can be used to cancel the unregistration of the authentication agent.
332 */
333 void unregisterAuthenticationAgentCancel();
334
335 /**
336 * Provide response that \p identity successfully authenticated for the authentication request identified by \p cookie.
337 *
338 * \see authenticationAgentResponseSync Synchronous version of this method.
339 * \see authenticationAgentResponseFinished Signal that is emitted when this method finishes.
340 * \see authenticationAgentResponseCancel Use it to cancel execution of this method.
341 *
342 * \param cookie The cookie passed to the authentication agent from the authority.
343 * \param identity The identity that was authenticated.
344 */
345 void authenticationAgentResponse(const QString &cookie, const Identity &identity);
346
347 /**
348 * Provide response that \p identity successfully authenticated for the authentication request identified by \p cookie.
349 *
350 * \see authenticationAgentResponse Asynchronous version of this method.
351 *
352 * \param cookie The cookie passed to the authentication agent from the authority.
353 * \param identity The identity that was authenticated.
354 *
355 * \return \c true if authority acknowledged the call, \c false if error is set.
356 *
357 */
358 bool authenticationAgentResponseSync(const QString& cookie, const PolkitQt1::Identity& identity);
359
360 /**
361 * This method can be used to cancel the authenticationAgentResponseAsync method.
362 */
363 void authenticationAgentResponseCancel();
364
365 /**
366 * Retrieves all temporary action that applies to \p subject.
367 *
368 * \see enumerateTemporaryAuthorizationsSync Synchronous version of this method.
369 * \see enumerateTemporaryAuthorizationsFinished Signal that is emitted when this method finishes.
370 * \see enumerateTemporaryAuthorizationsCancel Use it to cancel execution of this method.
371 *
372 * \param subject the subject to get temporary authorizations for
373 *
374 */
376
377 /**
378 * Retrieves all temporary action that applies to \p subject
379 *
380 * \see enumerateTemporaryAuthorizations Asynchronous version of this method.
381 *
382 * \param subject the subject to get temporary authorizations for
383 *
384 * \note Free all TemporaryAuthorization objects using \p delete operator.
385 *
386 * \return List of all temporary authorizations
387 */
388 TemporaryAuthorization::List enumerateTemporaryAuthorizationsSync(const Subject &subject);
389
390 /**
391 * This method can be used to cancel the enumerateTemporaryAuthorizationsAsync method.
392 */
393 void enumerateTemporaryAuthorizationsCancel();
394
395 /**
396 * Revokes all temporary authorizations that applies to \p subject
397 *
398 * \see revokeTemporaryAuthorizationsSync Synchronous version of this method.
399 * \see revokeTemporaryAuthorizationsFinished Signal that is emitted when this method finishes.
400 * \see revokeTemporaryAuthorizationsCancel Use it to cancel execution of this method.
401
402 * \param subject the subject to revoke temporary authorizations from
403 */
404 void revokeTemporaryAuthorizations(const Subject &subject);
405
406 /**
407 * Revokes all temporary authorizations that applies to \p subject
408 *
409 * \see revokeTemporaryAuthorizations Asynchronous version of this method.
410 *
411 * \param subject the subject to revoke temporary authorizations from
412 *
413 * \return \c true if all temporary authorization were revoked
414 * \c false if the revoking failed
415 */
416 bool revokeTemporaryAuthorizationsSync(const Subject &subject);
417
418 /**
419 * This method can be used to cancel the method revokeTemporaryAuthorizationsAsync.
420 */
421 void revokeTemporaryAuthorizationsCancel();
422
423 /**
424 * Revokes temporary authorization by \p id
425 *
426 * \see revokeTemporaryAuthorizationSync Synchronous version of this method.
427 * \see revokeTemporaryAuthorizationFinished Signal that is emitted when this method finishes.
428 * \see revokeTemporaryAuthorizationCancel Use it to cancel execution of this method.
429 *
430 * \param id the identifier of the temporary authorization
431 */
432 void revokeTemporaryAuthorization(const QString &id);
433
434 /**
435 * Revokes temporary authorization by \p id
436 *
437 * \see revokeTemporaryAuthorization Asynchronous version of this method.
438 *
439 * \param id the identifier of the temporary authorization
440 *
441 * \return \c true if the temporary authorization was revoked
442 * \c false if the revoking failed
443 */
444 bool revokeTemporaryAuthorizationSync(const QString &id);
445
446 /**
447 * This method can be used to cancel the method revokeTemporaryAuthorizationAsync.
448 */
449 void revokeTemporaryAuthorizationCancel();
450
451Q_SIGNALS:
452 /**
453 * This signal will be emitted when a configuration
454 * file gets changed (e.g. /etc/PolicyKit/PolicyKit.conf or
455 * .policy files).
456 * Connect to this signal if you want to track down
457 * actions.
458 */
460
461 /**
462 * This signal is emitted when ConsoleKit configuration
463 * changes. This might happen when a session becomes active
464 * or inactive.
465 *
466 * If you want to track your actions directly you should
467 * connect to this signal, as this might change the return value
468 * PolicyKit will give you.
469 *
470 * \note If you use Action you'll probably prefer to
471 * use the dataChanged() signal to track Action changes.
472 */
474
475 /**
476 * This signal is emitted when asynchronous method checkAuthorization finishes.
477 *
478 * The argument is the result of authorization.
479 */
481
482 /**
483 * This signal is emitted when asynchronous method enumerateActions finishes.
484 *
485 * The argument is the list of all Action IDs.
486 */
488
489 /**
490 * This signal is emitted when asynchronous method registerAuthenticationAgent finishes.
491 *
492 * The argument is \c true if the Authentication agent has been successfully registered
493 * \c false if the Authentication agent registration failed
494 */
496
497 /**
498 * This signal is emitted when asynchronous method unregisterAuthenticationAgent finishes.
499 *
500 * The argument is \c true if the Authentication agent has been successfully unregistered
501 * \c false if the Authentication agent unregistration failed
502 */
504
505 /**
506 * This signal is emitted when asynchronous method authenticationAgentResponse finishes.
507 *
508 * The argument is \c true if authority acknowledged the call, \c false if error is set.
509 */
511
512 /**
513 * This signal is emitted when asynchronous method enumerateTemporaryAuthorizations finishes.
514 *
515 * The argument is list of all temporary authorizations.
516 *
517 * \note Free all TemporaryAuthorization objects using \p delete operator.
518 */
520
521 /**
522 * This signal is emitted when asynchronous method revokeTemporaryAuthorizations finishes.
523 *
524 * The argument is \c true if all temporary authorizations were revoked
525 * \c false if the revoking failed
526 */
528
529 /**
530 * This signal is emitted when asynchronous method revokeTemporaryAuthorization finishes.
531 * \return \c true if the temporary authorization was revoked
532 * \c false if the revoking failed
533 */
535
536private:
537 explicit Authority(PolkitAuthority *context, QObject *parent = nullptr);
538
539 class Private;
540 friend class Private;
541 Private * const d;
542
543 Q_PRIVATE_SLOT(d, void dbusFilter(const QDBusMessage &message))
544};
545
546Q_DECLARE_OPERATORS_FOR_FLAGS(Authority::AuthorizationFlags)
547
548}
549
550#endif
Convenience class for Qt/KDE applications.
void consoleKitDBChanged()
This signal is emitted when ConsoleKit configuration changes.
void registerAuthenticationAgentFinished(bool)
This signal is emitted when asynchronous method registerAuthenticationAgent finishes.
void revokeTemporaryAuthorizationsFinished(bool)
This signal is emitted when asynchronous method revokeTemporaryAuthorizations finishes.
void configChanged()
This signal will be emitted when a configuration file gets changed (e.g.
void enumerateTemporaryAuthorizationsFinished(PolkitQt1::TemporaryAuthorization::List)
This signal is emitted when asynchronous method enumerateTemporaryAuthorizations finishes.
void unregisterAuthenticationAgentFinished(bool)
This signal is emitted when asynchronous method unregisterAuthenticationAgent finishes.
void enumerateActionsFinished(PolkitQt1::ActionDescription::List)
This signal is emitted when asynchronous method enumerateActions finishes.
void revokeTemporaryAuthorizationFinished(bool)
This signal is emitted when asynchronous method revokeTemporaryAuthorization finishes.
void authenticationAgentResponseFinished(bool)
This signal is emitted when asynchronous method authenticationAgentResponse finishes.
void enumerateTemporaryAuthorizations(const Subject &subject)
Retrieves all temporary action that applies to subject.
ErrorCode
Error codes for the authority class.
void checkAuthorizationFinished(PolkitQt1::Authority::Result)
This signal is emitted when asynchronous method checkAuthorization finishes.
Abstract class representing identities.
This class represents PolicyKit subjects.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:16:56 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.