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

## Types and Values

#define | CLIENT_BACKEND_PROPERTY_CAPABILITIES
#define | BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS
#define | BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS
#define | BOOK_BACKEND_PROPERTY_REVISION
struct | EBookBackend
struct | EBookBackendClass

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

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`

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

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 within call of `e_book_backend_notify_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,
                                         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 |
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,
                                    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 |
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,
                                         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 |
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,
                                    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 |
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,
                                         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 |
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,
                                    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 |
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`

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`

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

Since: 3.8

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

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]

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

Write all pending data to disk. This is only required under special circumstances (for example before a live backup) and should not be used in normal use.

#### Parameters

backend | an EBookBackend |

Since: 1.12

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

[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

### CLIENT_BACKEND_PROPERTY_CAPABILITIES

    #define             CLIENT_BACKEND_PROPERTY_CAPABILITIES

FIXME: Document me.

Since: 3.2

### BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

    #define             BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

FIXME: Document me.

Since: 3.2

### BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

    #define             BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

FIXME: Document me.

Since: 3.2

### BOOK_BACKEND_PROPERTY_REVISION

    #define BOOK_BACKEND_PROPERTY_REVISION			"revision"

The current overall revision string, this can be used as a quick check to see if data has changed at all since the last time the addressbook revision was observed.

Since: 3.4

### 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 *		(*get_backend_property) (EBookBackend *backend,
    						 const gchar *prop_name);

    	gboolean (*open_sync)		(EBookBackend *backend,
    						 GCancellable *cancellable,
    						 GError **error);
    	gboolean (*refresh_sync)		(EBookBackend *backend,
    						 GCancellable *cancellable,
    						 GError **error);
    	gboolean (*create_contacts_sync) (EBookBackend *backend,
    						 const gchar * const *vcards,
    						 GQueue *out_contacts,
    						 GCancellable *cancellable,
    						 GError **error);
    	gboolean (*modify_contacts_sync) (EBookBackend *backend,
    						 const gchar * const *vcards,
    						 GQueue *out_contacts,
    						 GCancellable *cancellable,
    						 GError **error);
    	gboolean (*remove_contacts_sync) (EBookBackend *backend,
    						 const gchar * const *uids,
    						 GCancellable *cancellable,
    						 GError **error);
    	EContact * (*get_contact_sync) (EBookBackend *backend,
    						 const gchar *uid,
    						 GCancellable *cancellable,
    						 GError **error);
    	gboolean (*get_contact_list_sync)
    						(EBookBackend *backend,
    						 const gchar *query,
    						 GQueue *out_contacts,
    						 GCancellable *cancellable,
    						 GError **error);

    	/* This method is optional.  By default, it simply calls
    	 * get_contact_list_sync() and extracts UID strings from
    	 * the matched EContacts.  Backends may override this if
    	 * they can implement it more efficiently. */
    	gboolean (*get_contact_list_uids_sync)
    						(EBookBackend *backend,
    						 const gchar *query,
    						 GQueue *out_uids,
    						 GCancellable *cancellable,
    						 GError **error);

    	/* These methods are deprecated and will be removed once all
    	 * known subclasses are converted to the new methods above. */
    	void		(*open)			(EBookBackend *backend,
    						 EDataBook *book,
    						 guint32 opid,
    						 GCancellable *cancellable,
    						 gboolean only_if_exists);
    	void		(*refresh)		(EBookBackend *backend,
    						 EDataBook *book,
    						 guint32 opid,
    						 GCancellable *cancellable);
    	void		(*create_contacts) (EBookBackend *backend,
    						 EDataBook *book,
    						 guint32 opid,
    						 GCancellable *cancellable,
    						 const GSList *vcards);
    	void		(*remove_contacts) (EBookBackend *backend,
    						 EDataBook *book,
    						 guint32 opid,
    						 GCancellable *cancellable,
    						 const GSList *id_list);
    	void		(*modify_contacts) (EBookBackend *backend,
    						 EDataBook *book,
    						 guint32 opid,
    						 GCancellable *cancellable,
    						 const GSList *vcards);
    	void		(*get_contact)		(EBookBackend *backend,
    						 EDataBook *book,
    						 guint32 opid,
    						 GCancellable *cancellable,
    						 const gchar *id);
    	void		(*get_contact_list) (EBookBackend *backend,
    						 EDataBook *book,
    						 guint32 opid,
    						 GCancellable *cancellable,
    						 const gchar *query);
    	void		(*get_contact_list_uids)
    						(EBookBackend *backend,
    						 EDataBook *book,
    						 guint32 opid,
    						 GCancellable *cancellable,
    						 const gchar *query);

    	void		(*start_view)		(EBookBackend *backend,
    						 EDataBookView *book_view);
    	void		(*stop_view)		(EBookBackend *backend,
    						 EDataBookView *book_view);

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

    	EDataBookDirect *
    			(*get_direct_book) (EBookBackend *backend);
    	void		(*configure_direct) (EBookBackend *backend,
    						 const gchar *config);

    	void		(*sync)			(EBookBackend *backend);

    	gboolean (*set_locale)		(EBookBackend *backend,
    						 const gchar *locale,
    						 GCancellable *cancellable,
    						 GError **error);
    	gchar *		(*dup_locale)		(EBookBackend *backend);
    	EDataBookCursor *
    			(*create_cursor) (EBookBackend *backend,
    						 EContactField *sort_fields,
    						 EBookCursorSortType *sort_types,
    						 guint n_fields,
    						 GError **error);
    	gboolean (*delete_cursor) (EBookBackend *backend,
    						 EDataBookCursor *cursor,
    						 GError **error);

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

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`. |
`get_backend_property` () | Fetch a property value by name from the backend |
`open_sync` () | Open the backend |
`refresh_sync` () | Refresh the backend |
`create_contacts_sync` () | Add and store the passed vcards |
`modify_contacts_sync` () | Modify the existing contacts using the passed vcards |
`remove_contacts_sync` () | Remove the contacts specified by the passed UIDs |
`get_contact_sync` () | Fetch a contact by UID |
`get_contact_list_sync` () | Fetch a list of contacts based on a search expression |
`get_contact_list_uids_sync` () | Fetch a list of contact UIDs based on a search expression (optional) |
`open` () | Deprecated method |
`refresh` () | Deprecated method |
`create_contacts` () | Deprecated method |
`remove_contacts` () | Deprecated method |
`modify_contacts` () | Deprecated method |
`get_contact` () | Deprecated method |
`get_contact_list` () | Deprecated method |
`get_contact_list_uids` () | Deprecated method |
`start_view` () | Start up the specified view |
`stop_view` () | Stop the specified view |
`notify_update` () | Notify changes which might have occured for a given contact |
`get_direct_book` () | For addressbook backends which support Direct Read Access, report some information on how to access the addressbook persistance directly |
`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. |
`sync` () | Sync the backend's persistance |
`set_locale` () | Store & remember the passed locale setting |
`dup_locale` () | Return the currently set locale setting (must be a string duplicate, for thread safety). |
`create_cursor` () | Create an EDataBookCursor |
`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 |