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

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.

Since 3.2

e_client_error_to_string ()

const gchar *       e_client_error_to_string            (EClientError code);

FIXME: Document me.

Since 3.2

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		"capabilities"

The "capabilities" property is a comma-separated list of capabilities supported by the backend. The preferred method of retrieving and working with capabilities is e_client_get_capabilities() and e_client_check_capability().

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

struct EClient

struct EClient;

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

Since 3.2

e_client_get_source ()

ESource *           e_client_get_source                 (EClient *client);

Get the ESource that this client has assigned.

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

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.

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

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

Since 3.2

e_client_is_readonly ()

gboolean            e_client_is_readonly                (EClient *client);

Check if this client is read-only.

Since 3.2

e_client_is_online ()

gboolean            e_client_is_online                  (EClient *client);

Check if this client is connected.

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.

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

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.

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.

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

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.

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.

Since 3.2

CLIENT_BACKEND_PROPERTY_OPENED

#define CLIENT_BACKEND_PROPERTY_OPENED			"opened"

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"

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

Since 3.2

e_client_is_opened ()

gboolean            e_client_is_opened                  (EClient *client);

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.

Since 3.2.

e_client_cancel_all ()

void                e_client_cancel_all                 (EClient *client);

Cancels all pending operations started on client.

Since 3.2

e_client_unwrap_dbus_error ()

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

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

Since 3.2

e_client_retrieve_capabilities ()

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

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.

Since 3.2

e_client_retrieve_capabilities_finish ()

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

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

Since 3.2

e_client_retrieve_capabilities_sync ()

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

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.

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

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.

Since 3.2

e_client_set_backend_property_finish ()

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

Finishes previous call of e_client_set_backend_property().

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

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

Since 3.2

e_client_open ()

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

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

Since 3.2

e_client_open_finish ()

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

Finishes previous call of e_client_open().

Since 3.2

e_client_open_sync ()

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

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

Since 3.2

e_client_remove ()

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

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.

Since 3.2

e_client_remove_finish ()

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

Finishes previous call of e_client_remove().

Since 3.2

e_client_remove_sync ()

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

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

Since 3.2

e_client_util_slist_to_strv ()

gchar **            e_client_util_slist_to_strv         (const GSList *strings);

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

Since 3.2

e_client_util_strv_to_slist ()

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

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

Since 3.2

e_client_util_copy_string_slist ()

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

Copies the GSList of strings to the end of copy_to.

Since 3.2

e_client_util_copy_object_slist ()

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

Copies a GSList of GObjects to the end of copy_to.

Since 3.2

e_client_util_free_string_slist ()

void                e_client_util_free_string_slist     (GSList *strings);

Frees memory previously allocated by e_client_util_strv_to_slist().

Since 3.2

e_client_util_free_object_slist ()

void                e_client_util_free_object_slist     (GSList *objects);

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

Since 3.2

struct EClientErrorsList

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

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

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.

Since 3.2

The "capabilities" property

  "capabilities"             gpointer              : Read

The "main-context" property

  "main-context"             GMainContext*         : Read

The main loop context on which to attach event sources.

The "online" property

  "online"                   gboolean              : Read / Write

Default value: FALSE

The "opened" property

  "opened"                   gboolean              : Read

Default value: FALSE

The "readonly" property

  "readonly"                 gboolean              : Read

Default value: FALSE

The "source" property

  "source"                   ESource*              : Read / Write / Construct Only

The "backend-died" signal

void                user_function                      (EClient *eclient,
                                                        gpointer user_data)      : Run Last

The "backend-error" signal

void                user_function                      (EClient *eclient,
                                                        gchar   *arg1,
                                                        gpointer user_data)      : Run First

The "backend-property-changed" signal

void                user_function                      (EClient *eclient,
                                                        gchar   *arg1,
                                                        gchar   *arg2,
                                                        gpointer user_data)      : Run Last

The "opened" signal

void                user_function                      (EClient *arg0,
                                                        GError  *arg1,
                                                        gpointer user_data)      : Run Last