## 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 ()

## Properties

ESourceRegistry * | registry | Read / Write / Construct Only

## Signals

void | backend-died | Run Last
void | backend-error | Run Last
void | client-connected | Run First
void | client-created | Run First
void | client-notify | No Hooks

## Types and Values

struct | EClientCache

## Object Hierarchy

        GObject
        ╰── EClientCache

## Implemented Interfaces

EClientCache implements EExtensible.

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

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

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

#### Parameters

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.

#### Parameters

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

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

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

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

## Types and Values

### struct EClientCache

    struct EClientCache;

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

## Property Details

### The `“registry”` property

      “registry”                 ESourceRegistry *

The ESourceRegistry manages ESource instances.

Flags: Read / Write / Construct Only

## Signal Details

### The `“backend-died”` signal

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

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.

#### Parameters

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

Flags: Run Last

### The `“backend-error”` signal

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

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.

#### Parameters

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

Flags: Run Last

### The `“client-connected”` signal

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

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.

#### Parameters

client_cache | the EClientCache that received the signal |
client | the newly-created EClient |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“client-created”` signal

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

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.

#### Parameters

client_cache | the EClientCache that received the signal |
client | the newly-created EClient |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“client-notify”` signal

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

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.

#### Parameters

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

Flags: No Hooks