## EClient

EClient — Base class for client handles

## Synopsis

    #include <libedataserver/libedataserver.h>

    #define             CLIENT_BACKEND_PROPERTY_ONLINE
    #define             CLIENT_BACKEND_PROPERTY_READONLY
    #define             CLIENT_BACKEND_PROPERTY_CACHE_DIR
    #define             CLIENT_BACKEND_PROPERTY_CAPABILITIES
    #define             CLIENT_BACKEND_PROPERTY_REVISION
    #define             E_CLIENT_ERROR
    GQuark              e_client_error_quark                (void);
    enum                EClientError;
    const gchar *       e_client_error_to_string            (EClientError code);
    struct              EClient;
    struct              EClientClass;
    ESource *           e_client_get_source                 (EClient *client);
    const GSList *      e_client_get_capabilities           (EClient *client);
    GMainContext *      e_client_ref_main_context           (EClient *client);
    gboolean            e_client_check_capability           (EClient *client,
                                                             const gchar *capability);
    gboolean            e_client_check_refresh_supported    (EClient *client);
    gboolean            e_client_is_readonly                (EClient *client);
    gboolean            e_client_is_online                  (EClient *client);
    void                e_client_get_backend_property       (EClient *client,
                                                             const gchar *prop_name,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_client_get_backend_property_finish
                                                            (EClient *client,
                                                             GAsyncResult *result,
                                                             gchar **prop_value,
                                                             GError **error);
    gboolean            e_client_get_backend_property_sync  (EClient *client,
                                                             const gchar *prop_name,
                                                             gchar **prop_value,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_client_refresh                    (EClient *client,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_client_refresh_finish             (EClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_client_refresh_sync               (EClient *client,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GSList *            e_client_util_parse_comma_strings   (const gchar *strings);
    #define             CLIENT_BACKEND_PROPERTY_OPENED
    #define             CLIENT_BACKEND_PROPERTY_OPENING
    GError *            e_client_error_create               (EClientError code,
                                                             const gchar *custom_msg);
    gboolean            e_client_is_opened                  (EClient *client);
    void                e_client_cancel_all                 (EClient *client);
    void                e_client_unwrap_dbus_error          (EClient *client,
                                                             GError *dbus_error,
                                                             GError **out_error);
    void                e_client_retrieve_capabilities      (EClient *client,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_client_retrieve_capabilities_finish
                                                            (EClient *client,
                                                             GAsyncResult *result,
                                                             gchar **capabilities,
                                                             GError **error);
    gboolean            e_client_retrieve_capabilities_sync (EClient *client,
                                                             gchar **capabilities,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_client_set_backend_property       (EClient *client,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_client_set_backend_property_finish
                                                            (EClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_client_set_backend_property_sync  (EClient *client,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_client_open                       (EClient *client,
                                                             gboolean only_if_exists,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_client_open_finish                (EClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_client_open_sync                  (EClient *client,
                                                             gboolean only_if_exists,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_client_remove                     (EClient *client,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_client_remove_finish              (EClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_client_remove_sync                (EClient *client,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gchar **            e_client_util_slist_to_strv         (const GSList *strings);
    GSList *            e_client_util_strv_to_slist         (const gchar * const *strv);
    GSList *            e_client_util_copy_string_slist     (GSList *copy_to,
                                                             const GSList *strings);
    GSList *            e_client_util_copy_object_slist     (GSList *copy_to,
                                                             const GSList *objects);
    void                e_client_util_free_string_slist     (GSList *strings);
    void                e_client_util_free_object_slist     (GSList *objects);
    struct              EClientErrorsList;
    gboolean            e_client_util_unwrap_dbus_error     (GError *dbus_error,
                                                             GError **client_error,
                                                             const EClientErrorsList *known_errors,
                                                             guint known_errors_count,
                                                             GQuark known_errors_domain,
                                                             gboolean fail_when_none_matched);

## Description

This class provides some base functionality for clients such as EBookClient and ECalClient.

## Details

### CLIENT_BACKEND_PROPERTY_ONLINE

    #define CLIENT_BACKEND_PROPERTY_ONLINE			"online"

The "online" property is "TRUE" when the client is fully opened and online, "FALSE" at all other times. See also `e_client_is_online()`.

Since 3.2

### CLIENT_BACKEND_PROPERTY_READONLY

    #define CLIENT_BACKEND_PROPERTY_READONLY		"readonly"

The "online" property is "TRUE" if the backend has only read access to its data, "FALSE" if the backend can modify its data. See also `e_client_is_readonly()`.

Since 3.2

### CLIENT_BACKEND_PROPERTY_CACHE_DIR

    #define CLIENT_BACKEND_PROPERTY_CACHE_DIR		"cache-dir"

The "cache-dir" property indicates the backend's local directory for cached data.

Since 3.2

### CLIENT_BACKEND_PROPERTY_CAPABILITIES

    #define             CLIENT_BACKEND_PROPERTY_CAPABILITIES

FIXME: Document me.

Since 3.2

### CLIENT_BACKEND_PROPERTY_REVISION

    #define CLIENT_BACKEND_PROPERTY_REVISION		"revision"

The current overall revision string, this can be used as a quick check to see if data has changed at all since the last time the revision was observed.

Since 3.4

### E_CLIENT_ERROR

    #define E_CLIENT_ERROR		e_client_error_quark ()

Error domain for EClient operations. Errors in this domain will be from the EClientError enumeration. See GError for more information on error domains.

Since 3.2

### e_client_error_quark ()

    GQuark              e_client_error_quark                (void);

### enum EClientError

    typedef enum {
    	E_CLIENT_ERROR_INVALID_ARG,
    	E_CLIENT_ERROR_BUSY,
    	E_CLIENT_ERROR_SOURCE_NOT_LOADED,
    	E_CLIENT_ERROR_SOURCE_ALREADY_LOADED,
    	E_CLIENT_ERROR_AUTHENTICATION_FAILED,
    	E_CLIENT_ERROR_AUTHENTICATION_REQUIRED,
    	E_CLIENT_ERROR_REPOSITORY_OFFLINE,
    	E_CLIENT_ERROR_OFFLINE_UNAVAILABLE,
    	E_CLIENT_ERROR_PERMISSION_DENIED,
    	E_CLIENT_ERROR_CANCELLED,
    	E_CLIENT_ERROR_COULD_NOT_CANCEL,
    	E_CLIENT_ERROR_NOT_SUPPORTED,
    	E_CLIENT_ERROR_TLS_NOT_AVAILABLE,
    	E_CLIENT_ERROR_UNSUPPORTED_AUTHENTICATION_METHOD,
    	E_CLIENT_ERROR_SEARCH_SIZE_LIMIT_EXCEEDED,
    	E_CLIENT_ERROR_SEARCH_TIME_LIMIT_EXCEEDED,
    	E_CLIENT_ERROR_INVALID_QUERY,
    	E_CLIENT_ERROR_QUERY_REFUSED,
    	E_CLIENT_ERROR_DBUS_ERROR,
    	E_CLIENT_ERROR_OTHER_ERROR,
    	E_CLIENT_ERROR_NOT_OPENED,
    	E_CLIENT_ERROR_OUT_OF_SYNC
    } EClientError;

FIXME Document each code.

Error codes for EClient operations.

`E_CLIENT_ERROR_INVALID_ARG` |
`E_CLIENT_ERROR_BUSY` |
`E_CLIENT_ERROR_SOURCE_NOT_LOADED` |
`E_CLIENT_ERROR_SOURCE_ALREADY_LOADED` |
`E_CLIENT_ERROR_AUTHENTICATION_FAILED` |
`E_CLIENT_ERROR_AUTHENTICATION_REQUIRED` |
`E_CLIENT_ERROR_REPOSITORY_OFFLINE` |
`E_CLIENT_ERROR_OFFLINE_UNAVAILABLE` |
`E_CLIENT_ERROR_PERMISSION_DENIED` |
`E_CLIENT_ERROR_CANCELLED` |
`E_CLIENT_ERROR_COULD_NOT_CANCEL` |
`E_CLIENT_ERROR_NOT_SUPPORTED` |
`E_CLIENT_ERROR_TLS_NOT_AVAILABLE` |
`E_CLIENT_ERROR_UNSUPPORTED_AUTHENTICATION_METHOD` |
`E_CLIENT_ERROR_SEARCH_SIZE_LIMIT_EXCEEDED` |
`E_CLIENT_ERROR_SEARCH_TIME_LIMIT_EXCEEDED` |
`E_CLIENT_ERROR_INVALID_QUERY` |
`E_CLIENT_ERROR_QUERY_REFUSED` |
`E_CLIENT_ERROR_DBUS_ERROR` |
`E_CLIENT_ERROR_OTHER_ERROR` |
`E_CLIENT_ERROR_NOT_OPENED` |
`E_CLIENT_ERROR_OUT_OF_SYNC` |

Since 3.2

### e_client_error_to_string ()

    const gchar *       e_client_error_to_string            (EClientError code);

FIXME: Document me.

Since 3.2

### struct EClient

    struct EClient {
    	GObject parent;
    	EClientPrivate *priv;
    };

Contains only private data that should be read and manipulated using the functions below.

Since 3.2

### struct EClientClass

    struct EClientClass {
    	GObjectClass parent;

    	/* This method is deprecated. */
    	GDBusProxy * (*get_dbus_proxy) (EClient *client);

    	/* This method is deprecated. */
    	void		(*unwrap_dbus_error) (EClient *client,
    						 GError *dbus_error,
    						 GError **out_error);

    	/* This method is deprecated. */
    	void		(*retrieve_capabilities)
    						(EClient *client,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	gboolean (*retrieve_capabilities_finish)
    						(EClient *client,
    						 GAsyncResult *result,
    						 gchar **capabilities,
    						 GError **error);
    	gboolean (*retrieve_capabilities_sync)
    						(EClient *client,
    						 gchar **capabilities,
    						 GCancellable *cancellable,
    						 GError **error);

    	void		(*get_backend_property) (EClient *client,
    						 const gchar *prop_name,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	gboolean (*get_backend_property_finish)
    						(EClient *client,
    						 GAsyncResult *result,
    						 gchar **prop_value,
    						 GError **error);
    	gboolean (*get_backend_property_sync)
    						(EClient *client,
    						 const gchar *prop_name,
    						 gchar **prop_value,
    						 GCancellable *cancellable,
    						 GError **error);

    	/* This method is deprecated. */
    	void		(*set_backend_property) (EClient *client,
    						 const gchar *prop_name,
    						 const gchar *prop_value,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	gboolean (*set_backend_property_finish)
    						(EClient *client,
    						 GAsyncResult *result,
    						 GError **error);
    	gboolean (*set_backend_property_sync)
    						(EClient *client,
    						 const gchar *prop_name,
    						 const gchar *prop_value,
    						 GCancellable *cancellable,
    						 GError **error);

    	void		(*open)			(EClient *client,
    						 gboolean only_if_exists,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	gboolean (*open_finish)		(EClient *client,
    						 GAsyncResult *result,
    						 GError **error);
    	gboolean (*open_sync)		(EClient *client,
    						 gboolean only_if_exists,
    						 GCancellable *cancellable,
    						 GError **error);

    	void		(*remove)		(EClient *client,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	gboolean (*remove_finish) (EClient *client,
    						 GAsyncResult *result,
    						 GError **error);
    	gboolean (*remove_sync)		(EClient *client,
    						 GCancellable *cancellable,
    						 GError **error);

    	void		(*refresh)		(EClient *client,
    						 GCancellable *cancellable,
    						 GAsyncReadyCallback callback,
    						 gpointer user_data);
    	gboolean (*refresh_finish) (EClient *client,
    						 GAsyncResult *result,
    						 GError **error);
    	gboolean (*refresh_sync)		(EClient *client,
    						 GCancellable *cancellable,
    						 GError **error);

    	void		(*opened)		(EClient *client,
    						 const GError *error);
    	void		(*backend_error) (EClient *client,
    						 const gchar *error_msg);
    	void		(*backend_died)		(EClient *client);
    	void		(*backend_property_changed)
    						(EClient *client,
    						 const gchar *prop_name,
    						 const gchar *prop_value);
    };

### e_client_get_source ()

    ESource *           e_client_get_source                 (EClient *client);

Get the ESource that this client has assigned.

`client` : | an EClient
Returns : | The source. [transfer none]

Since 3.2

### e_client_get_capabilities ()

    const GSList *      e_client_get_capabilities           (EClient *client);

Get list of strings with capabilities advertised by a backend. This list, together with inner strings, is owned by the `client`. To check for individual capabilities use `e_client_check_capability()`.

`client` : | an EClient
Returns : | GSList of const strings of capabilities. [element-type utf8][transfer none]

Since 3.2

### e_client_ref_main_context ()

    GMainContext *      e_client_ref_main_context           (EClient *client);

Returns the GMainContext on which event sources for `client` are to be attached.

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

`client` : | an EClient
Returns : | a GMainContext. [transfer full]

Since 3.8

### e_client_check_capability ()

    gboolean            e_client_check_capability           (EClient *client,
                                                             const gchar *capability);

Check if backend supports particular capability. To get all capabilities use `e_client_get_capabilities()`.

`client` : | an EClient
`capability` : | a capability
Returns : | GSList of const strings of capabilities

Since 3.2

### e_client_check_refresh_supported ()

    gboolean            e_client_check_refresh_supported    (EClient *client);

Checks whether a client supports explicit refreshing (see `e_client_refresh()`).

`client` : | A client.
Returns : | TRUE if the client supports refreshing, FALSE otherwise.

Since 3.2

### e_client_is_readonly ()

    gboolean            e_client_is_readonly                (EClient *client);

Check if this `client` is read-only.

`client` : | an EClient
Returns : | `TRUE` if this `client` is read-only, otherwise `FALSE`.

Since 3.2

### e_client_is_online ()

    gboolean            e_client_is_online                  (EClient *client);

Check if this `client` is connected.

`client` : | an EClient
Returns : | `TRUE` if this `client` is connected, otherwise `FALSE`.

Since 3.2

### e_client_get_backend_property ()

    void                e_client_get_backend_property       (EClient *client,
                                                             const gchar *prop_name,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Queries `client`'s backend for a property of name `prop_name`. The call is finished by `e_client_get_backend_property_finish()` from the `callback`.

`client` : | an EClient
`prop_name` : | property name, whose value to retrieve; cannot be `NULL`
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_client_get_backend_property_finish ()

    gboolean            e_client_get_backend_property_finish
                                                            (EClient *client,
                                                             GAsyncResult *result,
                                                             gchar **prop_value,
                                                             GError **error);

Finishes previous call of `e_client_get_backend_property()`.

`client` : | an EClient
`result` : | a GAsyncResult
`prop_value` : | Retrieved backend property value; cannot be `NULL`. [out]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_get_backend_property_sync ()

    gboolean            e_client_get_backend_property_sync  (EClient *client,
                                                             const gchar *prop_name,
                                                             gchar **prop_value,
                                                             GCancellable *cancellable,
                                                             GError **error);

Queries `client`'s backend for a property of name `prop_name`.

`client` : | an EClient
`prop_name` : | property name, whose value to retrieve; cannot be `NULL`
`prop_value` : | Retrieved backend property value; cannot be `NULL`. [out]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_refresh ()

    void                e_client_refresh                    (EClient *client,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Initiates refresh on the `client`. Finishing the method doesn't mean that the refresh is done, backend only notifies whether it started refreshing or not. Use `e_client_check_refresh_supported()` to check whether the backend supports this method. The call is finished by `e_client_refresh_finish()` from the `callback`.

`client` : | an EClient
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_client_refresh_finish ()

    gboolean            e_client_refresh_finish             (EClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes previous call of `e_client_refresh()`.

`client` : | an EClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_refresh_sync ()

    gboolean            e_client_refresh_sync               (EClient *client,
                                                             GCancellable *cancellable,
                                                             GError **error);

Initiates refresh on the `client`. Finishing the method doesn't mean that the refresh is done, backend only notifies whether it started refreshing or not. Use `e_client_check_refresh_supported()` to check whether the backend supports this method.

`client` : | an EClient
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_util_parse_comma_strings ()

    GSList *            e_client_util_parse_comma_strings   (const gchar *strings);

Parses comma-separated list of values into GSList.

`strings` : | string of comma-separated values
Returns : | Newly allocated GSList of newly allocated strings corresponding to values parsed from `strings`. Free the returned pointer with `e_client_util_free_string_slist()`. [transfer full][element-type utf8]

Since 3.2

### CLIENT_BACKEND_PROPERTY_OPENED

    #define CLIENT_BACKEND_PROPERTY_OPENED			"opened"

### Warning

`CLIENT_BACKEND_PROPERTY_OPENED` has been deprecated since version 3.8 and should not be used in newly-written code. Clients don't need to care if they're fully opened anymore. This property will always return `TRUE`.

The "opened" property is "TRUE" when the client is fully opened, "FALSE" at all other times.

Since 3.2

### CLIENT_BACKEND_PROPERTY_OPENING

    #define CLIENT_BACKEND_PROPERTY_OPENING			"opening"

### Warning

`CLIENT_BACKEND_PROPERTY_OPENING` has been deprecated since version 3.8 and should not be used in newly-written code. Clients don't need to care if they're fully opened anymore. This property will always return `FALSE`.

The "opening" property is "TRUE" when the client is in the process of opening, "FALSE" at all other times.

Since 3.2

### e_client_error_create ()

    GError *            e_client_error_create               (EClientError code,
                                                             const gchar *custom_msg);

### Warning

`e_client_error_create` has been deprecated since version 3.8 and should not be used in newly-written code. Just use the GError API directly.

`code` : | an EClientError code to create
`custom_msg` : | custom message to use for the error; can be `NULL`
Returns : | a new GError containing an E_CLIENT_ERROR of the given `code`. If the `custom_msg` is NULL, then the error message is the one returned from `e_client_error_to_string()` for the `code`, otherwise the given message is used. Returned pointer should be freed with `g_error_free()`.

Since 3.2

### e_client_is_opened ()

    gboolean            e_client_is_opened                  (EClient *client);

### Warning

`e_client_is_opened` has been deprecated since version 3.8 and should not be used in newly-written code. Clients don't need to care if they're fully opened anymore. This function always returns `TRUE`.

Check if this `client` is fully opened. This includes everything from `e_client_open()` call up to the authentication, if required by a backend. Client cannot do any other operation during the opening phase except of authenticate or cancel it. Every other operation results in an `E_CLIENT_ERROR_BUSY` error.

`client` : | an EClient
Returns : | always `TRUE`

Since 3.2.

### e_client_cancel_all ()

    void                e_client_cancel_all                 (EClient *client);

### Warning

`e_client_cancel_all` has been deprecated since version 3.8 and should not be used in newly-written code. The function no longer does anything.

Cancels all pending operations started on `client`.

`client` : | an EClient

Since 3.2

### e_client_unwrap_dbus_error ()

    void                e_client_unwrap_dbus_error          (EClient *client,
                                                             GError *dbus_error,
                                                             GError **out_error);

### Warning

`e_client_unwrap_dbus_error` has been deprecated since version 3.8 and should not be used in newly-written code. Use `g_dbus_error_strip_remote_error()` instead.

Unwraps D-Bus error to local error. `dbus_error` is automatically freed. `dbus_erorr` and `out_error` can point to the same variable.

`client` : | an EClient
`dbus_error` : | a GError returned bu D-Bus
`out_error` : | a GError variable where to store the result

Since 3.2

### e_client_retrieve_capabilities ()

    void                e_client_retrieve_capabilities      (EClient *client,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### Warning

`e_client_retrieve_capabilities` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_client_get_capabilities()` instead.

Initiates retrieval of capabilities on the `client`. This is usually required only once, after the `client` is opened. The returned value is cached and any subsequent call of `e_client_get_capabilities()` and `e_client_check_capability()` is using the cached value. The call is finished by `e_client_retrieve_capabilities_finish()` from the `callback`.

`client` : | an EClient
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_client_retrieve_capabilities_finish ()

    gboolean            e_client_retrieve_capabilities_finish
                                                            (EClient *client,
                                                             GAsyncResult *result,
                                                             gchar **capabilities,
                                                             GError **error);

### Warning

`e_client_retrieve_capabilities_finish` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_client_get_capabilities()` instead.

Finishes previous call of `e_client_retrieve_capabilities()`. Returned value of `capabilities` should be freed with `g_free()`, when no longer needed.

`client` : | an EClient
`result` : | a GAsyncResult
`capabilities` : | Comma-separated list of capabilities of the `client`. [out]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_retrieve_capabilities_sync ()

    gboolean            e_client_retrieve_capabilities_sync (EClient *client,
                                                             gchar **capabilities,
                                                             GCancellable *cancellable,
                                                             GError **error);

### Warning

`e_client_retrieve_capabilities_sync` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_client_get_capabilities()` instead.

Initiates retrieval of capabilities on the `client`. This is usually required only once, after the `client` is opened. The returned value is cached and any subsequent call of `e_client_get_capabilities()` and `e_client_check_capability()` is using the cached value. Returned value of `capabilities` should be freed with `g_free()`, when no longer needed.

`client` : | an EClient
`capabilities` : | Comma-separated list of capabilities of the `client`. [out]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_set_backend_property ()

    void                e_client_set_backend_property       (EClient *client,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### Warning

`e_client_set_backend_property` has been deprecated since version 3.8 and should not be used in newly-written code. Clients cannot set backend properties. Any attempt will fail with an `E_CLIENT_ERROR_NOT_SUPPORTED` error.

Sets `client`'s backend property of name `prop_name` to value `prop_value`. The call is finished by `e_client_set_backend_property_finish()` from the `callback`.

`client` : | an EClient
`prop_name` : | property name, whose value to change; cannot be `NULL`
`prop_value` : | property value, to set; cannot be `NULL`
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_client_set_backend_property_finish ()

    gboolean            e_client_set_backend_property_finish
                                                            (EClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

### Warning

`e_client_set_backend_property_finish` has been deprecated since version 3.8 and should not be used in newly-written code. Clients cannot set backend properties. Any attempt will fail with an `E_CLIENT_ERROR_NOT_SUPPORTED` error.

Finishes previous call of `e_client_set_backend_property()`.

`client` : | an EClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_set_backend_property_sync ()

    gboolean            e_client_set_backend_property_sync  (EClient *client,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value,
                                                             GCancellable *cancellable,
                                                             GError **error);

### Warning

`e_client_set_backend_property_sync` has been deprecated since version 3.8 and should not be used in newly-written code. Clients cannot set backend properties. Any attempt will fail with an `E_CLIENT_ERROR_NOT_SUPPORTED` error.

Sets `client`'s backend property of name `prop_name` to value `prop_value`.

`client` : | an EClient
`prop_name` : | property name, whose value to change; cannot be `NULL`
`prop_value` : | property value, to set; cannot be `NULL`
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_open ()

    void                e_client_open                       (EClient *client,
                                                             gboolean only_if_exists,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### Warning

`e_client_open` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_book_client_connect()` and `e_book_client_connect_finish()` or `e_cal_client_connect()` and `e_cal_client_connect_finish()` instead.

Opens the `client`, making it ready for queries and other operations. The call is finished by `e_client_open_finish()` from the `callback`.

`client` : | an EClient
`only_if_exists` : | if `TRUE`, fail if this book doesn't already exist, otherwise create it first
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_client_open_finish ()

    gboolean            e_client_open_finish                (EClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

### Warning

`e_client_open_finish` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_book_client_connect()` and `e_book_client_connect_finish()` or `e_cal_client_connect()` and `e_cal_client_connect_finish()` instead.

Finishes previous call of `e_client_open()`.

`client` : | an EClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_open_sync ()

    gboolean            e_client_open_sync                  (EClient *client,
                                                             gboolean only_if_exists,
                                                             GCancellable *cancellable,
                                                             GError **error);

### Warning

`e_client_open_sync` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_book_client_connect_sync()` or `e_cal_client_connect_sync()` instead.

Opens the `client`, making it ready for queries and other operations.

`client` : | an EClient
`only_if_exists` : | if `TRUE`, fail if this book doesn't already exist, otherwise create it first
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_remove ()

    void                e_client_remove                     (EClient *client,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

### Warning

`e_client_remove` has been deprecated since version 3.6 and should not be used in newly-written code. Use `e_source_remove()` instead.

Removes the backing data for this EClient. For example, with the file backend this deletes the database file. You cannot get it back! The call is finished by `e_client_remove_finish()` from the `callback`.

`client` : | an EClient
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_client_remove_finish ()

    gboolean            e_client_remove_finish              (EClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

### Warning

`e_client_remove_finish` has been deprecated since version 3.6 and should not be used in newly-written code. Use `e_source_remove_finish()` instead.

Finishes previous call of `e_client_remove()`.

`client` : | an EClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_remove_sync ()

    gboolean            e_client_remove_sync                (EClient *client,
                                                             GCancellable *cancellable,
                                                             GError **error);

### Warning

`e_client_remove_sync` has been deprecated since version 3.6 and should not be used in newly-written code. Use `e_source_remove_sync()` instead.

Removes the backing data for this EClient. For example, with the file backend this deletes the database file. You cannot get it back!

`client` : | an EClient
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_client_util_slist_to_strv ()

    gchar **            e_client_util_slist_to_strv         (const GSList *strings);

### Warning

`e_client_util_slist_to_strv` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_util_slist_to_strv()` instead.

Convert a list of strings into a `NULL`-terminated array of strings.

`strings` : | a GSList of strings (const gchar *). [element-type utf8]
Returns : | Newly allocated `NULL`-terminated array of strings. The returned pointer should be freed with `g_strfreev()`. Note: Paired function for this is `e_client_util_strv_to_slist()`. [transfer full]

Since 3.2

### e_client_util_strv_to_slist ()

    GSList *            e_client_util_strv_to_slist         (const gchar * const *strv);

### Warning

`e_client_util_strv_to_slist` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_util_strv_to_slist()` instead.

Convert a `NULL`-terminated array of strings to a list of strings.

`strv` : | a `NULL`-terminated array of strings (const gchar *)
Returns : | Newly allocated GSList of newly allocated strings. The returned pointer should be freed with `e_client_util_free_string_slist()`. Note: Paired function for this is `e_client_util_slist_to_strv()`. [transfer full][element-type utf8]

Since 3.2

### e_client_util_copy_string_slist ()

    GSList *            e_client_util_copy_string_slist     (GSList *copy_to,
                                                             const GSList *strings);

### Warning

`e_client_util_copy_string_slist` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_util_copy_string_slist()` instead.

Copies the GSList of strings to the end of `copy_to`.

`copy_to` : | Where to copy; may be `NULL`. [element-type utf8][allow-none]
`strings` : | GSList of strings to be copied. [element-type utf8]
Returns : | New head of `copy_to`. The returned pointer can be freed with `e_client_util_free_string_slist()`. [transfer full][element-type utf8]

Since 3.2

### e_client_util_copy_object_slist ()

    GSList *            e_client_util_copy_object_slist     (GSList *copy_to,
                                                             const GSList *objects);

### Warning

`e_client_util_copy_object_slist` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_util_copy_object_slist()` instead.

Copies a GSList of GObjects to the end of `copy_to`.

`copy_to` : | Where to copy; may be `NULL`. [element-type GObject][allow-none]
`objects` : | GSList of GObjects to be copied. [element-type GObject]
Returns : | New head of `copy_to`. The returned pointer can be freed with `e_client_util_free_object_slist()`. [transfer full][element-type GObject]

Since 3.2

### e_client_util_free_string_slist ()

    void                e_client_util_free_string_slist     (GSList *strings);

### Warning

`e_client_util_free_string_slist` has been deprecated since version 3.8 and should not be used in newly-written code. Use `g_slist_free_full()` instead.

Frees memory previously allocated by `e_client_util_strv_to_slist()`.

`strings` : | a GSList of strings (gchar *). [element-type utf8]

Since 3.2

### e_client_util_free_object_slist ()

    void                e_client_util_free_object_slist     (GSList *objects);

### Warning

`e_client_util_free_object_slist` has been deprecated since version 3.8 and should not be used in newly-written code. Use `g_slist_free_full()` instead.

Calls `g_object_unref()` on each member of `objects` and then frees `objects` itself.

`objects` : | a GSList of GObjects. [element-type GObject]

Since 3.2

### struct EClientErrorsList

    struct EClientErrorsList {
    	const gchar *name;
    	gint err_code;
    };

### Warning

`EClientErrorsList` has been deprecated since version 3.8 and should not be used in newly-written code. This structure is no longer used.

Since 3.2

### e_client_util_unwrap_dbus_error ()

    gboolean            e_client_util_unwrap_dbus_error     (GError *dbus_error,
                                                             GError **client_error,
                                                             const EClientErrorsList *known_errors,
                                                             guint known_errors_count,
                                                             GQuark known_errors_domain,
                                                             gboolean fail_when_none_matched);

### Warning

`e_client_util_unwrap_dbus_error` has been deprecated since version 3.8 and should not be used in newly-written code. This function is no longer used.

The function takes a `dbus_error` and tries to find a match in `known_errors` for it, if it is a G_IO_ERROR, G_IO_ERROR_DBUS_ERROR. If it is anything else then the `dbus_error` is moved to `client_error`.

The `fail_when_none_matched` influences behaviour. If it's `TRUE`, and none of `known_errors` matches, or this is not a G_IO_ERROR_DBUS_ERROR, then `FALSE` is returned and the `client_error` is left without change. Otherwise, the `fail_when_none_matched` is `FALSE`, the error is always processed and will result in E_CLIENT_ERROR, E_CLIENT_ERROR_OTHER_ERROR if none of `known_error` matches.

`dbus_error` : | DBus GError to unwrap
`client_error` : | Resulting GError; can be `NULL`. [out]
`known_errors` : | List of known errors against which try to match
`known_errors_count` : | How many items are stored in `known_errors`
`known_errors_domain` : | Error domain for `known_errors`
`fail_when_none_matched` : | Whether to fail when none of `known_errors` matches
Returns : | Whether was `dbus_error` processed into `client_error`. Note: The `dbus_error` is automatically freed if returned `TRUE`.

Since 3.2