## EClientSelector

EClientSelector — Tree view of EClient instances

## Synopsis

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

    struct              EClientSelector;
    GtkWidget *         e_client_selector_new               (EClientCache *client_cache,
                                                             const gchar *extension_name);
    EClientCache *      e_client_selector_ref_client_cache  (EClientSelector *selector);
    EClient *           e_client_selector_get_client_sync   (EClientSelector *selector,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_client_selector_get_client        (EClientSelector *selector,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    EClient *           e_client_selector_get_client_finish (EClientSelector *selector,
                                                             GAsyncResult *result,
                                                             GError **error);
    EClient *           e_client_selector_ref_cached_client (EClientSelector *selector,
                                                             ESource *source);
    EClient *           e_client_selector_ref_cached_client_by_iter
                                                            (EClientSelector *selector,
                                                             GtkTreeIter *iter);
    gboolean            e_client_selector_is_backend_dead   (EClientSelector *selector,
                                                             ESource *source);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkTreeView
                               +----ESourceSelector
                                     +----EClientSelector

## Implemented Interfaces

EClientSelector implements AtkImplementorIface, GtkBuildable and GtkScrollable.

## Properties

      "client-cache"             EClientCache*         : Read / Write / Construct Only

## Description

EClientSelector extends the functionality of ESourceSelector by utilizing an EClientCache to display status information about the backends associated with the displayed data sources.

## Details

### struct EClientSelector

    struct EClientSelector;

### e_client_selector_new ()

    GtkWidget *         e_client_selector_new               (EClientCache *client_cache,
                                                             const gchar *extension_name);

Displays a list of sources having an extension named `extension_name`, along with status information about the backends associated with them. The sources are grouped by backend or groupware account, which are described by the parent source.

`client_cache` : | an EClientCache
`extension_name` : | the name of an ESource extension
Returns : | a new EClientSelector

### e_client_selector_ref_client_cache ()

    EClientCache *      e_client_selector_ref_client_cache  (EClientSelector *selector);

Returns the EClientCache passed to `e_client_selector_new()`.

The returned EClientCache is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`selector` : | an EClientSelector
Returns : | an EClientCache

### e_client_selector_get_client_sync ()

    EClient *           e_client_selector_get_client_sync   (EClientSelector *selector,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);

Obtains a shared EClient instance for `source`, or else creates a new EClient instance to be shared.

The "extension-name" property determines the type of EClient to obtain. See `e_client_cache_get_client_sync()` for a list of valid extension names.

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

`selector` : | an ESourceSelector
`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | an EClient, or `NULL`

### e_client_selector_get_client ()

    void                e_client_selector_get_client        (EClientSelector *selector,
                                                             ESource *source,
                                                             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" property determines the type of EClient to obtain. See `e_client_cache_get_client_sync()` for a list of valid extension names.

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_selector_get_client_finish()` to get the result of the operation.

`selector` : | an ESourceSelector
`source` : | an ESource
`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_selector_get_client_finish ()

    EClient *           e_client_selector_get_client_finish (EClientSelector *selector,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_client_selector_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`.

`selector` : | an EClientSelector
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | an EClient, or `NULL`

### e_client_selector_ref_cached_client ()

    EClient *           e_client_selector_ref_cached_client (EClientSelector *selector,
                                                             ESource *source);

Returns a shared EClient instance for `source` and the value of "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.

The returned EClient is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`selector` : | an EClientSelector
`source` : | an ESource
Returns : | an EClient, or `NULL`

### e_client_selector_ref_cached_client_by_iter ()

    EClient *           e_client_selector_ref_cached_client_by_iter
                                                            (EClientSelector *selector,
                                                             GtkTreeIter *iter);

Returns a shared EClient instance for the ESource in the tree model row pointed to by `iter` and the value of "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.

The returned EClient is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

`selector` : | an EClientSelector
`iter` : | a GtkTreeIter
Returns : | an EClient, or `NULL`

### e_client_selector_is_backend_dead ()

    gboolean            e_client_selector_is_backend_dead   (EClientSelector *selector,
                                                             ESource *source);

Returns `TRUE` if an EClient instance for `source` and the value of "extension-name" was recently discarded after having emitted a "backend-died" signal, and a replacement EClient instance has not yet been created.

`selector` : | an EClientSelector
`source` : | an ESource
Returns : | whether the backend for `source` died

## Property Details

### The `"client-cache"` property

      "client-cache"             EClientCache*         : Read / Write / Construct Only

Cache of shared EClient instances.