EBackend: Evolution-Data-Server Reference Manual

## 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 ()
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 ()
void | e_backend_prepare_shutdown ()
gboolean | e_backend_credentials_required_sync ()
void | e_backend_credentials_required ()
gboolean | e_backend_credentials_required_finish ()
void | e_backend_schedule_credentials_required ()
void | e_backend_schedule_authenticate ()
void | e_backend_ensure_source_status_connected ()

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

### 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` |
error | return location for a GError, 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.16.4

## 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` () |  |
`authenticate_sync` () | Authenticate synchronously |

Since: 3.4