Top | ![]() |
![]() |
![]() |
![]() |
void | polkit_agent_listener_initiate_authentication () |
gboolean | polkit_agent_listener_initiate_authentication_finish () |
gpointer | polkit_agent_listener_register () |
gpointer | polkit_agent_listener_register_with_options () |
void | polkit_agent_listener_unregister () |
gboolean | polkit_agent_register_listener () |
PolkitAgentListener is an abstract base class used for implementing authentication
agents. To implement an authentication agent, simply subclass PolkitAgentListener and
implement the initiate_authentication
and initiate_authentication_finish
methods.
Typically authentication agents use PolkitAgentSession to authenticate users (via passwords) and communicate back the authentication result to the PolicyKit daemon. This is however not requirement. Depending on the system an authentication agent may use other means (such as a Yes/No dialog) to obtain sufficient evidence that the user is one of the requested identities.
To register a PolkitAgentListener with the PolicyKit daemon, use
polkit_agent_listener_register()
or
polkit_agent_listener_register_with_options()
.
void polkit_agent_listener_initiate_authentication (PolkitAgentListener *listener
,const gchar *action_id
,const gchar *message
,const gchar *icon_name
,PolkitDetails *details
,const gchar *cookie
,GList *identities
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Called on a registered authentication agent (see
polkit_agent_listener_register()
) when the user owning the session
needs to prove he is one of the identities listed in identities
.
When the user is done authenticating (for example by dismissing an
authentication dialog or by successfully entering a password or
otherwise proving the user is one of the identities in
identities
), callback
will be invoked. The caller then calls
polkit_agent_listener_initiate_authentication_finish()
to get the
result.
PolkitAgentListener derived subclasses imlementing this method
MUST not ignore cancellable
; callers of this
function can and will use it. Additionally, callback
must be
invoked in the
listener |
||
action_id |
The action to authenticate for. |
|
message |
The message to present to the user. |
|
icon_name |
A themed icon name representing the action or |
|
details |
Details describing the action. |
|
cookie |
The cookie for the authentication request. |
|
identities |
A list of PolkitIdentity objects that the user can choose to authenticate as. |
[element-type Polkit.Identity] |
cancellable |
A GCancellable. |
|
callback |
Function to call when the user is done authenticating. |
|
user_data |
Data to pass to |
gboolean polkit_agent_listener_initiate_authentication_finish (PolkitAgentListener *listener
,GAsyncResult *res
,GError **error
);
Finishes an authentication request from the PolicyKit daemon, see
polkit_agent_listener_initiate_authentication()
for details.
listener |
||
res |
A GAsyncResult obtained from the GAsyncReadyCallback function passed to |
|
error |
Return location for error. |
gpointer polkit_agent_listener_register (PolkitAgentListener *listener
,PolkitAgentRegisterFlags flags
,PolkitSubject *subject
,const gchar *object_path
,GCancellable *cancellable
,GError **error
);
Registers listener
with the PolicyKit daemon as an authentication
agent for subject
. This is implemented by registering a D-Bus
object at object_path
on the unique name assigned by the system
message bus.
Whenever the PolicyKit daemon needs to authenticate a processes
that is related to subject
, the methods
polkit_agent_listener_initiate_authentication()
and
polkit_agent_listener_initiate_authentication_finish()
will be
invoked on listener
.
Note that registration of an authentication agent can fail; for
example another authentication agent may already be registered for
subject
.
Note that the calling thread is blocked until a reply is received.
listener |
||
flags |
A set of flags from the PolkitAgentRegisterFlags enumeration. |
|
subject |
The subject to become an authentication agent for, typically a PolkitUnixSession object. |
|
object_path |
The D-Bus object path to use for the authentication agent or |
|
cancellable |
A GCancellable or |
|
error |
Return location for error. |
NULL
if error
is set, otherwise a
registration handle that can be used with
polkit_agent_listener_unregister()
.
[transfer full]
gpointer polkit_agent_listener_register_with_options (PolkitAgentListener *listener
,PolkitAgentRegisterFlags flags
,PolkitSubject *subject
,const gchar *object_path
,GVariant *options
,GCancellable *cancellable
,GError **error
);
Like polkit_agent_listener_register()
but takes options to influence registration. See the
RegisterAuthenticationAgentWithOptions()
D-Bus method for details.
listener |
||
flags |
A set of flags from the PolkitAgentRegisterFlags enumeration. |
|
subject |
The subject to become an authentication agent for, typically a PolkitUnixSession object. |
|
object_path |
The D-Bus object path to use for the authentication agent or |
|
options |
A GVariant with options or |
[allow-none] |
cancellable |
A GCancellable or |
|
error |
Return location for error. |
NULL
if error
is set, otherwise a
registration handle that can be used with
polkit_agent_listener_unregister()
.
[transfer full]
void
polkit_agent_listener_unregister (gpointer registration_handle
);
Unregisters listener
.
gboolean polkit_agent_register_listener (PolkitAgentListener *listener
,PolkitSubject *subject
,const gchar *object_path
,GError **error
);
polkit_agent_register_listener
is deprecated and should not be used in newly-written code.
(deprecated)
listener |
||
subject |
The subject to become an authentication agent for, typically a PolkitUnixSession object. |
|
object_path |
The D-Bus object path to use for the authentication agent or |
|
error |
Return location for error. |
typedef struct _PolkitAgentListener PolkitAgentListener;
The PolkitAgentListener struct should not be accessed directly.
struct PolkitAgentListenerClass { GObjectClass parent_class; /* Vtable */ void (*initiate_authentication) (PolkitAgentListener *listener, const gchar *action_id, const gchar *message, const gchar *icon_name, PolkitDetails *details, const gchar *cookie, GList *identities, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (*initiate_authentication_finish) (PolkitAgentListener *listener, GAsyncResult *res, GError **error); };
VFuncs that authentication agents needs to implement.
Handle an authentication request, see |
||
Finishes handling an authentication request, see |