EBookBackend

EBookBackend — An abstract class for implementing addressbook backends

Functions

const gchar * e_book_backend_get_cache_dir ()
gchar * e_book_backend_dup_cache_dir ()
void e_book_backend_set_cache_dir ()
EDataBook * e_book_backend_ref_data_book ()
void e_book_backend_set_data_book ()
GProxyResolver * e_book_backend_ref_proxy_resolver ()
ESourceRegistry * e_book_backend_get_registry ()
gboolean e_book_backend_get_writable ()
void e_book_backend_set_writable ()
gboolean e_book_backend_is_opened ()
gboolean e_book_backend_is_readonly ()
gchar * e_book_backend_get_backend_property ()
gboolean e_book_backend_open_sync ()
void e_book_backend_open ()
gboolean e_book_backend_open_finish ()
gboolean e_book_backend_refresh_sync ()
void e_book_backend_refresh ()
gboolean e_book_backend_refresh_finish ()
gboolean e_book_backend_create_contacts_sync ()
void e_book_backend_create_contacts ()
gboolean e_book_backend_create_contacts_finish ()
gboolean e_book_backend_modify_contacts_sync ()
void e_book_backend_modify_contacts ()
gboolean e_book_backend_modify_contacts_finish ()
gboolean e_book_backend_remove_contacts_sync ()
void e_book_backend_remove_contacts ()
gboolean e_book_backend_remove_contacts_finish ()
EContact * e_book_backend_get_contact_sync ()
void e_book_backend_get_contact ()
EContact * e_book_backend_get_contact_finish ()
gboolean e_book_backend_get_contact_list_sync ()
void e_book_backend_get_contact_list ()
gboolean e_book_backend_get_contact_list_finish ()
gboolean e_book_backend_get_contact_list_uids_sync ()
void e_book_backend_get_contact_list_uids ()
gboolean e_book_backend_get_contact_list_uids_finish ()
gboolean e_book_backend_contains_email_sync ()
void e_book_backend_contains_email ()
gboolean e_book_backend_contains_email_finish ()
void e_book_backend_start_view ()
void e_book_backend_stop_view ()
void e_book_backend_add_view ()
void e_book_backend_remove_view ()
GList * e_book_backend_list_views ()
gboolean (*EBookBackendForeachViewFunc) ()
gboolean e_book_backend_foreach_view ()
void e_book_backend_foreach_view_notify_progress ()
void e_book_backend_notify_update ()
void e_book_backend_notify_remove ()
void e_book_backend_notify_complete ()
void e_book_backend_notify_error ()
void e_book_backend_notify_property_changed ()
EDataBookDirect * e_book_backend_get_direct_book ()
void e_book_backend_configure_direct ()
void e_book_backend_sync ()
gboolean e_book_backend_set_locale ()
gchar * e_book_backend_dup_locale ()
EDataBookCursor * e_book_backend_create_cursor ()
gboolean e_book_backend_delete_cursor ()
void (*EBookBackendCustomOpFunc) ()
void e_book_backend_schedule_custom_operation ()
EDataBookView * e_book_backend_ref_view ()
gpointer e_book_backend_ref_view_user_data ()
void e_book_backend_take_view_user_data ()
EBookClientViewSortFields * e_book_backend_dup_view_sort_fields ()
void e_book_backend_set_view_sort_fields ()
guint e_book_backend_get_view_n_total ()
void e_book_backend_set_view_n_total ()
EBookIndices * e_book_backend_dup_view_indices ()
void e_book_backend_set_view_indices ()
GPtrArray * e_book_backend_dup_view_contacts ()

Properties

char * cache-dir Read / Write
GProxyResolver * proxy-resolver Read
ESourceRegistry * registry Read / Write / Construct Only
gboolean writable Read / Write

Signals

void closed Run Last
void shutdown Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── EBackend
        ╰── EBookBackend
            ╰── EBookBackendSync

Includes

#include <libedata-book/libedata-book.h>

Description

This is the main server facing API for interfacing with addressbook backends, addressbook backends must implement methods on this class.

Functions

e_book_backend_get_cache_dir ()

const gchar *
e_book_backend_get_cache_dir (EBookBackend *backend);

Returns the cache directory path used by backend .

Parameters

backend

an EBookBackend

 

Returns

the cache directory path

Since: 2.32


e_book_backend_dup_cache_dir ()

gchar *
e_book_backend_dup_cache_dir (EBookBackend *backend);

Thread-safe variation of e_book_backend_get_cache_dir(). Use this function when accessing backend from multiple threads.

The returned string should be freed with g_free() when no longer needed.

Parameters

backend

an EBookBackend

 

Returns

a newly-allocated copy of “cache-dir”

Since: 3.10


e_book_backend_set_cache_dir ()

void
e_book_backend_set_cache_dir (EBookBackend *backend,
                              const gchar *cache_dir);

Sets the cache directory path for use by backend .

Note that EBookBackend is initialized with a default cache directory path which should suffice for most cases. Backends should not override the default path without good reason.

Parameters

backend

an EBookBackend

 

cache_dir

a local cache directory path

 

Since: 2.32


e_book_backend_ref_data_book ()

