EClientCache

EClientCache — Shared EClient instances

Synopsis

#include <e-util/e-util.h>

struct              EClientCache;
EClientCache *      e_client_cache_new                  (ESourceRegistry *registry);
ESourceRegistry *   e_client_cache_ref_registry         (EClientCache *client_cache);
EClient *           e_client_cache_get_client_sync      (EClientCache *client_cache,
                                                         ESource *source,
                                                         const gchar *extension_name,
                                                         guint32 wait_for_connected_seconds,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_client_cache_get_client           (EClientCache *client_cache,
                                                         ESource *source,
                                                         const gchar *extension_name,
                                                         guint32 wait_for_connected_seconds,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
EClient *           e_client_cache_get_client_finish    (EClientCache *client_cache,
                                                         GAsyncResult *result,
                                                         GError **error);
EClient *           e_client_cache_ref_cached_client    (EClientCache *client_cache,
                                                         ESource *source,
                                                         const gchar *extension_name);
gboolean            e_client_cache_is_backend_dead      (EClientCache *client_cache,
                                                         ESource *source,
                                                         const gchar *extension_name);

Object Hierarchy

  GObject
   +----EClientCache

Implemented Interfaces

EClientCache implements EExtensible.

Properties

  "registry"                 ESourceRegistry*      : Read / Write / Construct Only

Signals

  "allow-auth-prompt"                              : Run First
  "backend-died"                                   : Run Last
  "backend-error"                                  : Run Last
  "client-connected"                               : Run First
  "client-created"                                 : Run First
  "client-notify"                                  : No Hooks

Description

EClientCache provides for application-wide sharing of EClient instances and centralized rebroadcasting of "backend-died", "backend-error" and "notify" signals from cached EClient instances.

EClientCache automatically invalidates cache entries in response to "backend-died" signals. The EClient instance is discarded, and a new instance is created on the next request.

Details

struct EClientCache

struct EClientCache;

Contains only private data that should be read and manipulated using the functions below.


e_client_cache_new ()

EClientCache *      e_client_cache_new                  (ESourceRegistry *registry);

Creates a new EClientCache instance.

registry :

an ESourceRegistry

Returns :

an EClientCache

e_client_cache_ref_registry ()

ESourceRegistry *   e_client_cache_ref_registry         (EClientCache *client_cache);

Returns the ESourceRegistry passed to e_client_cache_new().

The returned ESourceRegistry is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

client_cache :

an EClientCache

Returns :

an ESourceRegistry

e_client_cache_get_client_sync ()

EClient *           e_client_cache_get_client_sync      (EClientCache *client_cache,
                                                         ESource *source,
                                                         const gchar *extension_name,
                                                         guint32 wait_for_connected_seconds,
                                                         GCancellable *cancellable,
                                                         GError **error);

Obtains a shared EClient instance for source, or else creates a new EClient instance to be shared.

The extension_name determines the type of EClient to obtain. Valid extension_name values are:

E_SOURCE_EXTENSION_ADDRESS_BOOK will obtain an EBookClient.

E_SOURCE_EXTENSION_CALENDAR will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_EVENTS.

E_SOURCE_EXTENSION_MEMO_LIST will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_MEMOS.

E_SOURCE_EXTENSION_TASK_LIST will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_TASKS.

The source must already have an ESourceExtension by that name for this function to work. All other extension_name values will result in an error.

The wait_for_connected_seconds argument had been added since 3.16, to let the caller decide how long to wait for the backend to fully connect to its (possibly remote) data store. This is required due to a change in the authentication process, which is fully asynchronous and done on the client side, while not every client is supposed to response to authentication requests. In case the backend will not connect within the set interval, then it is opened in an offline mode. A special value -1 can be used to not wait for the connected state at all.

If a request for the same source and extension_name is already in progress when this function is called, this request will "piggyback" on the in-progress request such that they will both succeed or fail simultaneously.

Unreference the returned EClient with g_object_unref() when finished with it. If an error occurs, the function will set error and return NULL.

client_cache :

an EClientCache

source :

an ESource

extension_name :

an extension name

wait_for_connected_seconds :

timeout, in seconds, to wait for the backend to be fully connected

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

an EClient, or NULL

e_client_cache_get_client ()

void                e_client_cache_get_client           (EClientCache *client_cache,
                                                         ESource *source,
                                                         const gchar *extension_name,
                                                         guint32 wait_for_connected_seconds,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously obtains a shared EClient instance for source, or else creates a new EClient instance to be shared.

The extension_name determines the type of EClient to obtain. Valid extension_name values are:

E_SOURCE_EXTENSION_ADDRESS_BOOK will obtain an EBookClient.

E_SOURCE_EXTENSION_CALENDAR will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_EVENTS.

E_SOURCE_EXTENSION_MEMO_LIST will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_MEMOS.

E_SOURCE_EXTENSION_TASK_LIST will obtain an ECalClient with a "source-type" of E_CAL_CLIENT_SOURCE_TYPE_TASKS.

The source must already have an ESourceExtension by that name for this function to work. All other extension_name values will result in an error.

The wait_for_connected_seconds argument had been added since 3.16, to let the caller decide how long to wait for the backend to fully connect to its (possibly remote) data store. This is required due to a change in the authentication process, which is fully asynchronous and done on the client side, while not every client is supposed to response to authentication requests. In case the backend will not connect within the set interval, then it is opened in an offline mode. A special value -1 can be used to not wait for the connected state at all.

If a request for the same source and extension_name is already in progress when this function is called, this request will "piggyback" on the in-progress request such that they will both succeed or fail simultaneously.

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

client_cache :

an EClientCache

source :

an ESource

extension_name :

an extension name

wait_for_connected_seconds :

timeout, in seconds, to wait for the backend to be fully connected

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

e_client_cache_get_client_finish ()

EClient *           e_client_cache_get_client_finish    (EClientCache *client_cache,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_client_cache_get_client().

Unreference the returned EClient with g_object_unref() when finished with it. If an error occurred, the function will set error and return NULL.

client_cache :

an EClientCache

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

an EClient, or NULL

e_client_cache_ref_cached_client ()

EClient *           e_client_cache_ref_cached_client    (EClientCache *client_cache,
                                                         ESource *source,
                                                         const gchar *extension_name);

Returns a shared EClient instance for source and extension_name if such an instance is already cached, or else NULL. This function does not create a new EClient instance, and therefore does not block.

See e_client_cache_get_client() for valid extension_name values.

The returned EClient is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

client_cache :

an EClientCache

source :

an ESource

extension_name :

an extension name

Returns :

an EClient, or NULL

e_client_cache_is_backend_dead ()

gboolean            e_client_cache_is_backend_dead      (EClientCache *client_cache,
                                                         ESource *source,
                                                         const gchar *extension_name);

Returns TRUE if an EClient instance for source and extension_name was recently discarded after having emitted a "backend-died" signal, and a replacement EClient instance has not yet been created.

client_cache :

an EClientCache

source :

an ESource

extension_name :

an extension name

Returns :

whether the backend for source and extension_name died

Property Details

The "registry" property

  "registry"                 ESourceRegistry*      : Read / Write / Construct Only

The ESourceRegistry manages ESource instances.

Signal Details

The "allow-auth-prompt" signal

void                user_function                      (EClientCache *client_cache,
                                                        ESource      *source,
                                                        gpointer      user_data)         : Run First

This signal is emitted with e_client_cache_emit_allow_auth_prompt() to let any listeners know to enable credentials prompt for the given source.

client_cache :

an EClientCache, which sent the signal

source :

an ESource

user_data :

user data set when the signal handler was connected.

Since 3.16


The "backend-died" signal

void                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        EAlert       *alert,
                                                        gpointer      user_data)         : Run Last

Rebroadcasts a "backend-died" signal emitted by client, along with a pre-formatted EAlert.

As a convenience to signal handlers, this signal is always emitted from the GMainContext that was thread-default when the client_cache was created.

client_cache :

the EClientCache that received the signal

client :

the EClient that received the D-Bus notification

alert :

an EAlert with a user-friendly error description

user_data :

user data set when the signal handler was connected.

The "backend-error" signal

void                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        EAlert       *alert,
                                                        gpointer      user_data)         : Run Last

Rebroadcasts a "backend-error" signal emitted by client, along with a pre-formatted EAlert.

As a convenience to signal handlers, this signal is always emitted from the GMainContext that was thread-default when the client_cache was created.

client_cache :

the EClientCache that received the signal

client :

the EClient that received the D-Bus notification

alert :

an EAlert with a user-friendly error description

user_data :

user data set when the signal handler was connected.

The "client-connected" signal

void                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        gpointer      user_data)         : Run First

This signal is emitted when a call to e_client_cache_get_client() triggers the creation of a new EClient instance, immediately after the client's opening phase is over.

See the difference with EClientCache::client-created, which is called on idle.

client_cache :

the EClientCache that received the signal

client :

the newly-created EClient

user_data :

user data set when the signal handler was connected.

The "client-created" signal

void                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        gpointer      user_data)         : Run First

This signal is emitted when a call to e_client_cache_get_client() triggers the creation of a new EClient instance, invoked in an idle callback.

See the difference with EClientCache::client-connected, which is called immediately.

client_cache :

the EClientCache that received the signal

client :

the newly-created EClient

user_data :

user data set when the signal handler was connected.

The "client-notify" signal

void                user_function                      (EClientCache *client_cache,
                                                        EClient      *client,
                                                        GParamSpec   *pspec,
                                                        gpointer      user_data)         : No Hooks

Rebroadcasts a "notify" signal emitted by client.

This signal supports "::detail" appendices to the signal name just like the "notify" signal, so you can connect to change notification signals for specific EClient properties.

As a convenience to signal handlers, this signal is always emitted from the GMainContext that was thread-default when the client_cache was created.

client_cache :

the EClientCache that received the signal

client :

the EClient whose property changed

pspec :

the GParamSpec of the property that changed

user_data :

user data set when the signal handler was connected.