EBookBackend

## EBookBackend EBookBackend |

## Synopsis

    struct              EBookBackend;
    #define             CLIENT_BACKEND_PROPERTY_CAPABILITIES
    #define             BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS
    #define             BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS
    #define             BOOK_BACKEND_PROPERTY_REVISION
    const gchar *       e_book_backend_get_cache_dir        (EBookBackend *backend);
    gchar *             e_book_backend_dup_cache_dir        (EBookBackend *backend);
    void                e_book_backend_set_cache_dir        (EBookBackend *backend,
                                                             const gchar *cache_dir);
    EDataBook *         e_book_backend_ref_data_book        (EBookBackend *backend);
    void                e_book_backend_set_data_book        (EBookBackend *backend,
                                                             EDataBook *data_book);
    ESourceRegistry *   e_book_backend_get_registry         (EBookBackend *backend);
    gboolean            e_book_backend_get_writable         (EBookBackend *backend);
    void                e_book_backend_set_writable         (EBookBackend *backend,
                                                             gboolean writable);
    gboolean            e_book_backend_is_opened            (EBookBackend *backend);
    gboolean            e_book_backend_is_readonly          (EBookBackend *backend);
    gchar *             e_book_backend_get_backend_property (EBookBackend *backend,
                                                             const gchar *prop_name);
    gboolean            e_book_backend_open_sync            (EBookBackend *backend,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_backend_open                 (EBookBackend *backend,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_backend_open_finish          (EBookBackend *backend,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_backend_refresh_sync         (EBookBackend *backend,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_backend_refresh              (EBookBackend *backend,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_backend_refresh_finish       (EBookBackend *backend,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_backend_create_contacts_sync (EBookBackend *backend,
                                                             const gchar * const *vcards,
                                                             GQueue *out_contacts,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_backend_create_contacts      (EBookBackend *backend,
                                                             const gchar * const *vcards,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_backend_create_contacts_finish
                                                            (EBookBackend *backend,
                                                             GAsyncResult *result,
                                                             GQueue *out_contacts,
                                                             GError **error);
    gboolean            e_book_backend_modify_contacts_sync (EBookBackend *backend,
                                                             const gchar * const *vcards,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_backend_modify_contacts      (EBookBackend *backend,
                                                             const gchar * const *vcards,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_backend_modify_contacts_finish
                                                            (EBookBackend *backend,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_backend_remove_contacts_sync (EBookBackend *backend,
                                                             const gchar * const *uids,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                             const gchar * const *uids,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_backend_remove_contacts_finish
                                                            (EBookBackend *backend,
                                                             GAsyncResult *result,
                                                             GError **error);
    EContact *          e_book_backend_get_contact_sync     (EBookBackend *backend,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_backend_get_contact          (EBookBackend *backend,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    EContact *          e_book_backend_get_contact_finish   (EBookBackend *backend,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_backend_get_contact_list_sync
                                                            (EBookBackend *backend,
                                                             const gchar *query,
                                                             GQueue *out_contacts,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_backend_get_contact_list     (EBookBackend *backend,
                                                             const gchar *query,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_backend_get_contact_list_finish
                                                            (EBookBackend *backend,
                                                             GAsyncResult *result,
                                                             GQueue *out_contacts,
                                                             GError **error);
    gboolean            e_book_backend_get_contact_list_uids_sync
                                                            (EBookBackend *backend,
                                                             const gchar *query,
                                                             GQueue *out_uids,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_backend_get_contact_list_uids
                                                            (EBookBackend *backend,
                                                             const gchar *query,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_backend_get_contact_list_uids_finish
                                                            (EBookBackend *backend,
                                                             GAsyncResult *result,
                                                             GQueue *out_uids,
                                                             GError **error);
    void                e_book_backend_start_view           (EBookBackend *backend,
                                                             EDataBookView *view);
    void                e_book_backend_stop_view            (EBookBackend *backend,
                                                             EDataBookView *view);
    void                e_book_backend_add_view             (EBookBackend *backend,
                                                             EDataBookView *view);
    void                e_book_backend_remove_view          (EBookBackend *backend,
                                                             EDataBookView *view);
    GList *             e_book_backend_list_views           (EBookBackend *backend);
    void                e_book_backend_notify_update        (EBookBackend *backend,
                                                             const EContact *contact);
    void                e_book_backend_notify_remove        (EBookBackend *backend,
                                                             const gchar *id);
    void                e_book_backend_notify_complete      (EBookBackend *backend);
    void                e_book_backend_notify_error         (EBookBackend *backend,
                                                             const gchar *message);
    void                e_book_backend_notify_property_changed
                                                            (EBookBackend *backend,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);
    void                e_book_backend_sync                 (EBookBackend *backend);
    EDataBookDirect *   e_book_backend_get_direct_book      (EBookBackend *backend);
    void                e_book_backend_configure_direct     (EBookBackend *backend,
                                                             const gchar *config);

## Object Hierarchy

      GObject
       +----EBackend
             +----EBookBackend

## Properties

      "cache-dir"                gchar*                : Read / Write
      "registry"                 ESourceRegistry*      : Read / Write / Construct Only
      "writable"                 gboolean              : Read / Write

## Signals

      "closed"                                         : Run Last
      "shutdown"                                       : Run Last

## Description

## Details

### struct EBookBackend

    struct EBookBackend;

### CLIENT_BACKEND_PROPERTY_CAPABILITIES

    #define CLIENT_BACKEND_PROPERTY_CAPABILITIES		"capabilities"

FIXME: Document me.

Since 3.2

### BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

    #define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS		"required-fields"

FIXME: Document me.

Since 3.2

### BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

    #define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS		"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

### e_book_backend_get_cache_dir ()

    const gchar *       e_book_backend_get_cache_dir        (EBookBackend *backend);

Returns the cache directory path used by `backend`.

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

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

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

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

`backend` : | an EBookBackend
`data_book` : | an EDataBook

Since 3.10

### e_book_backend_get_registry ()

    ESourceRegistry *   e_book_backend_get_registry         (EBookBackend *backend);

Returns the data source registry to which "source" belongs.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`backend` : | an EBookBackend
`prop_name` : | property name, which changed
`prop_value` : | new property value

Since 3.2

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

`backend` : | an EBookbackend

Since 1.12

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

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

`backend` : | an EBookBackend
`config` : | The configuration string for the given backend

Since 3.8

## Property Details

### The `"cache-dir"` property

      "cache-dir"                gchar*                : Read / Write

The backend's cache directory.

Default value: NULL

### The `"registry"` property

      "registry"                 ESourceRegistry*      : Read / Write / Construct Only

Data source registry.

### The `"writable"` property

      "writable"                 gboolean              : Read / Write

Whether the backend will accept changes.

Default value: FALSE

## Signal Details

### The `"closed"` signal

    void                user_function                      (EBookBackend *backend,
                                                            gchar        *sender,
                                                            gpointer      user_data)      : Run Last

Emitted when a client destroys its EBookClient for `backend`.

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

Since 3.10

### The `"shutdown"` signal

    void                user_function                      (EBookBackend *backend,
                                                            gpointer      user_data)      : Run Last

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.

`backend` : | the EBookBackend which emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 3.10