## EClient Utilities

EClient Utilities

## Synopsis

    enum                EClientSourceType;
    gboolean            (*EClientUtilsAuthenticateHandler)  (EClient *client,
                                                             ECredentials *credentials,
                                                             gpointer user_data);
    EClient *	          e_client_utils_new                  (ESource *source,
                                                             EClientSourceType source_type,
                                                             GError **error);
    EClient *	          e_client_utils_new_from_uri         (const gchar *uri,
                                                             EClientSourceType source_type,
                                                             GError **error);
    EClient *	          e_client_utils_new_system           (EClientSourceType source_type,
                                                             GError **error);
    EClient *	          e_client_utils_new_default          (EClientSourceType source_type,
                                                             GError **error);
    gboolean            e_client_utils_set_default          (EClient *client,
                                                             EClientSourceType source_type,
                                                             GError **error);
    gboolean            e_client_utils_set_default_source   (ESource *source,
                                                             EClientSourceType source_type,
                                                             GError **error);
    gboolean            e_client_utils_get_sources          (ESourceList **sources,
                                                             EClientSourceType source_type,
                                                             GError **error);
    void                e_client_utils_open_new             (ESource *source,
                                                             EClientSourceType source_type,
                                                             gboolean only_if_exists,
                                                             GCancellable *cancellable,
                                                             EClientUtilsAuthenticateHandler auth_handler,
                                                             gpointer auth_handler_user_data,
                                                             GAsyncReadyCallback async_cb,
                                                             gpointer async_cb_user_data);
    gboolean            e_client_utils_open_new_finish      (ESource *source,
                                                             GAsyncResult *result,
                                                             EClient **client,
                                                             GError **error);
    gboolean            e_client_utils_authenticate_handler (EClient *client,
                                                             ECredentials *credentials,
                                                             gpointer gtk_window_parent);
    void                e_client_utils_forget_password      (EClient *client);
    gboolean            e_credentials_authenticate_helper   (ECredentials *credentials,
                                                             GtkWindow *parent,
                                                             gboolean *remember_password);
    void                e_credentials_forget_password       (const ECredentials *credentials);

## Description

## Details

### enum EClientSourceType

    typedef enum {
    	E_CLIENT_SOURCE_TYPE_CONTACTS,
    	E_CLIENT_SOURCE_TYPE_EVENTS,
    	E_CLIENT_SOURCE_TYPE_MEMOS,
    	E_CLIENT_SOURCE_TYPE_TASKS,
    	E_CLIENT_SOURCE_TYPE_LAST
    } EClientSourceType;

### EClientUtilsAuthenticateHandler ()

    gboolean            (*EClientUtilsAuthenticateHandler)  (EClient *client,
                                                             ECredentials *credentials,
                                                             gpointer user_data);

### e_client_utils_new ()

    EClient *	          e_client_utils_new                  (ESource *source,
                                                             EClientSourceType source_type,
                                                             GError **error);

Proxy function for `e_book_client_utils_new()` and `e_cal_client_utils_new()`.

### e_client_utils_new_from_uri ()

    EClient *	          e_client_utils_new_from_uri         (const gchar *uri,
                                                             EClientSourceType source_type,
                                                             GError **error);

Proxy function for `e_book_client_utils_new_from_uri()` and `e_cal_client_utils_new_from_uri()`.

### e_client_utils_new_system ()

    EClient *	          e_client_utils_new_system           (EClientSourceType source_type,
                                                             GError **error);

Proxy function for `e_book_client_utils_new_system()` and `e_cal_client_utils_new_system()`.

### e_client_utils_new_default ()

    EClient *	          e_client_utils_new_default          (EClientSourceType source_type,
                                                             GError **error);

Proxy function for `e_book_client_utils_new_default()` and `e_cal_client_utils_new_default()`.

### e_client_utils_set_default ()

    gboolean            e_client_utils_set_default          (EClient *client,
                                                             EClientSourceType source_type,
                                                             GError **error);

Proxy function for `e_book_client_utils_set_default()` and `e_book_client_utils_set_default()`.

### e_client_utils_set_default_source ()

    gboolean            e_client_utils_set_default_source   (ESource *source,
                                                             EClientSourceType source_type,
                                                             GError **error);

Proxy function for `e_book_client_utils_set_default_source()` and `e_cal_client_utils_set_default_source()`.

### e_client_utils_get_sources ()

    gboolean            e_client_utils_get_sources          (ESourceList **sources,
                                                             EClientSourceType source_type,
                                                             GError **error);

Proxy function for `e_book_client_utils_get_sources()` and `e_cal_client_utils_get_sources()`.

### e_client_utils_open_new ()

    void                e_client_utils_open_new             (ESource *source,
                                                             EClientSourceType source_type,
                                                             gboolean only_if_exists,
                                                             GCancellable *cancellable,
                                                             EClientUtilsAuthenticateHandler auth_handler,
                                                             gpointer auth_handler_user_data,
                                                             GAsyncReadyCallback async_cb,
                                                             gpointer async_cb_user_data);

Begins asynchronous opening of a new EClient corresponding to the `source` of type `source_type`. The resulting EClient is fully opened and authenticated client, ready to be used. The opened client has also fetched capabilities. This call is finished by `e_client_utils_open_new_finish()` from the `async_cb`.

Note: the `auth_handler`, and its `auth_handler_user_data`, should be valid through whole live of returned EClient.

`source` : | an ESource to be opened
`source_type` : | an EClientSourceType of the `source`
`only_if_exists` : | if `TRUE`, fail if this client doesn't already exist, otherwise create it first
`cancellable` : | a GCancellable; can be `NULL`
`auth_handler` : | authentication handler, to be used; the `e_client_utils_authenticate_handler()` is usually sufficient
`auth_handler_user_data` : | user data for `auth_handler` function
`async_cb` : | callback to call when a result is ready
`async_cb_user_data` : | user data for the `async_cb`

Since 3.2

### e_client_utils_open_new_finish ()

    gboolean            e_client_utils_open_new_finish      (ESource *source,
                                                             GAsyncResult *result,
                                                             EClient **client,
                                                             GError **error);

Finishes previous call of `e_client_utils_open_new()` and sets `client` to a fully opened and authenticated EClient. This `client`, if not NULL, should be freed with `g_object_unref()`.

`source` : | an ESource on which the `e_client_utils_open_new()` was invoked
`result` : | a GAsyncResult
`client` : | Return value for an EClient. [out]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_utils_authenticate_handler ()

    gboolean            e_client_utils_authenticate_handler (EClient *client,
                                                             ECredentials *credentials,
                                                             gpointer gtk_window_parent);

### e_client_utils_forget_password ()

    void                e_client_utils_forget_password      (EClient *client);

Forgets stored password for the given `client`.

`client` : | An EClient

Since 3.2

### e_credentials_authenticate_helper ()

    gboolean            e_credentials_authenticate_helper   (ECredentials *credentials,
                                                             GtkWindow *parent,
                                                             gboolean *remember_password);

### e_credentials_forget_password ()

    void                e_credentials_forget_password       (const ECredentials *credentials);

Forgets stored password for given `credentials`, which should contain E_CREDENTIALS_KEY_PROMPT_KEY.

`credentials` : | an ECredentials

Since 3.2