## ESourceAuthenticator

ESourceAuthenticator — Interface for authentication attempts

## Functions

void | e_source_authenticator_get_prompt_strings ()
gboolean | e_source_authenticator_get_without_password ()
ESourceAuthenticationResult | e_source_authenticator_try_password_sync ()
void | e_source_authenticator_try_password ()
ESourceAuthenticationResult | e_source_authenticator_try_password_finish ()

## Types and Values

struct | ESourceAuthenticatorInterface

## Includes

    #include <libedataserver/libedataserver.h>

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

## Functions

### 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()`.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Returns

the authentication result

Since 3.6

## Types and Values

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