EBookBackend: Evolution-Data-Server Reference Manual

## 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 ()
GSimpleAsyncResult * | e_book_backend_prepare_for_completion ()
void | (*EBookBackendCustomOpFunc) ()
void | e_book_backend_schedule_custom_operation ()

## 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

struct | EBookBackend
struct | EBookBackendClass

## 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

### e_book_backend_prepare_for_completion ()

    GSimpleAsyncResult *
    e_book_backend_prepare_for_completion (EBookBackend *backend,
                                           guint32 opid,
                                           GQueue **result_queue);

Obtains the GSimpleAsyncResult for `opid` and sets `result_queue` as a place to deposit results prior to completing the GSimpleAsyncResult.

This is a temporary function to serve EDataBook's "respond" functions until they can be removed. Nothing else should be calling this function.

#### Parameters

backend | an EBookBackend |
opid | an operation ID given to EDataBook |
result_queue | return location for a GQueue, or `NULL` |

#### Returns

a GSimpleAsyncResult.

[transfer full]

Since: 3.10

### 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

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

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

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 |
gpointer `reserved_padding`[19]; |  |

## 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