## ESourceAuthenticator

ESourceAuthenticator — Interface for authentication attempts

## Synopsis

    #include <libedataserver/libedataserver.h>

                        ESourceAuthenticator;
    struct              ESourceAuthenticatorInterface;
    enum                ESourceAuthenticationResult;
    void                e_source_authenticator_get_prompt_strings
                                                            (ESourceAuthenticator *auth,
                                                             ESource *source,
                                                             gchar **prompt_title,
                                                             gchar **prompt_message,
                                                             gchar **prompt_description);
    gboolean            e_source_authenticator_get_without_password
                                                            (ESourceAuthenticator *auth);
    ESourceAuthenticationResult e_source_authenticator_try_password_sync
                                                            (ESourceAuthenticator *auth,
                                                             const GString *password,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_source_authenticator_try_password (ESourceAuthenticator *auth,
                                                             const GString *password,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    ESourceAuthenticationResult e_source_authenticator_try_password_finish
                                                            (ESourceAuthenticator *auth,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----ESourceAuthenticator

## Prerequisites

ESourceAuthenticator requires GObject.

## Description

An object implementing the ESourceAuthenticator interface gets passed to `e_source_registry_authenticate()`. The job of an ESourceAuthenticator is to test whether a remote server will accept a given password, and then indicate the result by returning an ESourceAuthenticationResult value.

Typically only EBackend subclasses need to implement this interface, as client applications are not involved in authentication.

Note this interface is designed around "stateful authentication", where one connects to a server, provides credentials for authentication once, and then issues commands in an authenticated state for the remainder of the session.

Backends requiring "stateless authentication" -- where credentials are included with each command -- will typically want to cache the password internally once it's verified as part of implementing this interface.

## Details

### ESourceAuthenticator

    typedef struct _ESourceAuthenticator ESourceAuthenticator;

Since 3.6

### struct ESourceAuthenticatorInterface

    struct ESourceAuthenticatorInterface {
    	GTypeInterface parent_interface;

    	void		(*get_prompt_strings) (ESourceAuthenticator *auth,
    						 ESource *source,
    						 gchar **prompt_title,
    						 gchar **prompt_message,
    						 gchar **prompt_description);

    	gboolean (*get_without_password) (ESourceAuthenticator *auth);

    	/* Synchronous I/O Methods */
    	ESourceAuthenticationResult
    			(*try_password_sync) (ESourceAuthenticator *auth,
    						 const GString *password,
    						 GCancellable *cancellable,
    						 GError **error);

    	/* Asynchronous I/O Methods (all have defaults) */
    	void		(*try_password)		(ESourceAuthenticator *auth,
    						 const GString *password,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	ESourceAuthenticationResult
    			(*try_password_finish) (ESourceAuthenticator *auth,
    						 GAsyncResult *result,
    						 GError **error);
    };

Since 3.6

### enum ESourceAuthenticationResult

    typedef enum {
    	E_SOURCE_AUTHENTICATION_ERROR,
    	E_SOURCE_AUTHENTICATION_ACCEPTED,
    	E_SOURCE_AUTHENTICATION_REJECTED
    } ESourceAuthenticationResult;

Status codes used by the ESourceAuthenticator interface.

`E_SOURCE_AUTHENTICATION_ERROR` | An error occurred while authenticating.
`E_SOURCE_AUTHENTICATION_ACCEPTED` | Server requesting authentication accepted password.
`E_SOURCE_AUTHENTICATION_REJECTED` | Server requesting authentication rejected password.

Since 3.6

### e_source_authenticator_get_prompt_strings ()

    void                e_source_authenticator_get_prompt_strings
                                                            (ESourceAuthenticator *auth,
                                                             ESource *source,
                                                             gchar **prompt_title,
                                                             gchar **prompt_message,
                                                             gchar **prompt_description);

Generates authentication prompt strings for `source`.

For registry service clients, ESourceRegistry calls this function as part of `e_source_registry_authenticate_sync()`. In the registry service itself, EAuthenticationSession calls this function during initialization. This function should rarely need to be called explicitly outside of those two cases.

The ESourceAuthenticatorInterface defines a default behavior for this method which should suffice in most cases. But implementors can still override the method if needed for special circumstances.

Free each of the returned prompt strings with `g_free()`.

`auth` : | an ESourceAuthenticator
`source` : | an ESource
`prompt_title` : | the title of the prompt. [out]
`prompt_message` : | the prompt message for the user. [out]
`prompt_description` : | the detailed description of the prompt. [out]

Since 3.6

### e_source_authenticator_get_without_password ()

    gboolean            e_source_authenticator_get_without_password
                                                            (ESourceAuthenticator *auth);

Returns whether the used authentication method can be used without a password prompt. If so, then user is not asked for the password, only if the authentication fails. The default implementation returns `FALSE`, which means always asks for the password (or read it from a keyring).

`auth` : | an ESourceAuthenticator
Returns : | whether to try to authenticate without asking for the password

Since 3.10

### e_source_authenticator_try_password_sync ()

    ESourceAuthenticationResult e_source_authenticator_try_password_sync
                                                            (ESourceAuthenticator *auth,
                                                             const GString *password,
                                                             GCancellable *cancellable,
                                                             GError **error);

Attempts to authenticate using `password`.

The password is passed in a GString container so its content is not accidentally revealed in a stack trace.

If an error occurs, the function sets `error` and returns E_SOURCE_AUTHENTICATION_ERROR.

`auth` : | an ESourceAuthenticator
`password` : | a user-provided password
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | the authentication result

Since 3.6

### e_source_authenticator_try_password ()

    void                e_source_authenticator_try_password (ESourceAuthenticator *auth,
                                                             const GString *password,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asyncrhonously attempts to authenticate using `password`.

The password is passed in a GString container so its content is not accidentally revealed in a stack trace.

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

`auth` : | an ESourceAuthenticator
`password` : | a user-provided password
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

Since 3.6

### e_source_authenticator_try_password_finish ()

    ESourceAuthenticationResult e_source_authenticator_try_password_finish
                                                            (ESourceAuthenticator *auth,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_source_authenticator_try_password()`.

If an error occurred, the function sets `error` and returns E_SOURCE_AUTHENTICATION_ERROR.

`auth` : | an ESourceAuthenticator
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | the authentication result

Since 3.6