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 ()
void | e_backend_ensure_online_state_updated ()
ESource * | e_backend_get_source ()
GSocketConnectable * | e_backend_ref_connectable ()
void | e_backend_set_connectable ()
GMainContext * | e_backend_ref_main_context ()
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 ()
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 ()

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

[transfer none]

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

[transfer full][nullable]

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 `EBackendClass.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`. | [nullable]
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`. | [nullable]
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.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`. | [nullable]
cancellable | optional GCancellable object, or `NULL` |
who_calls | an identification who calls this. | [nullable]

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`. | [nullable]

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

Owner: EBackend

Flags: Read / Write

### The `“main-context”` property

      “main-context”             GMainContext *

The main loop context on which to attach event sources.

Owner: EBackend

Flags: Read

### The `“online”` property

      “online”                   gboolean

Whether the backend is online.

Owner: EBackend

Flags: Read / Write

Default value: TRUE

### The `“source”` property

      “source”                   ESource *

The data source being acted upon.

Owner: EBackend

Flags: Read / Write / Construct Only

### The `“user-prompter”` property

      “user-prompter”            EUserPrompter *

User prompter instance.

Owner: EBackend

Flags: Read