EBook
3
LIBEBOOK Library

# 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 char *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 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);
    void                (*EBookCallback)                    (EBook *book,
                                                             EBookStatus status,
                                                             gpointer closure);
    void                (*EBookOpenProgressCallback)        (EBook *book,
                                                             const char *status_message,
                                                             short percent ,
                                                             gpointer closure);
    void                (*EBookIdCallback)                  (EBook *book,
                                                             EBookStatus status,
                                                             const char *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);
    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 char *user,
                                                             const char *passwd,
                                                             const char *auth_method,
                                                             EBookCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_contact            (EBook *book,
                                                             const char *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 char *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,
                                                             int max_results,
                                                             EBookBookViewCallback cb,
                                                             gpointer closure);
    guint               e_book_async_get_changes            (EBook *book,
                                                             char *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

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

`source` :

`error` :

Returns :

### e_book_new_default_addressbook ()

    EBook*              e_book_new_default_addressbook      (GError **error);

`error` :

Returns :

### e_book_new_from_uri ()

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

`uri` :

`error` :

Returns :

### e_book_new_system_addressbook ()

    EBook*              e_book_new_system_addressbook       (GError **error);

`error` :

Returns :

### e_book_set_default_addressbook ()

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

`book` :

`error` :

Returns :

### e_book_set_default_source ()

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

`source` :

`error` :

Returns :

### e_book_remove ()

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

`book` :

`error` :

Returns :

### e_book_open ()

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

`book` :

`only_if_exists` :

`error` :

Returns :

### e_book_get_supported_fields ()

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

`book` :

`fields` :

`error` :

Returns :

### e_book_get_supported_auth_methods ()

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

`book` :

`auth_methods` :

`error` :

Returns :

### e_book_get_required_fields ()

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

`book` :

`fields` :

`error` :

Returns :

### e_book_get_source ()

    ESource*            e_book_get_source                   (EBook *book);

`book` :

Returns :

### e_book_is_online ()

    gboolean            e_book_is_online                    (EBook *book);

`book` :

Returns :

### e_book_is_opened ()

    gboolean            e_book_is_opened                    (EBook *book);

`book` :

Returns :

### e_book_authenticate_user ()

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

`book` :

`user` :

`passwd` :

`auth_method` :

`error` :

Returns :

### e_book_get_contact ()

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

`book` :

`id` :

`contact` :

`error` :

Returns :

### e_book_remove_contact ()

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

`book` :

`id` :

`error` :

Returns :

### e_book_remove_contacts ()

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

`book` :

`ids` :

`error` :

Returns :

### e_book_add_contact ()

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

`book` :

`contact` :

`error` :

Returns :

### e_book_commit_contact ()

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

`book` :

`contact` :

`error` :

Returns :

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

`book` :

`query` :

`requested_fields` :

`max_results` :

`book_view` :

`error` :

Returns :

### e_book_get_contacts ()

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

`book` :

`query` :

`contacts` :

`error` :

Returns :

### e_book_get_changes ()

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

`book` :

`changeid` :

`changes` :

`error` :

Returns :

### e_book_free_change_list ()

    void                e_book_free_change_list             (GList *change_list);

`change_list` :

### e_book_get_uri ()

    const char*         e_book_get_uri                      (EBook *book);

`book` :

Returns :

### e_book_get_static_capabilities ()

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

`book` :

`error` :

Returns :

### e_book_check_static_capability ()

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

`book` :

`cap` :

Returns :

### e_book_is_writable ()

    gboolean            e_book_is_writable                  (EBook *book);

`book` :

Returns :

### e_book_cancel ()

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

`book` :

`error` :

Returns :

### e_book_get_self ()

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

`contact` :

`book` :

`error` :

Returns :

### e_book_set_self ()

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

`book` :

`contact` :

`error` :

Returns :

### e_book_is_self ()

    gboolean            e_book_is_self                      (EContact *contact);

`contact` :

Returns :

### e_book_get_addressbooks ()

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

`addressbook_sources` :

`error` :

Returns :

### EBookCallback ()

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

`book` :

`status` :

`closure` :

### EBookOpenProgressCallback ()

    void                (*EBookOpenProgressCallback)        (EBook *book,
                                                             const char *status_message,
                                                             short percent ,
                                                             gpointer closure);

`book` :

`status_message` :

`Param3` :

`closure` :

### EBookIdCallback ()

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

`book` :

`status` :

`id` :

`closure` :

### EBookEListCallback ()

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

`book` :

`status` :

`list` :

`closure` :

### EBookListCallback ()

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

`book` :

`status` :

`list` :

`closure` :

### EBookContactCallback ()

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

`book` :

`status` :

`contact` :

`closure` :

### EBookBookViewCallback ()

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

`book` :

`status` :

`book_view` :

`closure` :

### e_book_async_open ()

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

`book` :

`only_if_exists` :

`open_response` :

`closure` :

Returns :

### e_book_async_remove ()

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

`book` :

`cb` :

`closure` :

Returns :

### e_book_async_get_supported_fields ()

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

`book` :

`cb` :

`closure` :

Returns :

### e_book_async_get_supported_auth_methods ()

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

`book` :

`cb` :

`closure` :

Returns :

### e_book_async_authenticate_user ()

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

`book` :

`user` :

`passwd` :

`auth_method` :

`cb` :

`closure` :

Returns :

### e_book_async_get_contact ()

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

`book` :

`id` :

`cb` :

`closure` :

Returns :

### e_book_async_get_contacts ()

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

`book` :

`query` :

`cb` :

`closure` :

Returns :

### e_book_async_remove_contact ()

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

`book` :

`contact` :

`cb` :

`closure` :

Returns :

### e_book_async_remove_contact_by_id ()

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

`book` :

`id` :

`cb` :

`closure` :

Returns :

### e_book_async_remove_contacts ()

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

`book` :

`ids` :

`cb` :

`closure` :

Returns :

### e_book_async_add_contact ()

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

`book` :

`contact` :

`cb` :

`closure` :

Returns :

### e_book_async_commit_contact ()

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

`book` :

`contact` :

`cb` :

`closure` :

Returns :

### e_book_async_get_book_view ()

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

`book` :

`query` :

`requested_fields` :

`max_results` :

`cb` :

`closure` :

Returns :

### e_book_async_get_changes ()

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

`book` :

`changeid` :

`cb` :

`closure` :

Returns :

### e_book_async_get_required_fields ()

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

`book` :

`cb` :

`closure` :

Returns :

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