EClient

EClient

Functions

Properties

gpointer capabilities Read
gboolean online Read / Write
gboolean opened Read
gboolean readonly Read
ESource * source Read / Write / Construct Only

Signals

gboolean authenticate Run Last
void backend-died Run Last
void backend-error Run First
void backend-property-changed Run Last
void opened Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── EClient

Description

Functions

e_client_error_to_string ()

const gchar *
e_client_error_to_string (EClientError code);

FIXME: Document me.

Since 3.2


e_client_error_create ()

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

Parameters

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

ESource *
e_client_get_source (EClient *client);

Get the ESource that this client has assigned.

Parameters

client

an EClient

 

Returns

The source.

[transfer none]

Since 3.2


e_client_get_uri ()

const gchar *
e_client_get_uri (EClient *client);

Get the URI that this client has assigned. This string should not be freed.

Parameters

client

an EClient

 

Returns

The URI.

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

Parameters

client

an EClient

 

Returns

GSList of const strings of capabilities.

[element-type utf8][transfer none]

Since 3.2


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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

client

an EClient

 

Returns

TRUE if this client is connected, otherwise FALSE.

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.

Parameters

client

an EClient

 

Returns

TRUE if this client is fully opened, otherwise FALSE.

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.

Parameters

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

void
e_client_cancel_all (EClient *client);

Cancels all pending operations started on client .

Parameters

client

an EClient

 

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 .

Parameters

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

Parameters

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 .

Parameters

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_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 .

Parameters

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

Finishes previous call of e_client_set_backend_property().

Parameters

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

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

Parameters

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

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

Parameters

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

Finishes previous call of e_client_open().

Parameters

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

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

Parameters

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

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 .

Parameters

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

Finishes previous call of e_client_remove().

Parameters

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

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

Parameters

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_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 .

Parameters

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

Parameters

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.

Parameters

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_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 .

Parameters

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

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

Parameters

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

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.

Parameters

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

gchar **
e_client_util_slist_to_strv (const GSList *strings);

Convert list of strings into NULL-terminates array of strings.

Parameters

strings

a GSList of strings (const gchar *)

 

Returns

Newly allocated NULL-terminated array of strings. Returned pointer should be freed with g_strfreev().

Note: Pair 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);

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

Parameters

strv

a NULL-terminated array of strings (const gchar *)

 

Returns

Newly allocated GSList of newly allocated strings. Returned pointer should be freed with e_client_util_free_string_slist().

Note: Pair function for this is e_client_util_slist_to_strv().

[transfer full]

Since 3.2


e_client_util_copy_string_slist ()

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

Copies GSList of strings at the end of copy_to .

Parameters

copy_to

Where to copy; can be NULL

 

strings

GSList of strings to be copied

 

Returns

New head of copy_to . Returned pointer can be freed with e_client_util_free_string_slist().

[transfer full]

Since 3.2


e_client_util_copy_object_slist ()

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

Copies GSList of GObject-s at the end of copy_to .

Parameters

copy_to

Where to copy; can be NULL

 

objects

GSList of GObject-s to be copied

 

Returns

New head of copy_to . Returned pointer can be freed with e_client_util_free_object_slist().

[transfer full]

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

Parameters

strings

a GSList of strings (gchar *)

 

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 also objects itself.

Parameters

objects

a GSList of GObject-s

 

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.

Parameters

strings

string of comma-separated values

 

Returns

Newly allocated GSList of newly allocated strings corresponding to values parsed from strings . Free returned pointer with e_client_util_free_string_slist().

[transfer full]

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.

Parameters

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

Types and Values

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

FIXME Document each code.

Error codes for EClient operations.

Members

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

   

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


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


struct EClientErrorsList

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

Since 3.2

Property Details

The “capabilities” property

  “capabilities”             gpointer

Flags: Read


The “online” property

  “online”                   gboolean

Flags: Read / Write

Default value: FALSE


The “opened” property

  “opened”                   gboolean

Flags: Read

Default value: FALSE


The “readonly” property

  “readonly”                 gboolean

Flags: Read

Default value: FALSE


The “source” property

  “source”                   ESource *

Flags: Read / Write / Construct Only

Signal Details

The “authenticate” signal

gboolean
user_function (EClient *eclient,
               gpointer arg1,
               gpointer user_data)

Flags: Run Last


The “backend-died” signal

void
user_function (EClient *eclient,
               gpointer user_data)

Flags: Run Last


The “backend-error” signal

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

Flags: Run First


The “backend-property-changed” signal

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

Flags: Run Last


The “opened” signal

void
user_function (EClient *eclient,
               GError  *arg1,
               gpointer user_data)

Flags: Run Last