## EBook

EBook — The primary Evolution addressbook client object.

## Synopsis

                EBook;
    EBook*      e_book_new                      (ESource *source,
                                                 GError **error);
    gboolean    e_book_remove                   (EBook *book,
                                                 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_authenticate_user        (EBook *book,
                                                 const char *user,
                                                 const char *passwd,
                                                 const char *auth_method,
                                                 GError **error);
    gboolean    e_book_get_contact              (EBook *book,
                                                 const char *id,
                                                 EContact **contact,
                                                 GError **error);
    gboolean    e_book_remove_contact           (EBook *book,
                                                 const char *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,
                                                 int 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,
                                                 char *changeid,
                                                 GList **changes,
                                                 GError **error);
    void        e_book_free_change_list         (GList *change_list);
    const char* e_book_get_uri                  (EBook *book);
    const char* e_book_get_static_capabilities  (EBook *book,
                                                 GError **error);
    gboolean    e_book_check_static_capability  (EBook *book,
                                                 const char *cap);
    gboolean    e_book_is_writable              (EBook *book);
    gboolean    e_book_cancel                   (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);

## Object Hierarchy

      GObject
       +----EBook

## Signals

    "auth-required"
                void        user_function      (EBook   *ebook,
                                                gpointer user_data)      : Run last
    "backend-died"
                void        user_function      (EBook   *ebook,
                                                gpointer user_data)      : Run last
    "connection-status"
                void        user_function      (EBook   *ebook,
                                                gboolean arg1,
                                                gpointer user_data)      : Run last
    "writable-status"
                void        user_function      (EBook   *ebook,
                                                gboolean arg1,
                                                gpointer user_data)      : Run last

## Description

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

    gboolean    e_book_authenticate_user        (EBook *book,
                                                 const char *user,
                                                 const char *passwd,
                                                 const char *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 char *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
`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 char *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_by_id 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 char *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,
                                                 int 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,
                                                 char *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 char* 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 char* 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 char *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_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
`error` : | A pointer to a GError* to set on error
Returns : | `TRUE` if `addressbook_sources` was set, otherwise `FALSE`.

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