## EBackend

EBackend — An abstract base class for backends

## Synopsis

    #include <libebackend/libebackend.h>

    struct              EBackend;
    struct              EBackendClass;
    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);

## 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

### 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

`authenticate_sync` () | Authenticate synchronously
`authenticate` () | Initiate authentication
`authenticate_finish` () | Complete authentication
`get_destination_address` () | Fetch the destination address

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`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