## 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,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_client_cache_get_client           (EClientCache *client_cache,
                                                             ESource *source,
                                                             const gchar *extension_name,
                                                             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

      "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,
                                                             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.

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

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