Evolution-Data-Server Reference Manual: EAuthenticationSession

## EAuthenticationSession EAuthenticationSession — Centralized authentication management |

## Functions

GQuark | e_authentication_session_error_quark ()
struct _ESourceRegistryServer * | e_authentication_session_get_server ()
ESourceAuthenticator * | e_authentication_session_get_authenticator ()
const gchar * | e_authentication_session_get_source_uid ()
const gchar * | e_authentication_session_get_prompt_title ()
gchar * | e_authentication_session_dup_prompt_title ()
void | e_authentication_session_set_prompt_title ()
const gchar * | e_authentication_session_get_prompt_message ()
gchar * | e_authentication_session_dup_prompt_message ()
void | e_authentication_session_set_prompt_message ()
const gchar * | e_authentication_session_get_prompt_description ()
gchar * | e_authentication_session_dup_prompt_description ()
void | e_authentication_session_set_prompt_description ()
EAuthenticationSessionResult | e_authentication_session_execute_sync ()
void | e_authentication_session_execute ()
EAuthenticationSessionResult | e_authentication_session_execute_finish ()
EAuthenticationSession * | e_authentication_session_new ()
gboolean | e_authentication_session_store_password_sync ()
void | e_authentication_session_store_password ()
gboolean | e_authentication_session_store_password_finish ()
gboolean | e_authentication_session_lookup_password_sync ()
void | e_authentication_session_lookup_password ()
gboolean | e_authentication_session_lookup_password_finish ()
gboolean | e_authentication_session_delete_password_sync ()
void | e_authentication_session_delete_password ()
gboolean | e_authentication_session_delete_password_finish ()

## Types and Values

struct | EAuthenticationSession
struct | EAuthenticationSessionClass
#define | E_AUTHENTICATION_SESSION_KEYRING_ERROR

## Includes

    #include <libebackend/libebackend.h>

## Description

EAuthenticationSession provides centralized password management and password prompting for all clients of the registry D-Bus service.

An EAuthenticationSession is created within the registry D-Bus service when the service receives a request to authenticate some data source. Clients can issue requests by calling `e_source_registry_authenticate()`. Requests can also come from any ECollectionBackend running within the service itself.

An EAuthenticationSession requires some object implementing the ESourceAuthenticator interface to verify stored or user-provided passwords. EAuthenticationMediator is used for client-issued authentication requests. Custom collection backends derived from ECollectionBackend usually implement the ESourceAuthenticator interface themselves.

The EAuthenticationSession is then handed to ESourceRegistryServer through `e_source_registry_server_authenticate()` where it waits in line behind other previously added authentication sessions. When its turn comes, the server calls `e_authentication_session_execute()` to begin the interactive authentication session.

## Functions

### e_authentication_session_error_quark ()

    GQuark
    e_authentication_session_error_quark (void);

### e_authentication_session_get_server ()

    struct _ESourceRegistryServer *
    e_authentication_session_get_server (EAuthenticationSession *session);

Returns the ESourceRegistryServer to which `session` belongs.

#### Parameters

session | an EAuthenticationSession |

#### Returns

the ESourceRegistryServer for `session`

Since 3.6

### e_authentication_session_get_authenticator ()

    ESourceAuthenticator *
    e_authentication_session_get_authenticator
                                   (EAuthenticationSession *session);

Returns the ESourceAuthenticator handling authentication attempts for `session` . This is usually an EAuthenticationMediator but can also be a custom collection backend derived from ECollectionBackend.

#### Parameters

session | an EAuthenticationSession |

#### Returns

the ESourceAuthenticator for `session`

Since 3.6

### e_authentication_session_get_source_uid ()

    const gchar *
    e_authentication_session_get_source_uid
                                   (EAuthenticationSession *session);

Returns the “uid” of the authenticating data source. The data source may or may not be known to the “server”.

#### Parameters

session | an EAuthenticationSession |

#### Returns

the UID of the authenticating data source

Since 3.6

### e_authentication_session_get_prompt_title ()

    const gchar *
    e_authentication_session_get_prompt_title
                                   (EAuthenticationSession *session);

