## EClientCache EClientCache — Shared EClient instances |

## Functions

EClientCache * | e_client_cache_new ()
ESourceRegistry * | e_client_cache_ref_registry ()
EClient * | e_client_cache_get_client_sync ()
void | e_client_cache_get_client ()
EClient * | e_client_cache_get_client_finish ()
EClient * | e_client_cache_ref_cached_client ()
gboolean | e_client_cache_is_backend_dead ()
void | e_client_cache_emit_allow_auth_prompt ()

## Types and Values

struct | EClientCache

## Includes

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

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

## Functions

### e_client_cache_new ()

    EClientCache *
    e_client_cache_new (ESourceRegistry *registry);

`e_client_cache_new` is deprecated and should not be used in newly-written code.

Creates a new EClientCache instance.

#### Parameters

registry | an ESourceRegistry |

#### Returns

an EClientCache

### e_client_cache_ref_registry ()

    ESourceRegistry *
    e_client_cache_ref_registry (EClientCache *client_cache);

`e_client_cache_ref_registry` is deprecated and should not be used in newly-written code.

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.

#### Parameters

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);

`e_client_cache_get_client_sync` is deprecated and should not be used in newly-written code.

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

#### Parameters

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);

`e_client_cache_get_client` is deprecated and should not be used in newly-written code.

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.

#### Parameters

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);

`e_client_cache_get_client_finish` is deprecated and should not be used in newly-written code.

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

#### Parameters

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);

`e_client_cache_ref_cached_client` is deprecated and should not be used in newly-written code.

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.

#### Parameters

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);

`e_client_cache_is_backend_dead` is deprecated and should not be used in newly-written code.

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.

#### Parameters

client_cache | an EClientCache |
source | an ESource |
extension_name | an extension name |

#### Returns

whether the backend for `source` and `extension_name` died

### e_client_cache_emit_allow_auth_prompt ()

    void
    e_client_cache_emit_allow_auth_prompt (EClientCache *client_cache,
                                           ESource *source);

`e_client_cache_emit_allow_auth_prompt` is deprecated and should not be used in newly-written code.

Emits 'allow-auth-prompt' on `client_cache` for `source` . This lets any listeners know to enable credentials prompt for this `source` .

#### Parameters

client_cache | an EClientCache |
source | an ESource |

Since: 3.16

## Types and Values

### struct EClientCache

    struct EClientCache {
    	GObject parent;
    	EClientCachePrivate *priv;
    };

`EClientCache` is deprecated and should not be used in newly-written code.

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