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