## EBackend

EBackend — An abstract base class for backends

## Functions

gboolean | e_backend_get_online ()
void | e_backend_set_online ()
ESource * | e_backend_get_source ()
GSocketConnectable * | e_backend_ref_connectable ()
void | e_backend_set_connectable ()
GMainContext * | e_backend_ref_main_context ()
gboolean | e_backend_authenticate_sync ()
void | e_backend_authenticate ()
gboolean | e_backend_authenticate_finish ()
struct _EUserPrompter * | e_backend_get_user_prompter ()
ETrustPromptResponse | e_backend_trust_prompt_sync ()
void | e_backend_trust_prompt ()
ETrustPromptResponse | e_backend_trust_prompt_finish ()
gboolean | e_backend_get_destination_address ()
gboolean | e_backend_is_destination_reachable ()

## Types and Values

struct | EBackend
struct | EBackendClass

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