## EBookBackend

EBookBackend — An abstract class for implementing addressbook backends

## Synopsis

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

    #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;
    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);
    GProxyResolver *    e_book_backend_ref_proxy_resolver   (EBookBackend *backend);
    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);
    EDataBookDirect *   e_book_backend_get_direct_book      (EBookBackend *backend);
    void                e_book_backend_configure_direct     (EBookBackend *backend,
                                                             const gchar *config);
    void                e_book_backend_sync                 (EBookBackend *backend);
    gboolean            e_book_backend_set_locale           (EBookBackend *backend,
                                                             const gchar *locale,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gchar *             e_book_backend_dup_locale           (EBookBackend *backend);
    EDataBookCursor *   e_book_backend_create_cursor        (EBookBackend *backend,
                                                             EContactField *sort_fields,
                                                             EBookCursorSortType *sort_types,
                                                             guint n_fields,
                                                             GError **error);
    gboolean            e_book_backend_delete_cursor        (EBookBackend *backend,
                                                             EDataBookCursor *cursor,
                                                             GError **error);
    GSimpleAsyncResult * e_book_backend_prepare_for_completion
                                                            (EBookBackend *backend,
                                                             guint32 opid,
                                                             GQueue **result_queue);

## Description

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

## Details

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

gboolean `use_serial_dispatch_queue`; | Whether a serial dispatch queue should be used for this backend or not.
`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

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

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

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

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

`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

`backend` : | an EBookbackend

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.

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

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

### Note

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

`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