EDataBook *
e_book_backend_ref_data_book (EBookBackend *backend);

Returns the EDataBook for backend . The EDataBook is essentially the glue between incoming D-Bus requests and backend 's native API.

An EDataBook should be set only once after backend is first created. If an EDataBook has not yet been set, the function returns NULL.

The returned EDataBook is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

Parameters

backend

an EBookBackend

 

Returns

an EDataBook, or NULL.

[transfer full][nullable]

Since: 3.10


e_book_backend_set_data_book ()

void
e_book_backend_set_data_book (EBookBackend *backend,
                              EDataBook *data_book);

Sets the EDataBook for backend . The EDataBook is essentially the glue between incoming D-Bus requests and backend 's native API.

An EDataBook should be set only once after backend is first created.

Parameters

backend

an EBookBackend

 

data_book

an EDataBook

 

Since: 3.10


e_book_backend_ref_proxy_resolver ()

GProxyResolver *
e_book_backend_ref_proxy_resolver (EBookBackend *backend);

Returns the GProxyResolver for backend (if applicable), as indicated by the “proxy-uid” of backend 's “source” or one of its ancestors.

The returned GProxyResolver is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

Parameters

backend

an EBookBackend

 

Returns

a GProxyResolver, or NULL.

[transfer full][nullable]

Since: 3.12


e_book_backend_get_registry ()

ESourceRegistry *
e_book_backend_get_registry (EBookBackend *backend);

Returns the data source registry to which “source” belongs.

Parameters

backend

an EBookBackend

 

Returns

an ESourceRegistry.

[transfer none]

Since: 3.6


e_book_backend_get_writable ()

gboolean
e_book_backend_get_writable (EBookBackend *backend);

Returns whether backend will accept changes to its data content.

Parameters

backend

an EBookBackend

 

Returns

whether backend is writable

Since: 3.8


e_book_backend_set_writable ()

void
e_book_backend_set_writable (EBookBackend *backend,
                             gboolean writable);

Sets whether backend will accept changes to its data content.

Parameters

backend

an EBookBackend

 

writable

whether backend is writable

 

Since: 3.8


e_book_backend_is_opened ()

gboolean
e_book_backend_is_opened (EBookBackend *backend);

Checks if backend 's storage has been opened (and authenticated, if necessary) and the backend itself is ready for accessing. This property is changed automatically after the backend is successfully opened.

Parameters

backend

an EBookBackend

 

Returns

TRUE if fully opened, FALSE otherwise.

Since: 3.2


e_book_backend_is_readonly ()

gboolean
e_book_backend_is_readonly (EBookBackend *backend);

Checks if we can write to backend .

Parameters

backend

an EBookBackend

 

Returns

TRUE if read-only, FALSE if not.

Since: 3.2


e_book_backend_get_backend_property ()

gchar *
e_book_backend_get_backend_property (EBookBackend *backend,
                                     const gchar *prop_name);

Obtains the value of the backend property named prop_name . Freed the returned string with g_free() when finished with it.

Parameters

backend

an EBookBackend

 

prop_name

a backend property name

 

Returns

the value for prop_name

Since: 3.10


e_book_backend_open_sync ()

gboolean
e_book_backend_open_sync (EBookBackend *backend,
                          GCancellable *cancellable,
                          GError **error);

"Opens" the backend . Opening a backend is something of an outdated concept, but the operation is hanging around for a little while longer. This usually involves some custom initialization logic, and testing of remote authentication if applicable.

If an error occurs, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_open ()

void
e_book_backend_open (EBookBackend *backend,
                     GCancellable *cancellable,
                     GAsyncReadyCallback callback,
                     gpointer user_data);

Asynchronously "opens" the backend . Opening a backend is something of an outdated concept, but the operation is hanging around for a little while longer. This usually involves some custom initialization logic, and testing of remote authentication if applicable.

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

Parameters

backend

an EBookBackend

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.10


e_book_backend_open_finish ()

gboolean
e_book_backend_open_finish (EBookBackend *backend,
                            GAsyncResult *result,
                            GError **error);

Finishes the operation started with e_book_backend_open().

If an error occurred, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_refresh_sync ()

gboolean
e_book_backend_refresh_sync (EBookBackend *backend,
                             GCancellable *cancellable,
                             GError **error);

Initiates a refresh for backend , if the backend supports refreshing. The actual refresh operation completes on its own time. This function merely initiates the operation.

If an error occurs while initiating the refresh, the function will set error and return FALSE. If the backend does not support refreshing, the function will set an E_CLIENT_ERROR_NOT_SUPPORTED error and return FALSE.

Parameters

backend

an EBookBackend

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_refresh ()

