PolkitAgentListener

PolkitAgentListener — Abstract base class for Authentication Agents

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── PolkitAgentListener
        ╰── PolkitAgentTextListener

Description

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().

Functions

polkit_agent_listener_initiate_authentication ()

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 thread-default main loop of the thread that this method is called from.

Parameters

listener

A PolkitAgentListener.

 

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 NULL.

 

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 callback .

 

polkit_agent_listener_initiate_authentication_finish ()

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.

Parameters

listener

A PolkitAgentListener.

 

res

A GAsyncResult obtained from the GAsyncReadyCallback function passed to polkit_agent_listener_initiate_authentication().

 

error

Return location for error.

 

Returns

TRUE if error is set.


polkit_agent_listener_register ()

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.

Parameters

listener

A PolkitAgentListener.

 

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 NULL for the default object path.

 

cancellable

A GCancellable or NULL.

 

error

Return location for error.

 

Returns

NULL if error is set, otherwise a registration handle that can be used with polkit_agent_listener_unregister().

[transfer full]


polkit_agent_listener_register_with_options ()

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.

Parameters

listener

A PolkitAgentListener.

 

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 NULL for the default object path.

 

options

A GVariant with options or NULL.

[allow-none]

cancellable

A GCancellable or NULL.

 

error

Return location for error.

 

Returns

NULL if error is set, otherwise a registration handle that can be used with polkit_agent_listener_unregister().

[transfer full]


polkit_agent_listener_unregister ()

void
polkit_agent_listener_unregister (gpointer registration_handle);

Unregisters listener .

Parameters

registration_handle

A handle obtained from polkit_agent_listener_register().

 

polkit_agent_register_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)

Parameters

listener

A PolkitAgentListener.

 

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 NULL for the default object path.

 

error

Return location for error.

 

Types and Values

PolkitAgentListener

typedef struct _PolkitAgentListener PolkitAgentListener;

The PolkitAgentListener struct should not be accessed directly.


struct PolkitAgentListenerClass

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.

Members

initiate_authentication ()

Handle an authentication request, see polkit_agent_listener_initiate_authentication().

 

initiate_authentication_finish ()

Finishes handling an authentication request, see polkit_agent_listener_initiate_authentication_finish().

 

enum PolkitAgentRegisterFlags

Flags used in polkit_agent_listener_register().

Members

POLKIT_AGENT_REGISTER_FLAGS_NONE

No flags are set.

 

POLKIT_AGENT_REGISTER_FLAGS_RUN_IN_THREAD

Run the listener in a dedicated thread.