GNOME.org

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

Generated by GTK-Doc V1.19