ESourceAuthenticator

ESourceAuthenticator — Interface for authentication attempts

Functions

Types and Values

Object Hierarchy

    GInterface
    ╰── ESourceAuthenticator

Prerequisites

ESourceAuthenticator requires GObject.

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

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

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

Status codes used by the ESourceAuthenticator interface.

Members

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