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

Since 3.2

### EClientUtilsAuthenticateHandler ()

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

Since 3.2

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

Since 3.2

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

Since 3.2

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

Since 3.2

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

Since 3.2

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

Since 3.2

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

Since 3.2

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

Since 3.2

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

This function is suitable as a handler for EClient::authenticate signal. It takes care of all the password prompt and such and returns TRUE if credentials (password) were provided. Thus just connect it to that signal and it'll take care of everything else.

gtk_window_parent is user_data passed into the callback. It can be a pointer to GtkWindow, used as a parent for a pasword prompt dialog.

Since 3.2

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

Asks for a password based on the provided credentials information. Credentials should have set following keys: E_CREDENTIALS_KEY_USERNAME E_CREDENTIALS_KEY_PROMPT_KEY E_CREDENTIALS_KEY_PROMPT_TEXT all other keys are optional. If also E_CREDENTIALS_KEY_PASSWORD key is provided, then it implies a reprompt.

When this returns TRUE, then the structure contains E_CREDENTIALS_KEY_PASSWORD set as entered by a user.

Since 3.2

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