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

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