EClientSelector: Evolution Utilities Reference Manual

## EClientSelector EClientSelector — Tree view of EClient instances |

## Functions

GtkWidget * | e_client_selector_new ()
EClientCache * | e_client_selector_ref_client_cache ()
EClient * | e_client_selector_get_client_sync ()
void | e_client_selector_get_client ()
EClient * | e_client_selector_get_client_finish ()
EClient * | e_client_selector_ref_cached_client ()
EClient * | e_client_selector_ref_cached_client_by_iter ()
gboolean | e_client_selector_is_backend_dead ()

## Properties

EClientCache * | client-cache | Read / Write / Construct Only

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkTreeView
                        ╰── ESourceSelector
                            ╰── EClientSelector

## Includes

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

## Description

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

## Functions

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

#### Parameters

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.

#### Parameters

selector | an EClientSelector |

#### Returns

an EClientCache

### e_client_selector_get_client_sync ()

    EClient *
    e_client_selector_get_client_sync (EClientSelector *selector,
                                       ESource *source,
                                       gboolean call_allow_auth_prompt,
                                       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” 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.

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.

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

selector | an ESourceSelector |
source | an ESource |
call_allow_auth_prompt | whether call allow-auth-prompt on the source first |
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_selector_get_client ()

    void
    e_client_selector_get_client (EClientSelector *selector,
                                  ESource *source,
                                  gboolean call_allow_auth_prompt,
                                  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” 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.

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.

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.

#### Parameters

selector | an ESourceSelector |
source | an ESource |
call_allow_auth_prompt | whether call allow-auth-prompt on the source first |
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_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`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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 an “backend-died” signal, and a replacement EClient instance has not yet been created.

#### Parameters

selector | an EClientSelector |
source | an ESource |

#### Returns

whether the backend for `source` died

## Property Details

### The `“client-cache”` property

      “client-cache”             EClientCache *

Cache of shared EClient instances.

Owner: EClientSelector

Flags: Read / Write / Construct Only