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);
void                e_client_retrieve_properties        (EClient *client,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_client_retrieve_properties_finish (EClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            e_client_retrieve_properties_sync   (EClient *client,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_client_wait_for_connected         (EClient *client,
                                                         guint32 timeout_seconds,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_client_wait_for_connected_finish  (EClient *client,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            e_client_wait_for_connected_sync    (EClient *client,
                                                         guint32 timeout_seconds,
                                                         GCancellable *cancellable,
                                                         GError **error);
GSList *            e_client_util_parse_comma_strings   (const gchar *strings);
gchar *             e_client_dup_bus_name               (EClient *client);
void                e_client_set_bus_name               (EClient *client,
                                                         const gchar *bus_name);
#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;

Error codes for EClient operations.

E_CLIENT_ERROR_INVALID_ARG

Invalid argument was used

E_CLIENT_ERROR_BUSY

The client is busy

E_CLIENT_ERROR_SOURCE_NOT_LOADED

The source is not loaded

E_CLIENT_ERROR_SOURCE_ALREADY_LOADED

The source is already loaded

E_CLIENT_ERROR_AUTHENTICATION_FAILED

Authentication failed

E_CLIENT_ERROR_AUTHENTICATION_REQUIRED

Authentication required

E_CLIENT_ERROR_REPOSITORY_OFFLINE

The repository (client) is offline

E_CLIENT_ERROR_OFFLINE_UNAVAILABLE

The operation is unavailable in offline mode

E_CLIENT_ERROR_PERMISSION_DENIED

Permission denied for the operation

E_CLIENT_ERROR_CANCELLED

The operation was cancelled

E_CLIENT_ERROR_COULD_NOT_CANCEL

The operation cannot be cancelled

E_CLIENT_ERROR_NOT_SUPPORTED

The operation is not supported

E_CLIENT_ERROR_TLS_NOT_AVAILABLE

TLS is not available

E_CLIENT_ERROR_UNSUPPORTED_AUTHENTICATION_METHOD

Requested authentication method is not supported

E_CLIENT_ERROR_SEARCH_SIZE_LIMIT_EXCEEDED

Search size limit exceeded

E_CLIENT_ERROR_SEARCH_TIME_LIMIT_EXCEEDED

Search time limit exceeded

E_CLIENT_ERROR_INVALID_QUERY

The query was invalid

E_CLIENT_ERROR_QUERY_REFUSED

The query was refused by the server side

E_CLIENT_ERROR_DBUS_ERROR

A D-Bus error occurred

E_CLIENT_ERROR_OTHER_ERROR

Other error

E_CLIENT_ERROR_NOT_OPENED

The client is not opened

E_CLIENT_ERROR_OUT_OF_SYNC

The clien tis out of sync

Since 3.2


e_client_error_to_string ()

const gchar *       e_client_error_to_string            (EClientError code);

Get localized human readable description of the given error code.

code :

an EClientError error code

Returns :

Localized human readable description of the given error code

Since 3.2


struct EClient

struct EClient {
};

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

Since 3.2


struct EClientClass

struct EClientClass {
};

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_retrieve_properties ()

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

Warning

e_client_retrieve_properties is deprecated and should not be used in newly-written code.

Asynchronously retrieves client properties to match server-side values, without waiting for the D-Bus property change notifications delivery.

When the operation is finished, callback will be called. You can then call e_client_retrieve_properties_finish() to get the result of the operation.

client :

an EClient

cancellable :

optional GCancellable object, or NULL. [allow-none]

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.16


e_client_retrieve_properties_finish ()

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

Warning

e_client_retrieve_properties_finish is deprecated and should not be used in newly-written code.

Finishes the operation started with e_client_retrieve_properties().

If an error occurs, the function sets error and returns FALSE.

client :

an EClient If an error occurs, the function sets error and returns FALSE.

Returns :

TRUE on success, FALSE on error

Since 3.16


e_client_retrieve_properties_sync ()

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

Warning

e_client_retrieve_properties_sync is deprecated and should not be used in newly-written code.

Retrieves client properties to match server-side values, without waiting for the D-Bus property change notifications delivery.

If an error occurs, the function sets error and returns FALSE.

client :

an EClient

cancellable :

optional GCancellable object, or NULL. [allow-none]

error :

return location for a GError, or NULL. [allow-none]

Returns :

TRUE on success, FALSE on error

Since 3.16


e_client_wait_for_connected ()

void                e_client_wait_for_connected         (EClient *client,
                                                         guint32 timeout_seconds,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously waits until the client is connected (according to ESource::connection-status property), but not longer than timeout_seconds.

The call is finished by e_client_wait_for_connected_finish() from the callback.

client :

an EClient

timeout_seconds :

a timeout for the wait, in seconds

cancellable :

a GCancellable; or NULL. [allow-none]

callback :

callback to call when a result is ready

user_data :

user data for the callback

Since 3.16


e_client_wait_for_connected_finish ()

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

Finishes previous call of e_client_wait_for_connected().

client :

an EClient

result :

a GAsyncResult

error :

(allow-none): a GError to set an error, or NULL. [out]

Returns :

TRUE if successful, FALSE otherwise.

Since 3.16


e_client_wait_for_connected_sync ()

gboolean            e_client_wait_for_connected_sync    (EClient *client,
                                                         guint32 timeout_seconds,
                                                         GCancellable *cancellable,
                                                         GError **error);

Synchronously waits until the client is connected (according to ESource::connection-status property), but not longer than timeout_seconds.

Note: This also calls e_client_retrieve_properties_sync() on success, to have up-to-date property values on the client side, without a delay due to property change notifcations delivery through D-Bus.

client :

an EClient

timeout_seconds :

a timeout for the wait, in seconds

cancellable :

a GCancellable; or NULL. [allow-none]

error :

(allow-none): a GError to set an error, or NULL. [out]

Returns :

TRUE if successful, FALSE otherwise.

Since 3.16


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


e_client_dup_bus_name ()

gchar *             e_client_dup_bus_name               (EClient *client);

Warning

e_client_dup_bus_name is deprecated and should not be used in newly-written code.

Returns a D-Bus bus name that will be used to connect the client to the backend subprocess.

client :

an EClient

Returns :

a newly-allocated string representing a D-Bus bus name that will be used to connect the client to the backend subprocess. The string should be freed by the caller using g_free().

Since 3.16


e_client_set_bus_name ()

void                e_client_set_bus_name               (EClient *client,
                                                         const gchar *bus_name);

Warning

e_client_set_bus_name is deprecated and should not be used in newly-written code.

Sets a D-Bus bus name that will be used to connect the client to the backend subprocess.

client :

an EClient

bus_name :

a string representing a D-Bus bus name

Since 3.16


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