Returns the text used for the password prompt title should prompting be necessary. See GcrPrompt for more details about password prompts.

#### Parameters

session | an EAuthenticationSession |

#### Returns

the password prompt title

Since 3.6

### e_authentication_session_dup_prompt_title ()

    gchar *
    e_authentication_session_dup_prompt_title
                                   (EAuthenticationSession *session);

Thread-safe variation of `e_authentication_session_get_prompt_title()`. Use this function when accessing `session` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

session | an EAuthenticationSession |

#### Returns

a newly-allocated copy of “prompt-title”

Since 3.6

### e_authentication_session_set_prompt_title ()

    void
    e_authentication_session_set_prompt_title
                                   (EAuthenticationSession *session,
                                    const gchar *prompt_title);

Sets the text used for the password prompt title should prompting be necessary. See GcrPrompt for more details about password prompts.

#### Parameters

session | an EAuthenticationSession |
prompt_title | the password prompt title, or `NULL` |

Since 3.6

### e_authentication_session_get_prompt_message ()

    const gchar *
    e_authentication_session_get_prompt_message
                                   (EAuthenticationSession *session);

Returns the text used for the password prompt message should prompting be necessary. See GcrPrompt for more details about password prompts.

#### Parameters

session | an EAuthenticationSession |

#### Returns

the password prompt message

Since 3.6

### e_authentication_session_dup_prompt_message ()

    gchar *
    e_authentication_session_dup_prompt_message
                                   (EAuthenticationSession *session);

Thread-safe variation of `e_authentication_session_get_prompt_message()`. Use this function when accessing `session` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

session | an EAuthenticationSession |

#### Returns

a newly-allocated copy of “prompt-message”

Since 3.6

### e_authentication_session_set_prompt_message ()

    void
    e_authentication_session_set_prompt_message
                                   (EAuthenticationSession *session,
                                    const gchar *prompt_message);

Sets the text used for the password prompt message should prompting be necessary. See GcrPrompt for more details about password prompts.

#### Parameters

session | an EAuthenticationSession |
prompt_message | the password prompt message, or `NULL` |

Since 3.6

### e_authentication_session_get_prompt_description ()

    const gchar *
    e_authentication_session_get_prompt_description
                                   (EAuthenticationSession *session);

Returns the text used for the password prompt description should prompting be necessary. See GcrPrompt for more details about password prompts.

#### Parameters

session | an EAuthenticationSession |

#### Returns

the password prompt description

Since 3.6

### e_authentication_session_dup_prompt_description ()

    gchar *
    e_authentication_session_dup_prompt_description
                                   (EAuthenticationSession *session);

Thread-safe variation of `e_authentication_session_get_prompt_description()`. Use this function when accessing `session` from multiple threads.

The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

session | an EAuthenticationSession |

#### Returns

a newly-allocated copy of “prompt-description”

Since 3.6

### e_authentication_session_set_prompt_description ()

    void
    e_authentication_session_set_prompt_description
                                   (EAuthenticationSession *session,
                                    const gchar *prompt_description);

Sets the text used for the password prompt description should prompting be necessary. See GcrPrompt for more details about password prompts.

#### Parameters

session | an EAuthenticationSession |
prompt_description | the password prompt description |

Since 3.6

### e_authentication_session_execute_sync ()

    EAuthenticationSessionResult
    e_authentication_session_execute_sync (EAuthenticationSession *session,
                                           GCancellable *cancellable,
                                           GError **error);

Executes an authentication session.

First the secret service is queried for a stored password. If found, an authentication attempt is made without disturbing the user. If no stored password is found, or if the stored password is rejected, the user is shown a system-modal dialog requesting a password. Further authentication attempts are repeated with user-provided passwords until authentication is verified or the user dismisses the prompt. The returned EAuthenticationSessionResult indicates the outcome.

If an error occurs while interacting with the secret service, or while prompting the user for a password, or while attempting authentication, the function sets `error` and returns E_AUTHENTICATION_SESSION_ERROR.

#### Parameters

session | an EAuthenticationSession |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

the result of the authentication session

Since 3.6