void
e_book_backend_refresh (EBookBackend *backend,
                        GCancellable *cancellable,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

Asynchronously initiates a refresh for backend , if the backend supports refreshing. The actual refresh operation completes on its own time. This function, along with e_book_backend_refresh_finish(), merely initiates the operation.

Once the refresh is initiated, callback will be called. You can then call e_book_backend_refresh_finish() to get the result of the initiation.

Parameters

backend

an EBookBackend

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.10


e_book_backend_refresh_finish ()

gboolean
e_book_backend_refresh_finish (EBookBackend *backend,
                               GAsyncResult *result,
                               GError **error);

Finishes the refresh initiation started with e_book_backend_refresh().

If an error occurred while initiating the refresh, the function will set error and return FALSE. If the backend does not support refreshing, the function will set an E_CLIENT_ERROR_NOT_SUPPORTED error and return FALSE.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_create_contacts_sync ()

gboolean
e_book_backend_create_contacts_sync (EBookBackend *backend,
                                     const gchar * const *vcards,
                                     guint32 opflags,
                                     GQueue *out_contacts,
                                     GCancellable *cancellable,
                                     GError **error);

Creates one or more new contacts from vcards , and deposits an EContact instance for each newly-created contact in out_contacts .

The returned EContact instances are referenced for thread-safety and must be unreferenced with g_object_unref() when finished with them.

If an error occurs, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

vcards

a NULL-terminated array of vCard strings

 

opflags

bit-or of EBookOperationFlags

 

out_contacts

a GQueue in which to deposit results

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_create_contacts ()

void
e_book_backend_create_contacts (EBookBackend *backend,
                                const gchar * const *vcards,
                                guint32 opflags,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously creates one or more new contacts from vcards .

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

Parameters

backend

an EBookBackend

 

vcards

a NULL-terminated array of vCard strings

 

opflags

bit-or of EBookOperationFlags

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.10


e_book_backend_create_contacts_finish ()

gboolean
e_book_backend_create_contacts_finish (EBookBackend *backend,
                                       GAsyncResult *result,
                                       GQueue *out_contacts,
                                       GError **error);

Finishes the operation started with e_book_backend_create_contacts().

An EContact instance for each newly-created contact is deposited in out_contacts . The returned EContact instances are referenced for thread-safety and must be unreferenced with g_object_unref() when finished with them.

If an error occurred, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

out_contacts

a GQueue in which to deposit results

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_modify_contacts_sync ()

gboolean
e_book_backend_modify_contacts_sync (EBookBackend *backend,
                                     const gchar * const *vcards,
                                     guint32 opflags,
                                     GCancellable *cancellable,
                                     GError **error);

Modifies one or more contacts according to vcards .

If an error occurs, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

vcards

a NULL-terminated array of vCard strings

 

opflags

bit-or of EBookOperationFlags

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_modify_contacts ()

void
e_book_backend_modify_contacts (EBookBackend *backend,
                                const gchar * const *vcards,
                                guint32 opflags,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously modifies one or more contacts according to vcards .

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

Parameters

backend

an EBookBackend

 

vcards

a NULL-terminated array of vCard strings

 

opflags

bit-or of EBookOperationFlags

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.10


e_book_backend_modify_contacts_finish ()

gboolean
e_book_backend_modify_contacts_finish (EBookBackend *backend,
                                       GAsyncResult *result,
                                       GError **error);

Finishes the operation started with e_book_backend_modify_contacts().

If an error occurred, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_remove_contacts_sync ()

gboolean
e_book_backend_remove_contacts_sync (EBookBackend *backend,
                                     const gchar * const *uids,
                                     guint32 opflags,
                                     GCancellable *cancellable,
                                     GError **error);

Removes one or more contacts according to uids .

If an error occurs, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

uids

a NULL-terminated array of contact ID strings

 

opflags

bit-or of EBookOperationFlags

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_remove_contacts ()

void
e_book_backend_remove_contacts (EBookBackend *backend,
                                const gchar * const *uids,
                                guint32 opflags,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously removes one or more contacts according to uids .

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

Parameters

backend

an EBookBackend

 

uids

a NULL-terminated array of contact ID strings.

[array zero-terminated=1]

opflags

bit-or of EBookOperationFlags

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.10


e_book_backend_remove_contacts_finish ()

gboolean
e_book_backend_remove_contacts_finish (EBookBackend *backend,
                                       GAsyncResult *result,
                                       GError **error);

Finishes the operation started with e_book_backend_remove_contacts().

If an error occurred, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_get_contact_sync ()

EContact *
e_book_backend_get_contact_sync (EBookBackend *backend,
                                 const gchar *uid,
                                 GCancellable *cancellable,
                                 GError **error);

Obtains an EContact for uid .

The returned EContact is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

If an error occurs, the function will set error and return NULL.

Parameters

backend

an EBookBackend

 

uid

a contact ID

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

an EContact, or NULL on error.

[transfer full]

Since: 3.10


e_book_backend_get_contact ()

void
e_book_backend_get_contact (EBookBackend *backend,
                            const gchar *uid,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronously obtains an EContact for uid .

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

Parameters

backend

an EBookBackend

 

uid

a contact ID

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.10


e_book_backend_get_contact_finish ()

EContact *
e_book_backend_get_contact_finish (EBookBackend *backend,
                                   GAsyncResult *result,
                                   GError **error);

Finishes the operation started with e_book_backend_get_contact_finish().

The returned EContact is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

If an error occurred, the function will set error and return NULL.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

an EContact, or NULL on error.

[transfer full]

Since: 3.10


e_book_backend_get_contact_list_sync ()

gboolean
e_book_backend_get_contact_list_sync (EBookBackend *backend,
                                      const gchar *query,
                                      GQueue *out_contacts,
                                      GCancellable *cancellable,
                                      GError **error);

Obtains a set of EContact instances which satisfy the criteria specified in query , and deposits them in out_contacts .

The returned EContact instances are referenced for thread-safety and must be unreferenced with g_object_unref() when finished with them.

If an error occurs, the function will set error and return FALSE. Note that an empty result set does not necessarily imply an error.

Parameters

backend

an EBookBackend

 

query

a search query in S-expression format

 

out_contacts

a GQueue in which to deposit results

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_get_contact_list ()

void
e_book_backend_get_contact_list (EBookBackend *backend,
                                 const gchar *query,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Asynchronously obtains a set of EContact instances which satisfy the criteria specified in query .

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

Parameters

backend

an EBookBackend

 

query

a search query in S-expression format

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.10


e_book_backend_get_contact_list_finish ()

gboolean
e_book_backend_get_contact_list_finish
                               (EBookBackend *backend,
                                GAsyncResult *result,
                                GQueue *out_contacts,
                                GError **error);

Finishes the operation started with e_book_backend_get_contact_list().

The matching EContact instances are deposited in out_contacts . The returned EContact instances are referenced for thread-safety and must be unreferenced with g_object_unref() when finished with them.

If an error occurred, the function will set error and return FALSE. Note that an empty result set does not necessarily imply an error.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

out_contacts

a GQueue in which to deposit results

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_get_contact_list_uids_sync ()

gboolean
e_book_backend_get_contact_list_uids_sync
                               (EBookBackend *backend,
                                const gchar *query,
                                GQueue *out_uids,
                                GCancellable *cancellable,
                                GError **error);

Obtains a set of ID strings for contacts which satisfy the criteria specified in query , and deposits them in out_uids .

The returned ID strings must be freed with g_free() with finished with them.

If an error occurs, the function will set error and return FALSE. Note that an empty result set does not necessarily imply an error.

Parameters

backend

an EBookBackend

 

query

a search query in S-expression format

 

out_uids

a GQueue in which to deposit results

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_get_contact_list_uids ()

void
e_book_backend_get_contact_list_uids (EBookBackend *backend,
                                      const gchar *query,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Asynchronously obtains a set of ID strings for contacts which satisfy the criteria specified in query .

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

Parameters

backend

an EBookBackend

 

query

a search query in S-expression format

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.10


e_book_backend_get_contact_list_uids_finish ()

gboolean
e_book_backend_get_contact_list_uids_finish
                               (EBookBackend *backend,
                                GAsyncResult *result,
                                GQueue *out_uids,
                                GError **error);

Finishes the operation started with e_book_backend_get_contact_list_uids_finish().

ID strings for the matching contacts are deposited in out_uids , and must be freed with g_free() when finished with them.

If an error occurs, the function will set error and return FALSE. Note that an empty result set does not necessarily imply an error.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

out_uids

a GQueue in which to deposit results

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.10


e_book_backend_contains_email_sync ()

gboolean
e_book_backend_contains_email_sync (EBookBackend *backend,
                                    const gchar *email_address,
                                    GCancellable *cancellable,
                                    GError **error);

Checks whether contains an email_address . When the email_address contains multiple addresses, then returns TRUE when at least one address exists in the address book.

If an error occurs, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

email_address

an email address

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE when found the email_address , FALSE on failure

Since: 3.44


e_book_backend_contains_email ()

void
e_book_backend_contains_email (EBookBackend *backend,
                               const gchar *email_address,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Asynchronously checks whether contains an email_address . When the email_address contains multiple addresses, then returns TRUE when at least one address exists in the address book.

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

Parameters

backend

an EBookBackend

 

email_address

an email address

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

Since: 3.44


e_book_backend_contains_email_finish ()

gboolean
e_book_backend_contains_email_finish (EBookBackend *backend,
                                      GAsyncResult *result,
                                      GError **error);

Finishes the operation started with e_book_backend_contains_email().

If an error occurred, the function will set error and return FALSE.

Parameters

backend

an EBookBackend

 

result

a GAsyncResult

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.44


e_book_backend_start_view ()

void
e_book_backend_start_view (EBookBackend *backend,
                           EDataBookView *view);

Starts running the query specified by view , emitting signals for matching contacts.

Parameters

backend

an EBookBackend

 

view

the EDataBookView to start

 

e_book_backend_stop_view ()

void
e_book_backend_stop_view (EBookBackend *backend,
                          EDataBookView *view);

Stops running the query specified by view , emitting no more signals.

Parameters

backend

an EBookBackend

 

view

the EDataBookView to stop

 

e_book_backend_add_view ()

void
e_book_backend_add_view (EBookBackend *backend,
                         EDataBookView *view);

Adds view to backend for querying.

Parameters

backend

an EBookBackend

 

view

an EDataBookView

 

e_book_backend_remove_view ()

void
e_book_backend_remove_view (EBookBackend *backend,
                            EDataBookView *view);

Removes view from backend .

Parameters

backend

an EBookBackend

 

view

an EDataBookView

 

e_book_backend_list_views ()

GList *
e_book_backend_list_views (EBookBackend *backend);

Returns a list of EDataBookView instances added with e_book_backend_add_view().

The views returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list properly in one step is as follows:

1
g_list_free_full (list, g_object_unref);

Parameters

backend

an EBookBackend

 

Returns

a list of book views.

[transfer full][element-type EDataBookView]

Since: 3.8


EBookBackendForeachViewFunc ()

gboolean
(*EBookBackendForeachViewFunc) (EBookBackend *backend,
                                EDataBookView *view,
                                gpointer user_data);

Callback function used by e_book_backend_foreach_view().

Parameters

backend

an EBookBackend

 

view

an EDataBookView

 

user_data

user data for the function

 

Returns

TRUE, to continue, FALSE to stop further processing.

Since: 3.34


e_book_backend_foreach_view ()

gboolean
e_book_backend_foreach_view (EBookBackend *backend,
                             EBookBackendForeachViewFunc func,
                             gpointer user_data);

Calls func for each existing view (as returned by e_book_backend_list_views()). The func can return FALSE to stop early.

Parameters

backend

an EBookBackend

 

func

an EBookBackendForeachViewFunc function to call.

[scope call]

user_data

user data to pass to func .

[closure func]

Returns

whether the call had been stopped by func

Since: 3.34


e_book_backend_foreach_view_notify_progress ()

void
e_book_backend_foreach_view_notify_progress
                               (EBookBackend *backend,
                                gboolean only_completed_views,
                                gint percent,
                                const gchar *message);

Notifies each view of the backend about progress. When only_completed_views is TRUE, notifies only completed views.

Parameters

backend

an EBookBackend

 

only_completed_views

whether notify in completed views only

 

percent

percent complete

 

message

message describing the operation in progress, or NULL.

[nullable]

Since: 3.34


e_book_backend_notify_update ()

void
e_book_backend_notify_update (EBookBackend *backend,
                              const EContact *contact);

Notifies all of backend 's book views about the new or modified contacts contact .

e_data_book_respond_create_contacts() and e_data_book_respond_modify_contacts() call this function for you. You only need to call this from your backend if contacts are created or modified by another (non-PAS-using) client.

Parameters

backend

an EBookBackend

 

contact

a new or modified contact

 

e_book_backend_notify_remove ()

void
e_book_backend_notify_remove (EBookBackend *backend,
                              const gchar *id);

Notifies all of backend 's book views that the contact with UID id has been removed.

e_data_book_respond_remove_contacts() calls this function for you. You only need to call this from your backend if contacts are removed by another (non-PAS-using) client.

Parameters

backend

an EBookBackend

 

id

a contact id

 

e_book_backend_notify_complete ()

void
e_book_backend_notify_complete (EBookBackend *backend);

Notifies all of backend 's book views that the current set of notifications is complete; use this after a series of e_book_backend_notify_update() and e_book_backend_notify_remove() calls.

Parameters

backend

an EBookBackend

 

e_book_backend_notify_error ()

void
e_book_backend_notify_error (EBookBackend *backend,
                             const gchar *message);

Notifies each backend listener about an error. This is meant to be used for cases where is no GError return possibility, to notify user about an issue.

Parameters

backend

an EBookBackend

 

message

an error message

 

Since: 3.2


e_book_backend_notify_property_changed ()

void
e_book_backend_notify_property_changed
                               (EBookBackend *backend,
                                const gchar *prop_name,
                                const gchar *prop_value);

Notifies clients about property value change.

Parameters

backend

an EBookBackend

 

prop_name

property name, which changed

 

prop_value

new property value.

[nullable]

Since: 3.2


e_book_backend_get_direct_book ()

EDataBookDirect *
e_book_backend_get_direct_book (EBookBackend *backend);

Tries to create an EDataBookDirect for backend if backend supports direct read access.

Parameters

backend

an EBookBackend

 

Returns

A new EDataBookDirect object, or NULL if backend does not support direct access.

[transfer full][nullable]

Since: 3.8


e_book_backend_configure_direct ()

void
e_book_backend_configure_direct (EBookBackend *backend,
                                 const gchar *config);

This method is called on backend in direct read access mode. The config argument is the same configuration string which the same backend reported in the EDataBookDirect returned by e_book_backend_get_direct_book().

The configuration string is optional and is used to ensure that direct access backends are properly configured to interface with the same data as the running server side backend.

Parameters

backend

an EBookBackend

 

config

The configuration string for the given backend

 

Since: 3.8


e_book_backend_sync ()

void
e_book_backend_sync (EBookBackend *backend);

e_book_backend_set_locale ()

gboolean
e_book_backend_set_locale (EBookBackend *backend,
                           const gchar *locale,
                           GCancellable *cancellable,
                           GError **error);

Notify the addressbook backend that the current locale has changed, this is important for backends which support ordered result lists which are locale sensitive.

Parameters

backend

an EBookBackend

 

locale

the new locale for the addressbook

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.12


e_book_backend_dup_locale ()

gchar *
e_book_backend_dup_locale (EBookBackend *backend);

Fetches a copy of the currently configured locale for the addressbook

Parameters

backend

an EBookBackend

 

Returns

A copy of the currently configured locale for the addressbook. Free with g_free() when done with it.

Since: 3.12


e_book_backend_create_cursor ()

EDataBookCursor *
e_book_backend_create_cursor (EBookBackend *backend,
                              EContactField *sort_fields,
                              EBookCursorSortType *sort_types,
                              guint n_fields,
                              GError **error);

Creates a new EDataBookCursor for the given backend if the backend has cursor support. If the backend does not support cursors then an E_CLIENT_ERROR_NOT_SUPPORTED error will be set in error .

Backends can also refuse to create cursors for some values of sort_fields and report more specific errors.

The returned cursor belongs to backend and should be destroyed with e_book_backend_delete_cursor() when no longer needed.

Parameters

backend

an EBookBackend

 

sort_fields

the EContactFields to sort by

 

sort_types

the EBookCursorSortTypes for the sorted fields

 

n_fields

the number of fields in the sort_fields and sort_types

 

error

return location for a GError, or NULL

 

Returns

A newly created cursor, the cursor belongs to the backend and should not be unreffed, or NULL on error.

[transfer none]

Since: 3.12


e_book_backend_delete_cursor ()

gboolean
e_book_backend_delete_cursor (EBookBackend *backend,
                              EDataBookCursor *cursor,
                              GError **error);

Requests backend to release and destroy cursor , this will trigger an E_CLIENT_ERROR_INVALID_ARG error if cursor is not owned by backend .

Parameters

backend

an EBookBackend

 

cursor

the EDataBookCursor to destroy

 

error

return location for a GError, or NULL

 

Returns

Whether cursor was successfully deleted.

Since: 3.12


EBookBackendCustomOpFunc ()

void
(*EBookBackendCustomOpFunc) (EBookBackend *book_backend,
                             gpointer user_data,
                             GCancellable *cancellable,
                             GError **error);

A callback prototype being called in a dedicated thread, scheduled by e_book_backend_schedule_custom_operation().

Parameters

book_backend

an EBookBackend

 

user_data

a function user data, as provided to e_book_backend_schedule_custom_operation()

 

cancellable

an optional GCancellable, as provided to e_book_backend_schedule_custom_operation()

 

error

return location for a GError, or NULL

 

Since: 3.26


e_book_backend_schedule_custom_operation ()

void
e_book_backend_schedule_custom_operation
                               (EBookBackend *book_backend,
                                GCancellable *use_cancellable,
                                EBookBackendCustomOpFunc func,
                                gpointer user_data,
                                GDestroyNotify user_data_free);

Schedules user function func to be run in a dedicated thread as a blocking operation.

The function adds its own reference to use_cancellable , if not NULL.

The error returned from func is propagated to client using e_book_backend_notify_error() function. If it's not desired, then left the error unchanged and notify about errors manually.

Parameters

book_backend

an EBookBackend

 

use_cancellable

an optional GCancellable to use for func .

[nullable]

func

a function to call in a dedicated thread

 

user_data

user data being passed to func

 

user_data_free

optional destroy call back for user_data .

[nullable]

Since: 3.26


e_book_backend_ref_view ()

EDataBookView *
e_book_backend_ref_view (EBookBackend *backend,
                         gsize view_id);

References an EDataBookView by its identifier.

Unref the returned non-NULL view with g_object_unref(), when no longer needed.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

Returns

a referenced EDataBookView corresponding to the given view_id , or NULL, when it cannot be found.

[transfer full][nullable]

Since: 3.50


e_book_backend_ref_view_user_data ()

gpointer
e_book_backend_ref_view_user_data (EBookBackend *backend,
                                   gsize view_id);

References user data previously set by e_book_backend_take_view_user_data() for the view_id .

Free the returned non-NULL object with g_object_unref(), when no longer needed.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

Returns

previously set user data for the view_id , or NULL when none had been set yet or when the view does not exist.

[transfer full][type GObject]

Since: 3.50


e_book_backend_take_view_user_data ()

void
e_book_backend_take_view_user_data (EBookBackend *backend,
                                    gsize view_id,
                                    GObject *user_data);

Sets the user data for the view_id . The function assumes ownership of the user_data . The user_data can be NULL, which unsets the current user data for the view.

This is primarily aimed as a helper for backend implementations of the manual query views (E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY).

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

user_data

user data to set.

[nullable][transfer full]

Since: 3.50


e_book_backend_dup_view_sort_fields ()

EBookClientViewSortFields *
e_book_backend_dup_view_sort_fields (EBookBackend *backend,
                                     gsize view_id);

Returns currently used sort fields for manual query views. The returned array is NULL only if the view could not be found. The default sort is by the file-as filed in ascending order.

The array is terminated by an item with an E_CONTACT_FIELD_LAST field.

Free the returned array with e_book_client_view_sort_fields_free(), when no longer needed.

Note: This function should be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY views.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

Returns

current sort fields for the view_id , as an EBookClientViewSortFields array, or NULL, when the view could not be found.

[transfer full]

Since: 3.50


e_book_backend_set_view_sort_fields ()

void
e_book_backend_set_view_sort_fields (EBookBackend *backend,
                                     gsize view_id,
                                     const EBookClientViewSortFields *fields);

Sets the sort fields for the view identified by the view_id . The fields array should be terminated by an item, which has the field member set to E_CONTACT_FIELD_LAST.

When the fields is NULL, the sort by file-as in ascending order is used instead.

The default implementation of this virtual method stores the fields into the internal structure for the backend , to be available by e_book_backend_dup_view_sort_fields().

Note: This function should be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY views.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

fields

an array of EBookClientViewSortFields, or NULL.

[nullable]

Since: 3.50


e_book_backend_get_view_n_total ()

guint
e_book_backend_get_view_n_total (EBookBackend *backend,
                                 gsize view_id);

Returns how many contacts the view identified by view_id contains.

The default implementation of this virtual method returns the value previously set by e_book_backend_set_view_n_total().

Note: This function should be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY views.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

Returns

how many contacts the view identified by view_id contains.

Since: 3.50


e_book_backend_set_view_n_total ()

void
e_book_backend_set_view_n_total (EBookBackend *backend,
                                 gsize view_id,
                                 guint n_total);

Stores how many contacts the view identified by view_id contains. It also sets the n_total to the corresponding EDataBookView, if such exists. The function does nothing when the view cannot be found.

Note: This function should be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY views.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

n_total

the value to set

 

Since: 3.50


e_book_backend_dup_view_indices ()

EBookIndices *
e_book_backend_dup_view_indices (EBookBackend *backend,
                                 gsize view_id);

Returns a list of EBookIndices holding indices of the contacts in the view identified by view_id . The array is terminated by an item with chr member being NULL.

The default implementation returns an array previously set by e_book_backend_set_view_indices().

Free the returned array with e_book_indices_free(), when no longer needed.

Note: This function should be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY views.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

Returns

an array of EBookIndices, or NULL.

[transfer full][nullable]

Since: 3.50


e_book_backend_set_view_indices ()

void
e_book_backend_set_view_indices (EBookBackend *backend,
                                 gsize view_id,
                                 const EBookIndices *indices);

Stores current indices for the view identified by the view_id and, if such exists, notifies about it also the corresponding EDataBookView. The array is terminated by an item with chr member being NULL.

Note: This function should be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY views.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

indices

an array of EBookIndices, or NULL.

[nullable]

Since: 3.50


e_book_backend_dup_view_contacts ()

GPtrArray *
e_book_backend_dup_view_contacts (EBookBackend *backend,
                                  gsize view_id,
                                  guint range_start,
                                  guint range_length);

Returns range_length contacts from 0-based index range_start in the view identified by the view_id . When there are asked more than e_book_backend_get_view_n_total() contacts only those up to the total number of contacts are read. Asking for out of range contacts results in an error, though it can return less than range_length contacts.

The default implementation tracks the view's content in memory and returns the contacts as needed. The subclasses can do more efficient implementation.

Note: This function should be used only with E_BOOK_CLIENT_VIEW_FLAGS_MANUAL_QUERY views.

Parameters

backend

an EBookBackend

 

view_id

a view identifier

 

range_start

0-based range start to retrieve the contacts for

 

range_length

how many contacts to retrieve

 

Returns

an array of the contacts, or NULL, when the view cannot be found or when the range_start is out of bounds.

[transfer container][element-type EContact][nullable]

Since: 3.50

Types and Values

struct EBookBackend

struct EBookBackend;

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


struct EBookBackendClass

struct EBookBackendClass {
	/* Set this to TRUE to use a serial dispatch queue, instead
	 * of a concurrent dispatch queue.  A serial dispatch queue
	 * executes one method at a time in the order in which they
	 * were called.  This is generally slower than a concurrent
	 * dispatch queue, but helps avoid thread-safety issues. */
	gboolean use_serial_dispatch_queue;

	gchar *		(*impl_get_backend_property)
						 (EBookBackend *backend,
						 const gchar *prop_name);

	void		(*impl_open)		(EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable);
	void		(*impl_refresh)		(EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable);
	void		(*impl_create_contacts) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar * const *vcards,
						 guint32 opflags); /* bit-or of EBookOperationFlags */
	void		(*impl_modify_contacts) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar * const *vcards,
						 guint32 opflags); /* bit-or of EBookOperationFlags */
	void		(*impl_remove_contacts) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar * const *uids,
						 guint32 opflags); /* bit-or of EBookOperationFlags */
	void		(*impl_get_contact) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar *id);
	void		(*impl_get_contact_list)(EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar *query);
	void		(*impl_get_contact_list_uids)
						(EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar *query);

	void		(*impl_start_view) (EBookBackend *backend,
						 EDataBookView *view);
	void		(*impl_stop_view) (EBookBackend *backend,
						 EDataBookView *view);

	void		(*impl_notify_update) (EBookBackend *backend,
						 const EContact *contact);

	EDataBookDirect *
			(*impl_get_direct_book) (EBookBackend *backend);
	void		(*impl_configure_direct)(EBookBackend *backend,
						 const gchar *config);

	gboolean (*impl_set_locale) (EBookBackend *backend,
						 const gchar *locale,
						 GCancellable *cancellable,
						 GError **error);
	gchar *		(*impl_dup_locale) (EBookBackend *backend);
	EDataBookCursor *
			(*impl_create_cursor) (EBookBackend *backend,
						 EContactField *sort_fields,
						 EBookCursorSortType *sort_types,
						 guint n_fields,
						 GError **error);
	gboolean (*impl_delete_cursor) (EBookBackend *backend,
						 EDataBookCursor *cursor,
						 GError **error);

	/* Signals */
	void		(*closed)		(EBookBackend *backend,
						 const gchar *sender);
	void		(*shutdown)		(EBookBackend *backend);

	void		(*impl_contains_email) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar *email_address);

	/* Functions for EBookClientView's manual query support */
	void		(*impl_set_view_sort_fields)
						(EBookBackend *backend,
						 gsize view_id,
						 const EBookClientViewSortFields *fields);
	guint		(*impl_get_view_n_total)(EBookBackend *backend,
						 gsize view_id);
	EBookIndices * (*impl_dup_view_indices)(EBookBackend *backend,
						 gsize view_id);
	GPtrArray * (*impl_dup_view_contacts) /* EContact * */
						(EBookBackend *backend,
						 gsize view_id,
						 guint range_start,
						 guint range_length);

	/* Padding for future expansion */
	gpointer reserved_padding[15];
};

Class structure for the EBookBackend class.

These virtual methods must be implemented when writing an addressbook backend.

Members

gboolean use_serial_dispatch_queue;

Whether a serial dispatch queue should be used for this backend or not. The default is TRUE.

 

impl_get_backend_property ()

Fetch a property value by name from the backend

 

impl_open ()

Open the backend

 

impl_refresh ()

Refresh the backend

 

impl_create_contacts ()

Add and store the passed vcards

 

impl_modify_contacts ()

Modify the existing contacts using the passed vcards

 

impl_remove_contacts ()

Remove the contacts specified by the passed UIDs

 

impl_get_contact ()

Fetch a contact by UID

 

impl_get_contact_list ()

Fetch a list of contacts based on a search expression

 

impl_get_contact_list_uids ()

Fetch a list of contact UIDs based on a search expression

 

impl_start_view ()

Start up the specified view

 

impl_stop_view ()

Stop the specified view

 

impl_notify_update ()

Notify changes which might have occured for a given contact

 

impl_get_direct_book ()

For addressbook backends which support Direct Read Access, report some information on how to access the addressbook persistance directly

 

impl_configure_direct ()

For addressbook backends which support Direct Read Access, configure a backend instantiated on the client side for Direct Read Access, using data reported from the server via the get_direct_book method.

 

impl_set_locale ()

Store & remember the passed locale setting

 

impl_dup_locale ()

Return the currently set locale setting (must be a string duplicate, for thread safety).

 

impl_create_cursor ()

Create an EDataBookCursor

 

impl_delete_cursor ()

Delete an EDataBookCursor previously created by this backend

 

closed ()

A signal notifying that the backend was closed

 

shutdown ()

A signal notifying that the backend is being shut down

 

impl_contains_email ()

Checkes whether the backend contains an email address

 

impl_set_view_sort_fields ()

sets sort fields for "manual query" views; default implementation saves the values into internal structures, which can be read back with e_book_backend_dup_view_sort_fields(). Since 3.50

 

impl_get_view_n_total ()

retrieve how many contacts a "manual query" view has; default implementation returns value set by e_book_backend_set_view_n_total(). Since: 3.50

 

impl_dup_view_indices ()

retrieve indexes into an alphabet for contacts in the "manual query" view; default implementation returns value set by e_book_backend_set_view_indices(). Since: 3.50

 

impl_dup_view_contacts ()

returns contacts in the given range of the sorted "manual query" view; default implementation tracks view's connect and returns the contacts accordingly. Since: 3.50

 

gpointer reserved_padding[15];

   

Property Details

The “cache-dir” property

  “cache-dir”                char *

The backend's cache directory.

Owner: EBookBackend

Flags: Read / Write

Default value: NULL


The “proxy-resolver” property

  “proxy-resolver”           GProxyResolver *

The proxy resolver for this backend.

Owner: EBookBackend

Flags: Read


The “registry” property

  “registry”                 ESourceRegistry *

Data source registry.

Owner: EBookBackend

Flags: Read / Write / Construct Only


The “writable” property

  “writable”                 gboolean

Whether the backend will accept changes.

Owner: EBookBackend

Flags: Read / Write

Default value: FALSE

Signal Details

The “closed” signal

void
user_function (EBookBackend *backend,
               char         *sender,
               gpointer      user_data)

Emitted when a client destroys its EBookClient for backend .

Parameters

backend

the EBookBackend which emitted the signal

 

sender

the bus name that invoked the "close" method

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.10


The “shutdown” signal

void
user_function (EBookBackend *backend,
               gpointer      user_data)

Emitted when the last client destroys its EBookClient for backend . This signals the backend to begin final cleanup tasks such as synchronizing data to permanent storage.

Parameters

backend

the EBookBackend which emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.10