EBackend

EBackend — An abstract base class for backends

Properties

GSocketConnectable * connectable Read / Write
GMainContext * main-context Read
gboolean online Read / Write
ESource * source Read / Write / Construct Only
EUserPrompter * user-prompter Read

Types and Values

struct EBackend
struct EBackendClass

Object Hierarchy

    GObject
    ╰── EBackend
        ├── EBookBackend
        ├── ECalBackend
        ╰── ECollectionBackend

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_ensure_online_state_updated ()

void
e_backend_ensure_online_state_updated (EBackend *backend,
                                       GCancellable *cancellable);

Makes sure that the "online" property is updated, that is, if there is any destination reachability test pending, it'll be done immediately and the only state will be updated as well.

Parameters

backend

an EBackend

 

cancellable

optional GCancellable object, or NULL

 

Since: 3.18


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_credentials_required_sync ()

gboolean
e_backend_credentials_required_sync (EBackend *backend,
                                     ESourceCredentialsReason reason,
                                     const gchar *certificate_pem,
                                     GTlsCertificateFlags certificate_errors,
                                     const GError *op_error,
                                     GCancellable *cancellable,
                                     GError **error);

Synchronously lets the clients know that the backned requires credentials to be properly opened. It's a proxy function for e_source_invoke_credentials_required_sync(), where can be found more information about actual parameters meaning.

The provided credentials are received through EBackend::authenticate_sync() method asynchronously.

If an error occurs, the function sets error and returns FALSE.

Parameters

backend

an EBackend

 

reason

an ESourceCredentialsReason, why the credentials are required

 

certificate_pem

PEM-encoded secure connection certificate, or an empty string

 

certificate_errors

a bit-or of GTlsCertificateFlags for secure connection certificate

 

op_error

a GError with a description of the previous credentials error, or NULL.

[allow-none]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since: 3.16


e_backend_credentials_required ()

void
e_backend_credentials_required (EBackend *backend,
                                ESourceCredentialsReason reason,
                                const gchar *certificate_pem,
                                GTlsCertificateFlags certificate_errors,
                                const GError *op_error,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously calls the e_backend_credentials_required_sync() on the backend , to inform clients that credentials are required.

When the operation is finished, callback will be called. You can then call e_backend_credentials_required_finish() to get the result of the operation.

Parameters

backend

an EBackend

 

reason

an ESourceCredentialsReason, why the credentials are required

 

certificate_pem

PEM-encoded secure connection certificate, or an empty string

 

certificate_errors

a bit-or of GTlsCertificateFlags for secure connection certificate

 

op_error

a GError with a description of the previous credentials error, or NULL.

[allow-none]

cancellable

optional GCancellable object, or NULL

 

Since: 3.16


e_backend_credentials_required_finish ()

gboolean
e_backend_credentials_required_finish (EBackend *backend,
                                       GAsyncResult *result,
                                       GError **error);

Finishes the operation started with e_backend_credentials_required().

If an error occurs, the function sets error and returns FALSE.

Parameters

backend

an EBackend

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on error

Since: 3.16


e_backend_schedule_credentials_required ()

void
e_backend_schedule_credentials_required
                               (EBackend *backend,
                                ESourceCredentialsReason reason,
                                const gchar *certificate_pem,
                                GTlsCertificateFlags certificate_errors,
                                const GError *op_error,
                                GCancellable *cancellable,
                                const gchar *who_calls);

Asynchronously invokes e_backend_credentials_required(), but installs its own callback which only prints a runtime warning on the console when the call fails. The who_calls is a prefix of the console message. This is useful when the caller just wants to start the operation without having actual place where to show the operation result.

Parameters

backend

an EBackend

 

reason

an ESourceCredentialsReason, why the credentials are required

 

certificate_pem

PEM-encoded secure connection certificate, or an empty string

 

certificate_errors

a bit-or of GTlsCertificateFlags for secure connection certificate

 

op_error

a GError with a description of the previous credentials error, or NULL.

[allow-none]

cancellable

optional GCancellable object, or NULL

 

who_calls

an identification who calls this.

[allow-none]

Since: 3.16


e_backend_schedule_authenticate ()

void
e_backend_schedule_authenticate (EBackend *backend,
                                 const ENamedParameters *credentials);

Schedules a new authenticate session, cancelling any previously run. This is usually done automatically, when an 'authenticate' signal is received for the associated ESource. With NULL credentials an attempt without it is run.

Parameters

backend

an EBackend

 

credentials

a credentials to use to authenticate, or NULL.

[allow-none]

Since: 3.16


e_backend_ensure_source_status_connected ()

void
e_backend_ensure_source_status_connected
                               (EBackend *backend);

Makes sure that the associated ESource::connection-status is connected. This is useful in cases when the backend can connect to the destination without invoking EBackend::authenticate_sync, possibly through e_backend_schedule_authenticate().

Parameters

backend

an EBackend

 

Since: 3.18


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


e_backend_prepare_shutdown ()

void
e_backend_prepare_shutdown (EBackend *backend);

Let's the backend know that it'll be shut down shortly, no client connects to it anymore. The backend can free any resources which reference it, for example the opened views.

Parameters

backend

an EBackend instance

 

Since: 3.16

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 (*get_destination_address)
						(EBackend *backend,
						 gchar **host,
						 guint16 *port);
	void		(*prepare_shutdown) (EBackend *backend);

	ESourceAuthenticationResult
			(*authenticate_sync) (EBackend *backend,
						 const ENamedParameters *credentials,
						 gchar **out_certificate_pem,
						 GTlsCertificateFlags *out_certificate_errors,
						 GCancellable *cancellable,
						 GError **error);
};

Base class structure for the EBackend class

Members

get_destination_address ()

Fetch the destination address

 

prepare_shutdown ()

Prepare for shutdown

 

authenticate_sync ()

Authenticate synchronously

 

Since: 3.4

Property Details

The “connectable” property

  “connectable”              GSocketConnectable *

Socket endpoint of a network service.

Flags: Read / Write


The “main-context” property

  “main-context”             GMainContext *

The main loop context on which to attach event sources.

Flags: Read


The “online” property

  “online”                   gboolean

Whether the backend is online.

Flags: Read / Write

Default value: TRUE


The “source” property

  “source”                   ESource *

The data source being acted upon.

Flags: Read / Write / Construct Only


The “user-prompter” property

  “user-prompter”            EUserPrompter *

User prompter instance.

Flags: Read