Evolution-Data-Server Manual: Backend Utilities (libebackend) | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
Synopsis
#include <libebackend/libebackend.h> struct EAuthenticationSession; enum EAuthenticationSessionResult; struct _ESourceRegistryServer * e_authentication_session_get_server (EAuthenticationSession *session
); ESourceAuthenticator * e_authentication_session_get_authenticator (EAuthenticationSession *session
); const gchar * e_authentication_session_get_source_uid (EAuthenticationSession *session
); const gchar * e_authentication_session_get_prompt_title (EAuthenticationSession *session
); gchar * e_authentication_session_dup_prompt_title (EAuthenticationSession *session
); void e_authentication_session_set_prompt_title (EAuthenticationSession *session
,const gchar *prompt_title
); const gchar * e_authentication_session_get_prompt_message (EAuthenticationSession *session
); gchar * e_authentication_session_dup_prompt_message (EAuthenticationSession *session
); void e_authentication_session_set_prompt_message (EAuthenticationSession *session
,const gchar *prompt_message
); const gchar * e_authentication_session_get_prompt_description (EAuthenticationSession *session
); gchar * e_authentication_session_dup_prompt_description (EAuthenticationSession *session
); void e_authentication_session_set_prompt_description (EAuthenticationSession *session
,const gchar *prompt_description
); EAuthenticationSessionResult e_authentication_session_execute_sync (EAuthenticationSession *session
,GCancellable *cancellable
,GError **error
); void e_authentication_session_execute (EAuthenticationSession *session
,gint io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); EAuthenticationSessionResult e_authentication_session_execute_finish (EAuthenticationSession *session
,GAsyncResult *result
,GError **error
); gboolean e_authentication_session_store_password_sync (EAuthenticationSession *session
,const gchar *password
,gboolean permanently
,GCancellable *cancellable
,GError **error
); void e_authentication_session_store_password (EAuthenticationSession *session
,const gchar *password
,gboolean permanently
,gint io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gboolean e_authentication_session_store_password_finish (EAuthenticationSession *session
,GAsyncResult *result
,GError **error
); gboolean e_authentication_session_lookup_password_sync (EAuthenticationSession *session
,GCancellable *cancellable
,gchar **password
,GError **error
); void e_authentication_session_lookup_password (EAuthenticationSession *session
,gint io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gboolean e_authentication_session_lookup_password_finish (EAuthenticationSession *session
,GAsyncResult *result
,gchar **password
,GError **error
); gboolean e_authentication_session_delete_password_sync (EAuthenticationSession *session
,GCancellable *cancellable
,GError **error
); void e_authentication_session_delete_password (EAuthenticationSession *session
,gint io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gboolean e_authentication_session_delete_password_finish (EAuthenticationSession *session
,GAsyncResult *result
,GError **error
); #define E_AUTHENTICATION_SESSION_KEYRING_ERROR EAuthenticationSession * e_authentication_session_new (struct _ESourceRegistryServer *server
,ESourceAuthenticator *authenticator
,const gchar *source_uid
);
Properties
"authenticator" ESourceAuthenticator* : Read / Write / Construct Only "prompt-description" gchar* : Read / Write "prompt-message" gchar* : Read / Write "prompt-title" gchar* : Read / Write "server" ESourceRegistryServer* : Read / Write / Construct Only "source-uid" gchar* : Read / Write / Construct Only
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.
Details
struct EAuthenticationSession
struct EAuthenticationSession;
Contains only private data that should be read and manipulated using the functions below.
Since 3.6
enum EAuthenticationSessionResult
typedef enum { E_AUTHENTICATION_SESSION_ERROR, E_AUTHENTICATION_SESSION_SUCCESS, E_AUTHENTICATION_SESSION_DISMISSED } EAuthenticationSessionResult;
Completion codes used by EAuthenticationSession.
An error occurred while authenticating. | |
Client reported successful authentication. | |
User dismissed the authentication prompt. |
Since 3.6
e_authentication_session_get_server ()
struct _ESourceRegistryServer * e_authentication_session_get_server
(EAuthenticationSession *session
);
Returns the ESourceRegistryServer to which session
belongs.
|
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.
|
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".
|
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.
|
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.
|
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.
|
an EAuthenticationSession |
|
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.
|
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.
|
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.
|
an EAuthenticationSession |
|
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.
|
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.
|
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.
|
an EAuthenticationSession |
|
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.
|
an EAuthenticationSession |
|
optional GCancellable object, or NULL
|
|
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.
|
an EAuthenticationSession |
|
the I/O priority of the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
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.
|
an EAuthenticationSession |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
the result of the authentication session |
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
);
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
.
|
an EAuthenticationSession |
|
the password to store |
|
store permanently or just for the session |
|
optional GCancellable object, or NULL
|
|
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
);
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.
|
an EAuthenticationSession |
|
the password to store |
|
store permanently or just for the session |
|
the I/O priority of the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
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
);
Finished the operation started with
e_authentication_session_store_password()
.
|
an EAuthenticationSession |
|
a GAsyncResult |
|
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
);
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
.
|
an EAuthenticationSession |
|
optional GCancellable object, or NULL
|
|
return location for the password, or NULL
|
|
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
);
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.
|
an EAuthenticationSession |
|
the I/O priority of the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
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
);
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
.
|
an EAuthenticationSession |
|
a GAsyncResult |
|
return location for the password, or NULL
|
|
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
);
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
.
|
an EAuthenticationSession |
|
optional GCancellable object, or NULL
|
|
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
);
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.
|
an EAuthenticationSession |
|
the I/O priority of the request |
|
optional GCancellable object, or NULL
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
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
);
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
.
|
an EAuthenticationSession |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on error |
Since 3.6
E_AUTHENTICATION_SESSION_KEYRING_ERROR
#define E_AUTHENTICATION_SESSION_KEYRING_ERROR
Warning
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
e_authentication_session_new ()
EAuthenticationSession * e_authentication_session_new (struct _ESourceRegistryServer *server
,ESourceAuthenticator *authenticator
,const gchar *source_uid
);
Warning
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.
|
an ESourceRegistryServer |
|
an ESourceAuthenticator |
|
a data source identifier |
Returns : |
a newly-created EAuthenticationSession |
Since 3.6
Property Details
The "authenticator"
property
"authenticator" ESourceAuthenticator* : Read / Write / Construct Only
Handles authentication attempts.
The "prompt-description"
property
"prompt-description" gchar* : Read / Write
The detailed description of the prompt.
Default value: NULL
The "prompt-message"
property
"prompt-message" gchar* : Read / Write
The prompt message for the user.
Default value: NULL
The "prompt-title"
property
"prompt-title" gchar* : Read / Write
The title of the prompt.
Default value: NULL
The "server"
property
"server" ESourceRegistryServer* : Read / Write / Construct Only
The server to which the session belongs.