### e_authentication_session_execute ()

    void
    e_authentication_session_execute (EAuthenticationSession *session,
                                      gint io_priority,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

See `e_authentication_session_execute_sync()` for details.

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

#### Parameters

session | an EAuthenticationSession |
io_priority | the I/O priority of the request |
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_session_execute_finish ()

    EAuthenticationSessionResult
    e_authentication_session_execute_finish
                                   (EAuthenticationSession *session,
                                    GAsyncResult *result,
                                    GError **error);

Finishes the operation started with `e_authentication_session_execute()`.

If an error occurs while interacting with the secret service, or while prompting the user for a password, or while attempting authentication, the function sets `error` and returns E_AUTHENTICATION_SESSION_ERROR.

#### Parameters

session | an EAuthenticationSession |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

the result of the authentication session

Since 3.6

### e_authentication_session_new ()

    EAuthenticationSession *
    e_authentication_session_new (struct _ESourceRegistryServer *server,
                                  ESourceAuthenticator *authenticator,
                                  const gchar *source_uid);

`e_authentication_session_new` has been deprecated since version 3.8 and should not be used in newly-written code.

Use `e_source_registry_server_new_auth_session()` instead.

Creates a new EAuthenticationSession instance for `server` using `authenticator` to handle authentication attempts.

Note that `source_uid` does not necessarily have to be known to the `server` , as in the case when configuring a new data source, but it still has to be unique.

#### Parameters

server | an ESourceRegistryServer |
authenticator | an ESourceAuthenticator |
source_uid | a data source identifier |

#### Returns

a newly-created EAuthenticationSession

Since 3.6

### e_authentication_session_store_password_sync ()

    gboolean
    e_authentication_session_store_password_sync
                                   (EAuthenticationSession *session,
                                    const gchar *password,
                                    gboolean permanently,
                                    GCancellable *cancellable,
                                    GError **error);

`e_authentication_session_store_password_sync` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_store_password_sync()` instead.

Store a password for the data source that `session` is representing. If `permanently` is `TRUE`, the password is stored in the default keyring. Otherwise the password is stored in the memory-only session keyring. If an error occurs, the function sets `error` and returns `FALSE`.

#### Parameters

session | an EAuthenticationSession |
password | the password to store |
permanently | store permanently or just for the session |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since 3.6

### e_authentication_session_store_password ()

    void
    e_authentication_session_store_password
                                   (EAuthenticationSession *session,
                                    const gchar *password,
                                    gboolean permanently,
                                    gint io_priority,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

`e_authentication_session_store_password` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_store_password()` instead.

Asynchronously stores a password for the data source that `session` is representing. If `permanently` is `TRUE`, the password is stored in the default keyring. Otherwise the password is stored in the memory-only session keyring.

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

#### Parameters

session | an EAuthenticationSession |
password | the password to store |
permanently | store permanently or just for the session |
io_priority | the I/O priority of the request |
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_session_store_password_finish ()

    gboolean
    e_authentication_session_store_password_finish
                                   (EAuthenticationSession *session,
                                    GAsyncResult *result,
                                    GError **error);

`e_authentication_session_store_password_finish` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_store_password_finish()` instead.

Finished the operation started with `e_authentication_session_store_password()`.

#### Parameters

session | an EAuthenticationSession |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since 3.6

### e_authentication_session_lookup_password_sync ()

    gboolean
    e_authentication_session_lookup_password_sync
                                   (EAuthenticationSession *session,
                                    GCancellable *cancellable,
                                    gchar **password,
                                    GError **error);

`e_authentication_session_lookup_password_sync` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_lookup_password_sync()` instead.

Looks up a password for the data source that `session` is representing. Both the default and session keyrings are queried.

Note the boolean return value indicates whether the lookup operation itself completed successfully, not whether a password was found. If no password was found, the function will set `password` to `NULL` but still return `TRUE`. If an error occurs, the function sets `error` and returns `FALSE`.

#### Parameters

session | an EAuthenticationSession |
cancellable | optional GCancellable object, or `NULL` |
password | return location for the password, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since 3.6

### e_authentication_session_lookup_password ()

    void
    e_authentication_session_lookup_password
                                   (EAuthenticationSession *session,
                                    gint io_priority,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

`e_authentication_session_lookup_password` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_lookup_password()` instead.

Asynchronously looks up a password for the data source that `session` is representing. Both the default and session keyrings are queried.

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

#### Parameters

session | an EAuthenticationSession |
io_priority | the I/O priority of the request |
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_session_lookup_password_finish ()

    gboolean
    e_authentication_session_lookup_password_finish
                                   (EAuthenticationSession *session,
                                    GAsyncResult *result,
                                    gchar **password,
                                    GError **error);

`e_authentication_session_lookup_password_finish` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_lookup_password_finish()` instead.

Finishes the operation started with `e_authentication_session_lookup_password()`.

Note the boolean return value indicates whether the lookup operation itself completed successfully, not whether a password was found. If no password was found, the function will set `password` to `NULL` but still return `TRUE`. If an error occurs, the function sets `error` and returns `FALSE`.

#### Parameters

session | an EAuthenticationSession |
result | a GAsyncResult |
password | return location for the password, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since 3.6

### e_authentication_session_delete_password_sync ()

    gboolean
    e_authentication_session_delete_password_sync
                                   (EAuthenticationSession *session,
                                    GCancellable *cancellable,
                                    GError **error);

`e_authentication_session_delete_password_sync` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_delete_password_sync()` instead.

Deletes the password for the data source that `session` is representing from either the default keyring or session keyring.

Note the boolean return value indicates whether the delete operation itself completed successfully, not whether a password was found and deleted. If no password was found, the function will still return `TRUE`. If an error occurs, the function sets `error` and returns `FALSE`.

#### Parameters

session | an EAuthenticationSession |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since 3.6

### e_authentication_session_delete_password ()

    void
    e_authentication_session_delete_password
                                   (EAuthenticationSession *session,
                                    gint io_priority,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

`e_authentication_session_delete_password` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_delete_password()` instead.

Asyncronously deletes the password for the data source that `session` is representing from either the default keyring or session keyring.

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

#### Parameters

session | an EAuthenticationSession |
io_priority | the I/O priority of the request |
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_session_delete_password_finish ()

    gboolean
    e_authentication_session_delete_password_finish
                                   (EAuthenticationSession *session,
                                    GAsyncResult *result,
                                    GError **error);

`e_authentication_session_delete_password_finish` has been deprecated since version 3.12 and should not be used in newly-written code.

Use `e_source_delete_password_finish()` instead.

Finishes the operation started with `e_authentication_session_delete_password()`.

Note the boolean return value indicates whether the delete operation itself completed successfully, not whether a password was found and deleted. If no password was found, the function will still return `TRUE`. If an error occurs, the function sets `error` and returns `FALSE`.

#### Parameters

session | an EAuthenticationSession |
result | a GAsyncResult |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error

Since 3.6

## Types and Values

### struct EAuthenticationSession

    struct EAuthenticationSession {
    };

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

Since 3.6

### struct EAuthenticationSessionClass

    struct EAuthenticationSessionClass {
    	/* Methods */
    	EAuthenticationSessionResult
    			(*execute_sync) (EAuthenticationSession *session,
    					 GCancellable *cancellable,
    					 GError **error);
    	void		(*execute) (EAuthenticationSession *session,
    					 gint io_priority,
    					 GCancellable *cancellable,
    					 GAsyncReadyCallback callback,
    					 gpointer user_data);
    	EAuthenticationSessionResult
    			(*execute_finish)
    					(EAuthenticationSession *session,
    					 GAsyncResult *result,
    					 GError **error);
    };

Class structure for the EAuthenticationSession object

#### Members

`execute_sync` () | Authenticate synchronously |
`execute` () | Initiate authentication |
`execute_finish` () | Complete authentication |

Since 3.6

### E_AUTHENTICATION_SESSION_KEYRING_ERROR

    #define             E_AUTHENTICATION_SESSION_KEYRING_ERROR

`E_AUTHENTICATION_SESSION_KEYRING_ERROR` has been deprecated since version 3.8 and should not be used in newly-written code.

The SECRET_ERROR domain is now used instead.

Error domain for password storage and retrieval.

No longer used.

Since 3.6