PolkitAgentListener: polkit Reference Manual

PolkitAgentListener

PolkitAgentListener — Abstract base class for Authentication Agents

Stability Level

Unstable, unless otherwise indicated

Functions

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

Types and Values

	PolkitAgentListener
struct	PolkitAgentListenerClass
enum	PolkitAgentRegisterFlags

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.

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

GObjectClass `parent_class`;	The parent class.
`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.