EClientCache: Evolution Utilities Reference Manual

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

## Properties

ESourceRegistry * | registry | Read / Write / Construct Only

## Signals

void | allow-auth-prompt | Run First
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,
                                    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 an “source-type” of E_CAL_CLIENT_SOURCE_TYPE_EVENTS.

E_SOURCE_EXTENSION_MEMO_LIST will obtain an ECalClient with an “source-type” of E_CAL_CLIENT_SOURCE_TYPE_MEMOS.

E_SOURCE_EXTENSION_TASK_LIST will obtain an ECalClient with an “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);

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

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

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;

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.

Owner: EClientCache

Flags: Read / Write / Construct Only

## Signal Details

### The `“allow-auth-prompt”` signal

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

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

#### Parameters

client_cache | an EClientCache, which sent the signal |
source | an ESource |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 3.16

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

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

Rebroadcasts an “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 an “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