## EBook

EBook — The primary Evolution addressbook client object.

## Synopsis

                        EBook;
    EBook *             e_book_new                          (ESource *source,
                                                             GError **error);
    EBook *             e_book_new_default_addressbook      (GError **error);
    EBook *             e_book_new_from_uri                 (const gchar *uri,
                                                             GError **error);
    EBook *             e_book_new_system_addressbook       (GError **error);
    gboolean            e_book_set_default_addressbook      (EBook *book,
                                                             GError **error);
    gboolean            e_book_set_default_source           (ESource *source,
                                                             GError **error);
    gboolean            e_book_remove                       (EBook *book,
                                                             GError **error);
    gboolean            e_book_open                         (EBook *book,
                                                             gboolean only_if_exists,
                                                             GError **error);
    gboolean            e_book_get_supported_fields         (EBook *book,
                                                             GList **fields,
                                                             GError **error);
    gboolean            e_book_get_supported_auth_methods   (EBook *book,
                                                             GList **auth_methods,
                                                             GError **error);
    gboolean            e_book_get_required_fields          (EBook *book,
                                                             GList **fields,
                                                             GError **error);
    ESource *           e_book_get_source                   (EBook *book);
    gboolean            e_book_is_online                    (EBook *book);
    gboolean            e_book_is_opened                    (EBook *book);
    gboolean            e_book_authenticate_user            (EBook *book,
                                                             const gchar *user,
                                                             const gchar *passwd,
                                                             const gchar *auth_method,
                                                             GError **error);
    gboolean            e_book_get_contact                  (EBook *book,
                                                             const gchar *id,
                                                             EContact **contact,
                                                             GError **error);
    gboolean            e_book_remove_contact               (EBook *book,
                                                             const gchar *id,
                                                             GError **error);
    gboolean            e_book_remove_contacts              (EBook *book,
                                                             GList *ids,
                                                             GError **error);
    gboolean            e_book_add_contact                  (EBook *book,
                                                             EContact *contact,
                                                             GError **error);
    gboolean            e_book_commit_contact               (EBook *book,
                                                             EContact *contact,
                                                             GError **error);
    gboolean            e_book_get_book_view                (EBook *book,
                                                             EBookQuery *query,
                                                             GList *requested_fields,
                                                             gint max_results,
                                                             EBookView **book_view,
                                                             GError **error);
    gboolean            e_book_get_contacts                 (EBook *book,
                                                             EBookQuery *query,
                                                             GList **contacts,
                                                             GError **error);
    gboolean            e_book_get_changes                  (EBook *book,
                                                             const gchar *changeid,
                                                             GList **changes,
                                                             GError **error);
    void                e_book_free_change_list             (GList *change_list);
    const gchar *       e_book_get_uri                      (EBook *book);
    const gchar *       e_book_get_static_capabilities      (EBook *book,
                                                             GError **error);
    gboolean            e_book_check_static_capability      (EBook *book,
                                                             const gchar *cap);
    gboolean            e_book_is_writable                  (EBook *book);
    gboolean            e_book_cancel                       (EBook *book,
                                                             GError **error);
    gboolean            e_book_cancel_async_op              (EBook *book,
                                                             GError **error);
    gboolean            e_book_get_self                     (EContact **contact,
                                                             EBook **book,
                                                             GError **error);
    gboolean            e_book_set_self                     (EBook *book,
                                                             EContact *contact,
                                                             GError **error);
    gboolean            e_book_is_self                      (EContact *contact);
    gboolean            e_book_get_addressbooks             (ESourceList **addressbook_sources,
                                                             GError **error);
    #define             e_return_error_if_fail              (expr,
                                                             error_code)
    #define             e_return_async_error_if_fail        (expr,
                                                             error)
    #define             e_return_ex_async_error_val_if_fail (expr,
                                                             error)
    void                (*EBookAsyncCallback)               (EBook *book,
                                                             const GError *error,
                                                             gpointer closure);
    void                (*EBookOpenProgressCallback)        (EBook *book,
                                                             const gchar *status_message,
                                                             gshort percent,
                                                             gpointer closure);
    void                (*EBookIdAsyncCallback)             (EBook *book,
                                                             const GError *error,
                                                             const gchar *id,
                                                             gpointer closure);
    void                (*EBookContactAsyncCallback)        (EBook *book,
                                                             const GError *error,
                                                             EContact *contact,
                                                             gpointer closure);
    void                (*EBookListAsyncCallback)           (EBook *book,
                                                             const GError *error,
                                                             GList *list,
                                                             gpointer closure);
    void                (*EBookBookViewAsyncCallback)       (EBook *book,
                                                             const GError *error,
                                                             EBookView *book_view,
                                                             gpointer closure);
    void                (*EBookEListAsyncCallback)          (EBook *book,
                                                             const GError *error,
                                                             EList *list,
                                                             gpointer closure);
    void                (*EBookCallback)                    (EBook *book,
                                                             EBookStatus status,
                                                             gpointer closure);
    void                (*EBookIdCallback)                  (EBook *book,
                                                             EBookStatus status,
                                                             const gchar *id,
                                                             gpointer closure);
    void                (*EBookEListCallback)               (EBook *book,
                                                             EBookStatus status,
                                                             EList *list,
                                                             gpointer closure);
    void                (*EBookListCallback)                (EBook *book,
                                                             EBookStatus status,
                                                             GList *list,
                                                             gpointer closure);
    void                (*EBookContactCallback)             (EBook *book,
                                                             EBookStatus status,
                                                             EContact *contact,
                                                             gpointer closure);
    void                (*EBookBookViewCallback)            (EBook *book,
                                                             EBookStatus status,
                                                             EBookView *book_view,
                                                             gpointer closure);
    gboolean            e_book_open_async                   (EBook *book,
                                                             gboolean only_if_exists,
                                                             EBookAsyncCallback open_response,
                                                             gpointer closure);
    gboolean            e_book_remove_async                 (EBook *book,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_get_supported_fields_async   (EBook *book,
                                                             EBookEListAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_get_supported_auth_methods_async
                                                            (EBook *book,
                                                             EBookEListAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_authenticate_user_async      (EBook *book,
                                                             const gchar *user,
                                                             const gchar *passwd,
                                                             const gchar *auth_method,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_get_contact_async            (EBook *book,
                                                             const gchar *id,
                                                             EBookContactAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_get_contacts_async           (EBook *book,
                                                             EBookQuery *query,
                                                             EBookListAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_remove_contact_async         (EBook *book,
                                                             EContact *contact,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_remove_contact_by_id_async   (EBook *book,
                                                             const gchar *id,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_remove_contacts_async        (EBook *book,
                                                             GList *ids,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_add_contact_async            (EBook *book,
                                                             EContact *contact,
                                                             EBookIdAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_commit_contact_async         (EBook *book,
                                                             EContact *contact,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_get_book_view_async          (EBook *book,
                                                             EBookQuery *query,
                                                             GList *requested_fields,
                                                             gint max_results,
                                                             EBookBookViewAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_get_changes_async            (EBook *book,
                                                             const gchar *changeid,
                                                             EBookListAsyncCallback cb,
                                                             gpointer closure);
    gboolean            e_book_get_required_fields_async    (EBook *book,
                                                             EBookEListAsyncCallback cb,
                                                             gpointer closure);
    guint               e_book_async_open                   (EBook *book,
                                                             gboolean only_if_exists,
                                                             EBookCallback open_response,
                                                             gpointer closure);
    guint               e_book_async_remove                 (EBook *book,
                                                             EBookCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_supported_fields   (EBook *book,
                                                             EBookEListCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_supported_auth_methods
                                                            (EBook *book,
                                                             EBookEListCallback cb,
                                                             gpointer closure);
    guint               e_book_async_authenticate_user      (EBook *book,
                                                             const gchar *user,
                                                             const gchar *passwd,
                                                             const gchar *auth_method,
                                                             EBookCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_contact            (EBook *book,
                                                             const gchar *id,
                                                             EBookContactCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_contacts           (EBook *book,
                                                             EBookQuery *query,
                                                             EBookListCallback cb,
                                                             gpointer closure);
    guint               e_book_async_remove_contact         (EBook *book,
                                                             EContact *contact,
                                                             EBookCallback cb,
                                                             gpointer closure);
    guint               e_book_async_remove_contact_by_id   (EBook *book,
                                                             const gchar *id,
                                                             EBookCallback cb,
                                                             gpointer closure);
    guint               e_book_async_remove_contacts        (EBook *book,
                                                             GList *ids,
                                                             EBookCallback cb,
                                                             gpointer closure);
    gboolean            e_book_async_add_contact            (EBook *book,
                                                             EContact *contact,
                                                             EBookIdCallback cb,
                                                             gpointer closure);
    guint               e_book_async_commit_contact         (EBook *book,
                                                             EContact *contact,
                                                             EBookCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_book_view          (EBook *book,
                                                             EBookQuery *query,
                                                             GList *requested_fields,
                                                             gint max_results,
                                                             EBookBookViewCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_changes            (EBook *book,
                                                             const gchar *changeid,
                                                             EBookListCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_required_fields    (EBook *book,
                                                             EBookEListCallback cb,
                                                             gpointer closure);

## Object Hierarchy

      GObject
       +----EBook

## Signals

      "auth-required"                                  : Run Last
      "backend-died"                                   : Run Last
      "connection-status"                              : Run Last
      "writable-status"                                : Run Last

## Description

The old asynchronous API was deprecated since 3.0 and is replaced with their an equivalent version which has a detailed GError structure in the asynchronous callback, instead of a status code only.

As an example, `e_book_async_open()` is replaced by `e_book_open_async()`.

Represents a complete addressbook. Event notifications and callbacks go to the EBookListener. Contrast with EBookView, which represents a search of the addressbook.

## Details

### EBook

    typedef struct _EBook EBook;

EBook has no publicly available members.

### e_book_new ()

    EBook *             e_book_new                          (ESource *source,
                                                             GError **error);

Creates a new EBook corresponding to the given source. There are only two operations that are valid on this book at this point: `e_book_open()`, and `e_book_remove()`.

`source` : | An ESource pointer
`error` : | A GError pointer
Returns : | a new but unopened EBook.

### e_book_new_default_addressbook ()

    EBook *             e_book_new_default_addressbook      (GError **error);

Creates a new EBook corresponding to the user's default address book. See the documentation for `e_book_new()` for further information.

`error` : | return location for a GError, or `NULL`
Returns : | a new but unopened EBook

### e_book_new_from_uri ()

    EBook *             e_book_new_from_uri                 (const gchar *uri,
                                                             GError **error);

Creates a new EBook corresponding to the given uri. See the documentation for e_book_new for further information.

`uri` : | the URI to load
`error` : | A GError pointer
Returns : | a new but unopened EBook.

### e_book_new_system_addressbook ()

    EBook *             e_book_new_system_addressbook       (GError **error);

Creates a new EBook corresponding to the user's system addressbook. See the documentation for e_book_new for further information.

`error` : | A GError pointer
Returns : | a new but unopened EBook.

### e_book_set_default_addressbook ()

    gboolean            e_book_set_default_addressbook      (EBook *book,
                                                             GError **error);

sets the ESource of the EBook as the "default" addressbook. This is the source that will be loaded in the e_book_get_default_addressbook call.

`book` : | An EBook pointer
`error` : | A GError pointer
Returns : | `TRUE` if the setting was stored in libebook's ESourceList, otherwise `FALSE`.

### e_book_set_default_source ()

    gboolean            e_book_set_default_source           (ESource *source,
                                                             GError **error);

sets `source` as the "default" addressbook. This is the source that will be loaded in the e_book_get_default_addressbook call.

`source` : | An ESource pointer
`error` : | A GError pointer
Returns : | `TRUE` if the setting was stored in libebook's ESourceList, otherwise `FALSE`.

### e_book_remove ()

    gboolean            e_book_remove                       (EBook *book,
                                                             GError **error);

Removes the backing data for this EBook. For example, with the file backend this deletes the database file. You cannot get it back!

`book` : | an EBook
`error` : | a GError to set on failure
Returns : | `TRUE` on success, `FALSE` on failure.

### e_book_open ()

    gboolean            e_book_open                         (EBook *book,
                                                             gboolean only_if_exists,
                                                             GError **error);

Opens the addressbook, making it ready for queries and other operations.

`book` : | an EBook
`only_if_exists` : | if `TRUE`, fail if this book doesn't already exist, otherwise create it first
`error` : | a GError to set on failure
Returns : | `TRUE` if the book was successfully opened, `FALSE` otherwise.

### e_book_get_supported_fields ()

    gboolean            e_book_get_supported_fields         (EBook *book,
                                                             GList **fields,
                                                             GError **error);

Gets a list of fields that can be stored for contacts in this `book`. Other fields may be discarded. The list will contain pointers to allocated strings, and both the GList and the strings must be freed by the caller.

`book` : | an EBook
`fields` : | a GList of fields to set on success
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_get_supported_auth_methods ()

    gboolean            e_book_get_supported_auth_methods   (EBook *book,
                                                             GList **auth_methods,
                                                             GError **error);

Queries `book` for the list of authentication methods it supports. The list will contain pointers to allocated strings, and both the GList and the strings must be freed by the caller.

`book` : | an EBook
`auth_methods` : | a GList of auth methods to set on success
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_get_required_fields ()

    gboolean            e_book_get_required_fields          (EBook *book,
                                                             GList **fields,
                                                             GError **error);

Gets a list of fields that are required to be filled in for all contacts in this `book`. The list will contain pointers to allocated strings, and both the GList and the strings must be freed by the caller.

`book` : | an EBook
`fields` : | a GList of fields to set on success
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise.

### e_book_get_source ()

    ESource *           e_book_get_source                   (EBook *book);

Get the ESource that this book has loaded.

`book` : | an EBook
Returns : | The source.

### e_book_is_online ()

    gboolean            e_book_is_online                    (EBook *book);

Check if this book is connected.

`book` : | an EBook
Returns : | `TRUE` if this book is connected, otherwise `FALSE`.

### e_book_is_opened ()

    gboolean            e_book_is_opened                    (EBook *book);

Check if this book has been opened.

`book` : | and EBook
Returns : | `TRUE` if this book has been opened, otherwise `FALSE`.

### e_book_authenticate_user ()

    gboolean            e_book_authenticate_user            (EBook *book,
                                                             const gchar *user,
                                                             const gchar *passwd,
                                                             const gchar *auth_method,
                                                             GError **error);

Authenticates `user` with `passwd`, using the auth method `auth_method`. `auth_method` must be one of the authentication methods returned using e_book_get_supported_auth_methods.

`book` : | an EBook
`user` : | a string
`passwd` : | a string
`auth_method` : | a string
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_get_contact ()

    gboolean            e_book_get_contact                  (EBook *book,
                                                             const gchar *id,
                                                             EContact **contact,
                                                             GError **error);

Fills in `contact` with the contents of the vcard in `book` corresponding to `id`.

`book` : | an EBook
`id` : | a unique string ID specifying the contact
`contact` : | an EContact. [out][transfer: full]
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_remove_contact ()

    gboolean            e_book_remove_contact               (EBook *book,
                                                             const gchar *id,
                                                             GError **error);

Removes the contact with id `id` from `book`.

`book` : | an EBook
`id` : | a string
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_remove_contacts ()

    gboolean            e_book_remove_contacts              (EBook *book,
                                                             GList *ids,
                                                             GError **error);

Removes the contacts with ids from the list `ids` from `book`. This is always more efficient than calling `e_book_remove_contact()` if you have more than one id to remove, as some backends can implement it as a batch request.

`book` : | an EBook
`ids` : | an GList of const gchar *id's
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_add_contact ()

    gboolean            e_book_add_contact                  (EBook *book,
                                                             EContact *contact,
                                                             GError **error);

Adds `contact` to `book`.

`book` : | an EBook
`contact` : | an EContact
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise.

### e_book_commit_contact ()

    gboolean            e_book_commit_contact               (EBook *book,
                                                             EContact *contact,
                                                             GError **error);

Applies the changes made to `contact` to the stored version in `book`.

`book` : | an EBook
`contact` : | an EContact
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_get_book_view ()

    gboolean            e_book_get_book_view                (EBook *book,
                                                             EBookQuery *query,
                                                             GList *requested_fields,
                                                             gint max_results,
                                                             EBookView **book_view,
                                                             GError **error);

Query `book` with `query`, creating a EBookView in `book_view` with the fields specified by `requested_fields` and limited at `max_results` records. On an error, `error` is set and `FALSE` returned.

`book` : | an EBook
`query` : | an EBookQuery
`requested_fields` : | a GList containing the names of fields to return, or NULL for all
`max_results` : | the maximum number of contacts to show (or 0 for all)
`book_view` : | A EBookView pointer, will be set to the view
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_get_contacts ()

    gboolean            e_book_get_contacts                 (EBook *book,
                                                             EBookQuery *query,
                                                             GList **contacts,
                                                             GError **error);

Query `book` with `query`, setting `contacts` to the list of contacts which matched. On failed, `error` will be set and `FALSE` returned.

`book` : | an EBook
`query` : | an EBookQuery
`contacts` : | a GList pointer, will be set to the list of contacts
`error` : | a GError to set on failure
Returns : | `TRUE` on success, `FALSE` otherwise

### e_book_get_changes ()

    gboolean            e_book_get_changes                  (EBook *book,
                                                             const gchar *changeid,
                                                             GList **changes,
                                                             GError **error);

Get the set of changes since the previous call to e_book_get_changes for a given change ID.

`book` : | an EBook
`changeid` : | the change ID
`changes` : | return location for a GList of EBookChange items
`error` : | a GError to set on failure.
Returns : | TRUE on success, FALSE otherwise

### e_book_free_change_list ()

    void                e_book_free_change_list             (GList *change_list);

Free the contents of change_list, and the list itself.

`change_list` : | a GList of EBookChange items

### e_book_get_uri ()

    const gchar *       e_book_get_uri                      (EBook *book);

Get the URI that this book has loaded. This string should not be freed.

`book` : | an EBook
Returns : | The URI.

### e_book_get_static_capabilities ()

    const gchar *       e_book_get_static_capabilities      (EBook *book,
                                                             GError **error);

Get the list of capabilities which the backend for this address book supports. This string should not be freed.

`book` : | an EBook
`error` : | an GError to set on failure
Returns : | The capabilities list

### e_book_check_static_capability ()

    gboolean            e_book_check_static_capability      (EBook *book,
                                                             const gchar *cap);

Check to see if the backend for this address book supports the capability `cap`.

`book` : | an EBook
`cap` : | A capability string
Returns : | `TRUE` if the backend supports `cap`, `FALSE` otherwise.

### e_book_is_writable ()

    gboolean            e_book_is_writable                  (EBook *book);

Check if this book is writable.

`book` : | an EBook
Returns : | `TRUE` if this book is writable, otherwise `FALSE`.

### e_book_cancel ()

    gboolean            e_book_cancel                       (EBook *book,
                                                             GError **error);

Used to cancel an already running operation on `book`. This function makes a synchronous CORBA to the backend telling it to cancel the operation. If the operation wasn't cancellable (either transiently or permanently) or had already comopleted on the server side, this function will return E_BOOK_STATUS_COULD_NOT_CANCEL, and the operation will continue uncancelled. If the operation could be cancelled, this function will return E_BOOK_ERROR_OK, and the blocked e_book function corresponding to current operation will return with a status of E_BOOK_STATUS_CANCELLED.

`book` : | an EBook
`error` : | a GError to set on failure
Returns : | `TRUE` on success, `FALSE` otherwise

### e_book_cancel_async_op ()

    gboolean            e_book_cancel_async_op              (EBook *book,
                                                             GError **error);

Similar to above e_book_cancel function, only cancels last, still running, asynchronous operation.

`book` : |
`error` : |
Returns : |

Since 2.24

### e_book_get_self ()

    gboolean            e_book_get_self                     (EContact **contact,
                                                             EBook **book,
                                                             GError **error);

Get the EContact referring to the user of the address book and set it in `contact` and `book`.

`contact` : | an EContact pointer to set
`book` : | an EBook pointer to set
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, otherwise `FALSE`.

### e_book_set_self ()

    gboolean            e_book_set_self                     (EBook *book,
                                                             EContact *contact,
                                                             GError **error);

Specify that `contact` residing in `book` is the EContact that refers to the user of the address book.

`book` : | an EBook
`contact` : | an EContact
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise.

### e_book_is_self ()

    gboolean            e_book_is_self                      (EContact *contact);

Check if `contact` is the user of the address book.

`contact` : | an EContact
Returns : | `TRUE` if `contact` is the user, `FALSE` otherwise.

### e_book_get_addressbooks ()

    gboolean            e_book_get_addressbooks             (ESourceList **addressbook_sources,
                                                             GError **error);

Populate *addressbook_sources with the list of all sources which have been added to Evolution.

`addressbook_sources` : | A pointer to a ESourceList* to set. [out]
`error` : | A pointer to a GError* to set on error
Returns : | `TRUE` if `addressbook_sources` was set, otherwise `FALSE`.

### e_return_error_if_fail()

    #define             e_return_error_if_fail(expr,error_code)

FIXME Document me!

`expr` : |
`error_code` : |

Since 2.30

### e_return_async_error_if_fail()

    #define             e_return_async_error_if_fail(expr, error)

`expr` : |
`error` : |

Since 2.32

### e_return_ex_async_error_val_if_fail()

    #define             e_return_ex_async_error_val_if_fail(expr, error)

`expr` : |
`error` : |

Since 2.32

### EBookAsyncCallback ()

    void                (*EBookAsyncCallback)               (EBook *book,
                                                             const GError *error,
                                                             gpointer closure);

`book` : |
`error` : |
`closure` : |

Since 2.32

### EBookOpenProgressCallback ()

    void                (*EBookOpenProgressCallback)        (EBook *book,
                                                             const gchar *status_message,
                                                             gshort percent,
                                                             gpointer closure);

`book` : |
`status_message` : |
`percent` : |
`closure` : |

Since 2.32

### EBookIdAsyncCallback ()

    void                (*EBookIdAsyncCallback)             (EBook *book,
                                                             const GError *error,
                                                             const gchar *id,
                                                             gpointer closure);

`book` : |
`error` : |
`id` : |
`closure` : |

Since 2.32

### EBookContactAsyncCallback ()

    void                (*EBookContactAsyncCallback)        (EBook *book,
                                                             const GError *error,
                                                             EContact *contact,
                                                             gpointer closure);

`book` : |
`error` : |
`contact` : |
`closure` : |

Since 2.32

### EBookListAsyncCallback ()

    void                (*EBookListAsyncCallback)           (EBook *book,
                                                             const GError *error,
                                                             GList *list,
                                                             gpointer closure);

`book` : |
`error` : |
`list` : |
`closure` : |

Since 2.32

### EBookBookViewAsyncCallback ()

    void                (*EBookBookViewAsyncCallback)       (EBook *book,
                                                             const GError *error,
                                                             EBookView *book_view,
                                                             gpointer closure);

`book` : |
`error` : |
`book_view` : |
`closure` : |

Since 2.32

### EBookEListAsyncCallback ()

    void                (*EBookEListAsyncCallback)          (EBook *book,
                                                             const GError *error,
                                                             EList *list,
                                                             gpointer closure);

`book` : |
`error` : |
`list` : |
`closure` : |

Since 2.32

### EBookCallback ()

    void                (*EBookCallback)                    (EBook *book,
                                                             EBookStatus status,
                                                             gpointer closure);

### Warning

`EBookCallback` is deprecated and should not be used in newly-written code.

`book` : |
`status` : |
`closure` : |

### EBookIdCallback ()

    void                (*EBookIdCallback)                  (EBook *book,
                                                             EBookStatus status,
                                                             const gchar *id,
                                                             gpointer closure);

### Warning

`EBookIdCallback` is deprecated and should not be used in newly-written code.

`book` : |
`status` : |
`id` : |
`closure` : |

### EBookEListCallback ()

    void                (*EBookEListCallback)               (EBook *book,
                                                             EBookStatus status,
                                                             EList *list,
                                                             gpointer closure);

### Warning

`EBookEListCallback` is deprecated and should not be used in newly-written code.

`book` : |
`status` : |
`list` : |
`closure` : |

### EBookListCallback ()

    void                (*EBookListCallback)                (EBook *book,
                                                             EBookStatus status,
                                                             GList *list,
                                                             gpointer closure);

### Warning

`EBookListCallback` is deprecated and should not be used in newly-written code.

`book` : |
`status` : |
`list` : |
`closure` : |

### EBookContactCallback ()

    void                (*EBookContactCallback)             (EBook *book,
                                                             EBookStatus status,
                                                             EContact *contact,
                                                             gpointer closure);

### Warning

`EBookContactCallback` is deprecated and should not be used in newly-written code.

`book` : |
`status` : |
`contact` : |
`closure` : |

### EBookBookViewCallback ()

    void                (*EBookBookViewCallback)            (EBook *book,
                                                             EBookStatus status,
                                                             EBookView *book_view,
                                                             gpointer closure);

### Warning

`EBookBookViewCallback` is deprecated and should not be used in newly-written code.

`book` : |
`status` : |
`book_view` : |
`closure` : |

### e_book_open_async ()

    gboolean            e_book_open_async                   (EBook *book,
                                                             gboolean only_if_exists,
                                                             EBookAsyncCallback open_response,
                                                             gpointer closure);

Opens the addressbook, making it ready for queries and other operations. This function does not block.

`book` : | an EBook
`only_if_exists` : | if `TRUE`, fail if this book doesn't already exist, otherwise create it first
`open_response` : | a function to call when the operation finishes. [scope call]
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise.

Since 2.32

### e_book_remove_async ()

    gboolean            e_book_remove_async                 (EBook *book,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);

Remove the backing data for this EBook. For example, with the file backend this deletes the database file. You cannot get it back!

`book` : | an EBook
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise.

Since 2.32

### e_book_get_supported_fields_async ()

    gboolean            e_book_get_supported_fields_async   (EBook *book,
                                                             EBookEListAsyncCallback cb,
                                                             gpointer closure);

Gets a list of fields that can be stored for contacts in this `book`. Other fields may be discarded. This function does not block.

`book` : | an EBook
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 2.32

### e_book_get_supported_auth_methods_async ()

    gboolean            e_book_get_supported_auth_methods_async
                                                            (EBook *book,
                                                             EBookEListAsyncCallback cb,
                                                             gpointer closure);

Queries `book` for the list of authentication methods it supports. This function does not block.

`book` : | an EBook
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 2.32

### e_book_authenticate_user_async ()

    gboolean            e_book_authenticate_user_async      (EBook *book,
                                                             const gchar *user,
                                                             const gchar *passwd,
                                                             const gchar *auth_method,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);

Authenticate `user` with `passwd`, using the auth method `auth_method`. `auth_method` must be one of the authentication methods returned using e_book_get_supported_auth_methods. This function does not block.

`book` : | an EBook
`user` : | user name
`passwd` : | password
`auth_method` : | string indicating authentication method
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise.

Since 2.32

### e_book_get_contact_async ()

    gboolean            e_book_get_contact_async            (EBook *book,
                                                             const gchar *id,
                                                             EBookContactAsyncCallback cb,
                                                             gpointer closure);

Retrieves a contact specified by `id` from `book`.

`book` : | an EBook
`id` : | a unique string ID specifying the contact
`cb` : | function to call when operation finishes
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise

Since 2.32

### e_book_get_contacts_async ()

    gboolean            e_book_get_contacts_async           (EBook *book,
                                                             EBookQuery *query,
                                                             EBookListAsyncCallback cb,
                                                             gpointer closure);

Query `book` with `query`.

`book` : | an EBook
`query` : | an EBookQuery
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `FALSE` on success, `TRUE` otherwise

Since 2.32

### e_book_remove_contact_async ()

    gboolean            e_book_remove_contact_async         (EBook *book,
                                                             EContact *contact,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);

Removes `contact` from `book`.

`book` : | an EBook
`contact` : | an EContact
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise

Since 2.32

### e_book_remove_contact_by_id_async ()

    gboolean            e_book_remove_contact_by_id_async   (EBook *book,
                                                             const gchar *id,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);

Removes the contact with id `id` from `book`.

`book` : | an EBook
`id` : | a unique ID string specifying the contact
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise

Since 2.32

### e_book_remove_contacts_async ()

    gboolean            e_book_remove_contacts_async        (EBook *book,
                                                             GList *ids,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);

Removes the contacts with ids from the list `ids` from `book`. This is always more efficient than calling `e_book_remove_contact()` if you have more than one id to remove, as some backends can implement it as a batch request.

`book` : | an EBook
`ids` : | a GList of const gchar *id's
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise

Since 2.32

### e_book_add_contact_async ()

    gboolean            e_book_add_contact_async            (EBook *book,
                                                             EContact *contact,
                                                             EBookIdAsyncCallback cb,
                                                             gpointer closure);

Adds `contact` to `book` without blocking.

`book` : | an EBook
`contact` : | an EContact
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if the operation was started, `FALSE` otherwise.

Since 2.32

### e_book_commit_contact_async ()

    gboolean            e_book_commit_contact_async         (EBook *book,
                                                             EContact *contact,
                                                             EBookAsyncCallback cb,
                                                             gpointer closure);

Applies the changes made to `contact` to the stored version in `book` without blocking.

`book` : | an EBook
`contact` : | an EContact
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if the operation was started, `FALSE` otherwise.

Since 2.32

### e_book_get_book_view_async ()

    gboolean            e_book_get_book_view_async          (EBook *book,
                                                             EBookQuery *query,
                                                             GList *requested_fields,
                                                             gint max_results,
                                                             EBookBookViewAsyncCallback cb,
                                                             gpointer closure);

Query `book` with `query`, creating a EBookView with the fields specified by `requested_fields` and limited at `max_results` records.

`book` : | an EBook
`query` : | an EBookQuery
`requested_fields` : | a GList containing the names of fields to return, or NULL for all
`max_results` : | the maximum number of contacts to show (or 0 for all)
`cb` : | a function to call when the operation finishes. [scope call]
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise

Since 2.32

### e_book_get_changes_async ()

    gboolean            e_book_get_changes_async            (EBook *book,
                                                             const gchar *changeid,
                                                             EBookListAsyncCallback cb,
                                                             gpointer closure);

Get the set of changes since the previous call to e_book_async_get_changes for a given change ID.

`book` : | an EBook
`changeid` : | the change ID
`cb` : | function to call when operation finishes
`closure` : | data to pass to callback function
Returns : | TRUE on success, FALSE otherwise

Since 2.32

### e_book_get_required_fields_async ()

    gboolean            e_book_get_required_fields_async    (EBook *book,
                                                             EBookEListAsyncCallback cb,
                                                             gpointer closure);

Gets a list of fields that are required to be filled in for all contacts in this `book`. This function does not block.

`book` : | an EBook
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if the operation was started, `FALSE` otherwise.

Since 2.32

### e_book_async_open ()

    guint               e_book_async_open                   (EBook *book,
                                                             gboolean only_if_exists,
                                                             EBookCallback open_response,
                                                             gpointer closure);

### Warning

`e_book_async_open` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_open_async()` instead.

Opens the addressbook, making it ready for queries and other operations. This function does not block.

`book` : | an EBook
`only_if_exists` : | if `TRUE`, fail if this book doesn't already exist, otherwise create it first
`open_response` : | a function to call when the operation finishes. [scope call][closure closure]
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise.

### e_book_async_remove ()

    guint               e_book_async_remove                 (EBook *book,
                                                             EBookCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_remove` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_remove_async()` instead.

Remove the backing data for this EBook. For example, with the file backend this deletes the database file. You cannot get it back!

`book` : | an EBook
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise.

### e_book_async_get_supported_fields ()

    guint               e_book_async_get_supported_fields   (EBook *book,
                                                             EBookEListCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_get_supported_fields` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_get_supported_fields_async()` instead.

Gets a list of fields that can be stored for contacts in this `book`. Other fields may be discarded. This function does not block.

`book` : | an EBook
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise.

### e_book_async_get_supported_auth_methods ()

    guint               e_book_async_get_supported_auth_methods
                                                            (EBook *book,
                                                             EBookEListCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_get_supported_auth_methods` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_get_supported_auth_methods_async()` instead.

Queries `book` for the list of authentication methods it supports. This function does not block.

`book` : | an EBook
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise.

### e_book_async_authenticate_user ()

    guint               e_book_async_authenticate_user      (EBook *book,
                                                             const gchar *user,
                                                             const gchar *passwd,
                                                             const gchar *auth_method,
                                                             EBookCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_authenticate_user` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_authenticate_user_async()` instead.

Authenticate `user` with `passwd`, using the auth method `auth_method`. `auth_method` must be one of the authentication methods returned using e_book_get_supported_auth_methods. This function does not block.

`book` : | an EBook
`user` : | user name
`passwd` : | password
`auth_method` : | string indicating authentication method
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise.

### e_book_async_get_contact ()

    guint               e_book_async_get_contact            (EBook *book,
                                                             const gchar *id,
                                                             EBookContactCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_get_contact` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_get_contact_async()` instead.

Retrieves a contact specified by `id` from `book`.

`book` : | an EBook
`id` : | a unique string ID specifying the contact
`cb` : | function to call when operation finishes
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise

### e_book_async_get_contacts ()

    guint               e_book_async_get_contacts           (EBook *book,
                                                             EBookQuery *query,
                                                             EBookListCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_get_contacts` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_get_contacts_async()` instead.

Query `book` with `query`.

`book` : | an EBook
`query` : | an EBookQuery
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `FALSE` on success, `TRUE` otherwise

### e_book_async_remove_contact ()

    guint               e_book_async_remove_contact         (EBook *book,
                                                             EContact *contact,
                                                             EBookCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_remove_contact` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_remove_contact_async()` instead.

Removes `contact` from `book`.

`book` : | an EBook
`contact` : | an EContact
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_async_remove_contact_by_id ()

    guint               e_book_async_remove_contact_by_id   (EBook *book,
                                                             const gchar *id,
                                                             EBookCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_remove_contact_by_id` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_remove_contact_by_id_async()` instead.

Removes the contact with id `id` from `book`.

`book` : | an EBook
`id` : | a unique ID string specifying the contact
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_async_remove_contacts ()

    guint               e_book_async_remove_contacts        (EBook *book,
                                                             GList *ids,
                                                             EBookCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_remove_contacts` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_remove_contacts_async()` instead.

Removes the contacts with ids from the list `ids` from `book`. This is always more efficient than calling `e_book_remove_contact()` if you have more than one id to remove, as some backends can implement it as a batch request.

`book` : | an EBook
`ids` : | a GList of const gchar *id's
`cb` : | a function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if successful, `FALSE` otherwise

### e_book_async_add_contact ()

    gboolean            e_book_async_add_contact            (EBook *book,
                                                             EContact *contact,
                                                             EBookIdCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_add_contact` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_add_contact_async()` instead.

Adds `contact` to `book` without blocking.

`book` : | an EBook
`contact` : | an EContact
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if the operation was started, `FALSE` otherwise.

### e_book_async_commit_contact ()

    guint               e_book_async_commit_contact         (EBook *book,
                                                             EContact *contact,
                                                             EBookCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_commit_contact` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_commit_contact_async()` instead.

Applies the changes made to `contact` to the stored version in `book` without blocking.

`book` : | an EBook
`contact` : | an EContact
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if the operation was started, `FALSE` otherwise.

### e_book_async_get_book_view ()

    guint               e_book_async_get_book_view          (EBook *book,
                                                             EBookQuery *query,
                                                             GList *requested_fields,
                                                             gint max_results,
                                                             EBookBookViewCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_get_book_view` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_get_book_view_async()` instead.

Query `book` with `query`, creating a EBookView with the fields specified by `requested_fields` and limited at `max_results` records.

`book` : | an EBook
`query` : | an EBookQuery
`requested_fields` : | a GList containing the names of fields to return, or NULL for all
`max_results` : | the maximum number of contacts to show (or 0 for all)
`cb` : | a function to call when the operation finishes. [scope call]
`closure` : | data to pass to callback function
Returns : | `FALSE` if successful, `TRUE` otherwise

### e_book_async_get_changes ()

    guint               e_book_async_get_changes            (EBook *book,
                                                             const gchar *changeid,
                                                             EBookListCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_get_changes` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_get_changes_async()` instead.

Get the set of changes since the previous call to e_book_async_get_changes for a given change ID.

`book` : | an EBook
`changeid` : | the change ID
`cb` : | function to call when operation finishes
`closure` : | data to pass to callback function
Returns : | TRUE on success, FALSE otherwise

### e_book_async_get_required_fields ()

    guint               e_book_async_get_required_fields    (EBook *book,
                                                             EBookEListCallback cb,
                                                             gpointer closure);

### Warning

`e_book_async_get_required_fields` has been deprecated since version 3.0 and should not be used in newly-written code. Use `e_book_get_required_fields_async()` instead.

Gets a list of fields that are required to be filled in for all contacts in this `book`. This function does not block.

`book` : | an EBook
`cb` : | function to call when the operation finishes
`closure` : | data to pass to callback function
Returns : | `TRUE` if the operation was started, `FALSE` otherwise.

## Signal Details

### The `"auth-required"` signal

    void                user_function                      (EBook   *ebook,
                                                            gpointer user_data)      : Run Last

Authentication is required to access this source. You should call e_book_authenticate_user or e_book_async_authenticate_user.

`ebook` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"backend-died"` signal

    void                user_function                      (EBook   *ebook,
                                                            gpointer user_data)      : Run Last

The backend for this address book has died.

`ebook` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"connection-status"` signal

    void                user_function                      (EBook   *ebook,
                                                            gboolean arg1,
                                                            gpointer user_data)      : Run Last

The connection status for this book is being reported.

`ebook` : | the object which received the signal.
`arg1` : | TRUE if the connection is online, FALSE otherwise.
`user_data` : | user data set when the signal handler was connected.

### The `"writable-status"` signal

    void                user_function                      (EBook   *ebook,
                                                            gboolean arg1,
                                                            gpointer user_data)      : Run Last

The writable status for this book is being reported.

`ebook` : | the object which received the signal.
`arg1` : | TRUE if the book is writable, FALSE otherwise.
`user_data` : | user data set when the signal handler was connected.

## See Also

EBookView