Evolution-Data-Server Manual: Backend Utilities (libebackend) | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
Synopsis
#include <libebackend/libebackend.h> struct EBackend; gboolean e_backend_get_online (EBackend *backend
); void e_backend_set_online (EBackend *backend
,gboolean online
); ESource * e_backend_get_source (EBackend *backend
); GSocketConnectable * e_backend_ref_connectable (EBackend *backend
); void e_backend_set_connectable (EBackend *backend
,GSocketConnectable *connectable
); GMainContext * e_backend_ref_main_context (EBackend *backend
); gboolean e_backend_authenticate_sync (EBackend *backend
,ESourceAuthenticator *auth
,GCancellable *cancellable
,GError **error
); void e_backend_authenticate (EBackend *backend
,ESourceAuthenticator *auth
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); gboolean e_backend_authenticate_finish (EBackend *backend
,GAsyncResult *result
,GError **error
); struct _EUserPrompter * e_backend_get_user_prompter (EBackend *backend
); ETrustPromptResponse e_backend_trust_prompt_sync (EBackend *backend
,const ENamedParameters *parameters
,GCancellable *cancellable
,GError **error
); void e_backend_trust_prompt (EBackend *backend
,const ENamedParameters *parameters
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
); ETrustPromptResponse e_backend_trust_prompt_finish (EBackend *backend
,GAsyncResult *result
,GError **error
); gboolean e_backend_get_destination_address (EBackend *backend
,gchar **host
,guint16 *port
); gboolean e_backend_is_destination_reachable (EBackend *backend
,GCancellable *cancellable
,GError **error
);
Properties
"connectable" GSocketConnectable* : Read / Write "main-context" GMainContext* : Read "online" gboolean : Read / Write / Construct "source" ESource* : Read / Write / Construct Only "user-prompter" EUserPrompter* : Read
Description
An EBackend is paired with an ESource to facilitate performing actions on the local or remote resource described by the ESource.
In other words, whereas a certain backend type knows how to talk to a certain type of server or data store, the ESource fills in configuration details such as host name, user name, resource path, etc.
All EBackend instances are created by an EBackendFactory.
Details
struct EBackend
struct EBackend;
Contains only private data that should be read and manipulated using the functions below.
Since 3.4
e_backend_get_online ()
gboolean e_backend_get_online (EBackend *backend
);
Returns the online state of backend
: TRUE
if backend
is online,
FALSE
if offline.
If the "connectable" property is non-NULL
, the backend
will
automatically determine whether the network service should be reachable,
and hence whether the backend
is "online". But subclasses may
override the online state if, for example, a connection attempt fails.
|
an EBackend |
Returns : |
the online state |
Since 3.4
e_backend_set_online ()
void e_backend_set_online (EBackend *backend
,gboolean online
);
Sets the online state of backend
: TRUE
if backend
is online,
FALSE
if offline.
If the "connectable" property is non-NULL
, the backend
will
automatically determine whether the network service should be reachable,
and hence whether the backend
is "online". But subclasses may
override the online state if, for example, a connection attempt fails.
|
an EBackend |
|
the online state |
Since 3.4
e_backend_get_source ()
ESource * e_backend_get_source (EBackend *backend
);
Returns the ESource to which backend
is paired.
Since 3.4
e_backend_ref_connectable ()
GSocketConnectable * e_backend_ref_connectable (EBackend *backend
);
Returns the socket endpoint for the network service to which backend
is a client, or NULL
if backend
does not use network sockets.
The initial value of the "connectable" property is derived from
the ESourceAuthentication extension of the backend
's "source"
property, if the extension is present.
The returned GSocketConnectable is referenced for thread-safety and
must be unreferenced with g_object_unref()
when finished with it.
|
an EBackend |
Returns : |
a GSocketConnectable, or NULL
|
Since 3.8
e_backend_set_connectable ()
void e_backend_set_connectable (EBackend *backend
,GSocketConnectable *connectable
);
Sets the socket endpoint for the network service to which backend
is
a client. This can be NULL
if backend
does not use network sockets.
The initial value of the "connectable" property is derived from
the ESourceAuthentication extension of the backend
's "source"
property, if the extension is present.
|
an EBackend |
|
a GSocketConnectable, or NULL
|
Since 3.8
e_backend_ref_main_context ()
GMainContext * e_backend_ref_main_context (EBackend *backend
);
Returns the GMainContext on which event sources for backend
are to
be attached.
The returned GMainContext is referenced for thread-safety and must be
unreferenced with g_main_context_unref()
when finished with it.
|
an EBackend |
Returns : |
a GMainContext. [transfer full] |
Since 3.8
e_backend_authenticate_sync ()
gboolean e_backend_authenticate_sync (EBackend *backend
,ESourceAuthenticator *auth
,GCancellable *cancellable
,GError **error
);
Convenience function providing a consistent authentication interface for backends running in either the registry service itself or a client process communicating with the registry service over D-Bus.
Authenticates backend
's "source", using auth
to handle
authentication attempts. The backend
and auth
arguments may be one
and the same if backend
implements the ESourceAuthenticator interface.
The operation loops until authentication is successful or the user aborts
further authentication attempts. If an error occurs, the function will
set error
and return FALSE
.
|
an EBackend |
|
an ESourceAuthenticator |
|
optional GCancellable object, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
Since 3.6
e_backend_authenticate ()
void e_backend_authenticate (EBackend *backend
,ESourceAuthenticator *auth
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Convenience function providing a consistent authentication interface for backends running in either the registry service itself or a client process communicating with the registry service over D-Bus.
Asynchronously authenticates backend
's "source", using auth
to handle authentication attempts. The backend
and auth
arguments may
be one and the same if backend
implements the ESourceAuthenticator
interface. The operation loops until authentication is succesful or the
user aborts further authentication attempts.
When the operation is finished, callback
will be called. You can then
call e_backend_authenticate_finish()
to get the result of the operation.
|
an EBackend |
|
an ESourceAuthenticator |
|
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_backend_authenticate_finish ()
gboolean e_backend_authenticate_finish (EBackend *backend
,GAsyncResult *result
,GError **error
);
Finishes the operation started with e_backend_authenticate()
. If
an error occurred, the function will set error
and return FALSE
.
|
an EBackend |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE on failure |
Since 3.6
e_backend_get_user_prompter ()
struct _EUserPrompter * e_backend_get_user_prompter (EBackend *backend
);
Gets an instance of EUserPrompter, associated with this backend
.
The instance is owned by the backend
.
|
an EBackend |
Returns : |
an EUserPrompter instance. [transfer-none] |
Since 3.8
e_backend_trust_prompt_sync ()
ETrustPromptResponse e_backend_trust_prompt_sync (EBackend *backend
,const ENamedParameters *parameters
,GCancellable *cancellable
,GError **error
);
Asks a user a trust prompt with given parameters
, and returns what
user responded. This blocks until the response is delivered.
|
an EBackend |
|
an ENamedParameters with values for the trust prompt |
|
optional GCancellable object, or NULL . [allow-none]
|
|
return location for a GError, or NULL
|
Returns : |
an ETrustPromptResponse what user responded
Note: The function can return also E_TRUST_PROMPT_RESPONSE_UNKNOWN ,
it's on error or if user closes the trust prompt dialog with other
than the offered buttons. Usual behaviour in such case is to treat
it as a temporary reject. |
Since 3.8
e_backend_trust_prompt ()
void e_backend_trust_prompt (EBackend *backend
,const ENamedParameters *parameters
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Initiates a user trust prompt with given parameters
.
When the operation is finished, callback
will be called. You can then
call e_backend_trust_prompt_finish()
to get the result of the operation.
|
an EBackend |
|
an ENamedParameters with values for the trust prompt |
|
optional GCancellable object, or NULL . [allow-none]
|
|
a GAsyncReadyCallback to call when the request is satisfied |
|
data to pass to the callback function |
Since 3.8
e_backend_trust_prompt_finish ()
ETrustPromptResponse e_backend_trust_prompt_finish (EBackend *backend
,GAsyncResult *result
,GError **error
);
Finishes the operation started with e_backend_trust_prompt()
.
If an error occurred, the function will set error
and return
E_TRUST_PROMPT_RESPONSE_UNKNOWN
.
|
an EBackend |
|
a GAsyncResult |
|
return location for a GError, or NULL
|
Returns : |
an ETrustPromptResponse what user responded
Note: The function can return also E_TRUST_PROMPT_RESPONSE_UNKNOWN ,
it's on error or if user closes the trust prompt dialog with other
than the offered buttons. Usual behaviour in such case is to treat
it as a temporary reject. |
Since 3.8
e_backend_get_destination_address ()
gboolean e_backend_get_destination_address (EBackend *backend
,gchar **host
,guint16 *port
);
Provides destination server host name and port to which
the backend connects. This is used to determine required
connection point for e_backend_destination_is_reachable()
.
The host
is a newly allocated string, which will be freed
with g_free()
. When backend
sets both host
and port
, then
it should return TRUE
, indicating it's a remote backend.
Default implementation returns FALSE
, which is treated
like the backend is local, no checking for server reachability
is possible.
|
an EBackend instance |
|
destination server host name. [out] |
|
destination server port. [out] |
Returns : |
TRUE , when it's a remote backend and provides both
host and port ; FALSE otherwise. |
Since 3.8
e_backend_is_destination_reachable ()
gboolean e_backend_is_destination_reachable (EBackend *backend
,GCancellable *cancellable
,GError **error
);
Checks whether the backend
's destination server, as returned
by e_backend_get_destination_address()
, is reachable.
If the e_backend_get_destination_address()
returns FALSE
, this function
returns TRUE
, meaning the destination is always reachable.
This uses GNetworkMonitor's g_network_monitor_can_reach()
for reachability tests.
|
an EBackend instance |
|
a GCancellable instance, or NULL
|
|
a GError for errors, or NULL
|
Returns : |
TRUE , when destination server address is reachable or
the backend doesn't provide destination address; FALSE if
the backend destination server cannot be reached currently. |
Since 3.8
Property Details
The "connectable"
property
"connectable" GSocketConnectable* : Read / Write
Socket endpoint of a network service.
The "main-context"
property
"main-context" GMainContext* : Read
The main loop context on which to attach event sources.
The "online"
property
"online" gboolean : Read / Write / Construct
Whether the backend is online.
Default value: TRUE
The "source"
property
"source" ESource* : Read / Write / Construct Only
The data source being acted upon.