EBackend

EBackend — An abstract base class for backends

Functions

Types and Values

struct EBackend
struct EBackendClass

Object Hierarchy


Includes

#include <libebackend/libebackend.h>

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.

Functions

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.

Parameters

backend

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.

Parameters

backend

an EBackend

 

online

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.

Parameters

backend

an EBackend

 

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.

Parameters

backend

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.

Parameters

backend

an EBackend

 

connectable

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.

Parameters

backend

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.

Parameters

backend

an EBackend

 

auth

an ESourceAuthenticator

 

cancellable

optional GCancellable object, or NULL

 

error

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.

Parameters

backend

an EBackend

 

auth

an ESourceAuthenticator

 

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_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.

Parameters

backend

an EBackend

 

result

a GAsyncResult

 

error

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 returned instance is owned by the backend .

Parameters

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.

Parameters

backend

an EBackend

 

parameters

an ENamedParameters with values for the trust prompt

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

error

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.

Parameters

backend

an EBackend

 

parameters

an ENamedParameters with values for the trust prompt

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

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.

Parameters

backend

an EBackend

 

result

a GAsyncResult

 

error

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.

Parameters

backend

an EBackend instance

 

host

destination server host name.

[out]

port

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.

Parameters

backend

an EBackend instance

 

cancellable

a GCancellable instance, or NULL

 

error

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

Types and Values

struct EBackend

struct EBackend {
};

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

Since 3.4


struct EBackendClass

struct EBackendClass {
	/* Methods */
	gboolean (*authenticate_sync) (EBackend *backend,
						 ESourceAuthenticator *auth,
						 GCancellable *cancellable,
						 GError **error);
	void		(*authenticate)		(EBackend *backend,
						 ESourceAuthenticator *auth,
						 GCancellable *cancellable,
						 GAsyncReadyCallback callback,
						 gpointer user_data);
	gboolean (*authenticate_finish) (EBackend *backend,
						 GAsyncResult *result,
						 GError **error);

	gboolean (*get_destination_address)
						(EBackend *backend,
						 gchar **host,
						 guint16 *port);
};

Base class structure for the EBackend class

Members

authenticate_sync ()

Authenticate synchronously

 

authenticate ()

Initiate authentication

 

authenticate_finish ()

Complete authentication

 

get_destination_address ()

Fetch the destination address

 

Since 3.4