EClientCache

EClientCache — Shared EClient instances

Functions

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