## EAuthenticationMediator

EAuthenticationMediator — Authenticator proxy for remote clients

## Synopsis

    #include <libebackend/libebackend.h>

    struct              EAuthenticationMediator;
    ESourceAuthenticator * e_authentication_mediator_new    (GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             const gchar *sender,
                                                             GError **error);
    GDBusConnection *   e_authentication_mediator_get_connection
                                                            (EAuthenticationMediator *mediator);
    const gchar *       e_authentication_mediator_get_object_path
                                                            (EAuthenticationMediator *mediator);
    const gchar *       e_authentication_mediator_get_sender
                                                            (EAuthenticationMediator *mediator);
    gboolean            e_authentication_mediator_wait_for_client_sync
                                                            (EAuthenticationMediator *mediator,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_authentication_mediator_wait_for_client
                                                            (EAuthenticationMediator *mediator,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_authentication_mediator_wait_for_client_finish
                                                            (EAuthenticationMediator *mediator,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                e_authentication_mediator_dismiss   (EAuthenticationMediator *mediator);
    void                e_authentication_mediator_server_error
                                                            (EAuthenticationMediator *mediator,
                                                             const GError *error);

## Object Hierarchy

      GObject
       +----EAuthenticationMediator

## Implemented Interfaces

EAuthenticationMediator implements GInitable and ESourceAuthenticator.

## Properties

      "connection"               GDBusConnection*      : Read / Write / Construct Only
      "object-path"              gchar*                : Read / Write / Construct Only
      "sender"                   gchar*                : Read / Write / Construct Only

## Description

EAuthenticationMediator runs on the registry D-Bus service. It mediates authentication attempts between the client requesting authentication and the server-side EAuthenticationSession interacting with the user and/or secret service. It implements the ESourceAuthenticator interface and securely transmits passwords to a remote ESourceRegistry over D-Bus.

## Details

### struct EAuthenticationMediator

    struct EAuthenticationMediator;

Contains only private data that should be read and manipulated using the functions below.

Since 3.6

### e_authentication_mediator_new ()

    ESourceAuthenticator * e_authentication_mediator_new    (GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             const gchar *sender,
                                                             GError **error);

Creates a new EAuthenticationMediator and exports the Authenticator D-Bus interface on `connection` at `object_path`. If the Authenticator interface fails to export, the function sets `error` and returns `NULL`.

EAuthenticationMediator watches the bus name of the client requesting authentication, given by `sender`. If it sees the bus name vanish, it cancels the authentication session so the next authentication session can begin without delay.

`connection` : | a GDBusConnection
`object_path` : | object path of the authentication session
`sender` : | bus name of the client requesting authentication
`error` : | return location for a GError, or `NULL`
Returns : | an EAuthenticationMediator, or `NULL` on error

Since 3.6

### e_authentication_mediator_get_connection ()

    GDBusConnection *   e_authentication_mediator_get_connection
                                                            (EAuthenticationMediator *mediator);

Returns the GDBusConnection on which the Authenticator D-Bus interface is exported.

`mediator` : | an EAuthenticationMediator
Returns : | the GDBusConnection

Since 3.6

### e_authentication_mediator_get_object_path ()

    const gchar *       e_authentication_mediator_get_object_path
                                                            (EAuthenticationMediator *mediator);

Returns the object path at which the Authenticator D-Bus interface is exported.

`mediator` : | an EAuthenticationMediator
Returns : | the object path

Since 3.6

### e_authentication_mediator_get_sender ()

    const gchar *       e_authentication_mediator_get_sender
                                                            (EAuthenticationMediator *mediator);

Returns the authentication client's unique bus name.

`mediator` : | an EAuthenticationMediator
Returns : | the client's bus name

Since 3.6

### e_authentication_mediator_wait_for_client_sync ()

    gboolean            e_authentication_mediator_wait_for_client_sync
                                                            (EAuthenticationMediator *mediator,
                                                             GCancellable *cancellable,
                                                             GError **error);

Waits for the authentication client to indicate it is ready to begin authentication attempts. Call this function to synchronize with the client before initiating any authentication attempts through `mediator`.

If the authentication client's bus name vanishes or the client fails to signal it is ready before a timer expires, the function sets `error` and returns `FALSE`.

`mediator` : | an EAuthenticationMediator
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the client is ready, `FALSE` if an error occurred

Since 3.6

### e_authentication_mediator_wait_for_client ()

    void                e_authentication_mediator_wait_for_client
                                                            (EAuthenticationMediator *mediator,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously waits for the authentication client to indicate it is ready to being authentication attempts. Call this function to synchronize with the client before initiating any authentication attempts through `mediator`.

When the operation is finished, `callback` will be called. You can then call `e_authentication_mediator_wait_for_client_finished()` to get the result of the operation.

`mediator` : | an EAuthenticationMediator
`cancellable` : | optional GCancellable object, or `NULL`
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | data to pass to the callback function

Since 3.6

### e_authentication_mediator_wait_for_client_finish ()

    gboolean            e_authentication_mediator_wait_for_client_finish
                                                            (EAuthenticationMediator *mediator,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_authentication_mediator_wait_for_client()`.

If the authentication client's bus name vanishes or the client fails to signal it is ready before a timer expires, the function sets `error` and returns `FALSE`.

`mediator` : | an EAuthenticationMediator
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the client is ready, `FALSE` if an error occurred

Since 3.6

### e_authentication_mediator_dismiss ()

    void                e_authentication_mediator_dismiss   (EAuthenticationMediator *mediator);

Signals to the authentication client that the user declined to provide a password when prompted and that the authentication session has terminated. This is also called when a server-side error has occurred, but the client doesn't need to know the difference.

`mediator` : | an EAuthenticationMediator

Since 3.6

### e_authentication_mediator_server_error ()

    void                e_authentication_mediator_server_error
                                                            (EAuthenticationMediator *mediator,
                                                             const GError *error);

Signals to the authentication client that the authentication session has terminated with a server-side error.

`mediator` : | an EAuthenticationMediator

Since 3.10.3

## Property Details

### The `"connection"` property

      "connection"               GDBusConnection*      : Read / Write / Construct Only

The GDBusConnection on which to export the authenticator interface.

### The `"object-path"` property

      "object-path"              gchar*                : Read / Write / Construct Only

The object path at which to export the authenticator interface.

Default value: NULL

### The `"sender"` property

      "sender"                   gchar*                : Read / Write / Construct Only

Unique bus name of the process that initiated the authentication session.

Default value: NULL