EBook

EBook — The primary Evolution addressbook client object.

Synopsis




struct      EBook;
EBook*      e_book_new                      (void);
gboolean    e_book_load_source              (EBook *book,
                                             ESource *source,
                                             gboolean only_if_exists,
                                             GError **error);
gboolean    e_book_load_uri                 (EBook *book,
                                             const char *uri,
                                             gboolean only_if_exists,
                                             GError **error);
gboolean    e_book_unload_uri               (EBook *book,
                                             GError **error);
gboolean    e_book_remove                   (EBook *book,
                                             GError **error);
gboolean    e_book_load_local_addressbook   (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_default_addressbook  (EBook **book,
                                             GError **error);
gboolean    e_book_get_addressbooks         (ESourceList **addressbook_sources,
                                             GError **error);


Object Hierarchy


  GObject
   +----EBook

Signal Prototypes


"backend-died"
            void        user_function      (EBook *ebook,
                                            gpointer user_data);
"writable-status"
            void        user_function      (EBook *ebook,
                                            gboolean arg1,
                                            gpointer user_data);

Description

Represents a complete addressbook. Event notifications and callbacks go to the e-book-listener. Contrast with e-book-view, which represents a search of the addressbook.

Details

struct EBook

struct EBook;

EBook has no publicly available members.


e_book_new ()

EBook*      e_book_new                      (void);

Creates a new EBook. Use e_book_load_uri() or e_book_load_local_addressbook() to access a data store. Alternatively use e_book_get_default_addressbook().

Returns : a new but unopened EBook.

e_book_load_source ()

gboolean    e_book_load_source              (EBook *book,
                                             ESource *source,
                                             gboolean only_if_exists,
                                             GError **error);

Load the specified source into the book.

book : an EBook
source : the ESource to load
only_if_exists : if TRUE, fail if this source doesn't already exist otherwise create it first
error : a GError to set on failure
Returns : TRUE if the source was loaded, FALSE otherwise.

e_book_load_uri ()

gboolean    e_book_load_uri                 (EBook *book,
                                             const char *uri,
                                             gboolean only_if_exists,
                                             GError **error);

Create an ESource from url and load the source. See e_book_load_source().

book : an EBook
uri : the URI to load
only_if_exists : if TRUE, fail if this URI doesn't already exist otherwise create it first
error : a GError to set on failure
Returns : TRUE if the URI was loaded, FALSE otherwise.

e_book_unload_uri ()

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

Unload the URI that this book had previously loaded.

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

e_book_remove ()

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

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
error : a GError to set on failure
Returns : TRUE on success, FALSE on failure.

e_book_load_local_addressbook ()

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

Load the local address book into book.

book : an EBook
error : a GError
Returns : TRUE on success, FALSE otherwise.

e_book_get_supported_fields ()

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

Queries book for the list of fields it supports. Mostly for use by the contact editor so it knows what fields to sensitize.

book : an EBook
fields : a GList
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.

book : an EBook
auth_methods : a GList
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 string
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);

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

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

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_default_addressbook ()

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

Convience function to open the default address book. Pass it the address of a EBook* and if this returns TRUE, book is set to an opened EBook.

book : The address of a pointer to an EBook
error : A GError pointer
Returns : TRUE if the default addressbook was opened, otherwise FALSE.

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.

Signals

The "backend-died" signal

void        user_function                  (EBook *ebook,
                                            gpointer user_data);

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 "writable-status" signal

void        user_function                  (EBook *ebook,
                                            gboolean arg1,
                                            gpointer user_data);

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

See Also

e-book-listener, e-book-view