EBookBackend
3
LIBEDATA-BOOK Library

# EBookBackend

## Synopsis

    struct              EBookBackend;
    gboolean            e_book_backend_construct            (EBookBackend *backend);
    GNOME_Evolution_Addressbook_CallStatus e_book_backend_load_source
                                                            (EBookBackend *backend,
                                                             ESource *source,
                                                             gboolean only_if_exists);
    ESource*            e_book_backend_get_source           (EBookBackend *backend);
    gboolean            e_book_backend_add_client           (EBookBackend *backend,
                                                             EDataBook *book);
    void                e_book_backend_remove_client        (EBookBackend *backend,
                                                             EDataBook *book);
    gboolean            e_book_backend_has_out_of_proc_clients
                                                            (EBookBackend *backend);
    char*               e_book_backend_get_static_capabilities
                                                            (EBookBackend *backend);
    gboolean            e_book_backend_is_loaded            (EBookBackend *backend);
    gboolean            e_book_backend_is_writable          (EBookBackend *backend);
    gboolean            e_book_backend_is_removed           (EBookBackend *backend);
    void                e_book_backend_open                 (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             gboolean only_if_exists);
    void                e_book_backend_remove               (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid);
    void                e_book_backend_create_contact       (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *vcard);
    void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GList *id_list);
    void                e_book_backend_modify_contact       (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *vcard);
    void                e_book_backend_get_contact          (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *id);
    void                e_book_backend_get_contact_list     (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *query);
    void                e_book_backend_get_changes          (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *change_id);
    void                e_book_backend_authenticate_user    (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *user,
                                                             const char *passwd,
                                                             const char *auth_method);
    void                e_book_backend_get_supported_fields (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid);
    void                e_book_backend_get_required_fields  (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid);
    void                e_book_backend_get_supported_auth_methods
                                                            (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid);
    GNOME_Evolution_Addressbook_CallStatus e_book_backend_cancel_operation
                                                            (EBookBackend *backend,
                                                             EDataBook *book);
    void                e_book_backend_set_mode             (EBookBackend *backend,
                                                             GNOME_Evolution_Addressbook_BookMode mode);
    void                e_book_backend_start_book_view      (EBookBackend *backend,
                                                             EDataBookView *view);
    void                e_book_backend_stop_book_view       (EBookBackend *backend,
                                                             EDataBookView *view);
    void                e_book_backend_add_book_view        (EBookBackend *backend,
                                                             EDataBookView *view);
    void                e_book_backend_remove_book_view     (EBookBackend *backend,
                                                             EDataBookView *view);
    EList*              e_book_backend_get_book_views       (EBookBackend *backend);
    void                e_book_backend_notify_update        (EBookBackend *backend,
                                                             EContact *contact);
    void                e_book_backend_notify_remove        (EBookBackend *backend,
                                                             const char *id);
    void                e_book_backend_notify_complete      (EBookBackend *backend);
    void                e_book_backend_notify_writable      (EBookBackend *backend,
                                                             gboolean is_writable);
    void                e_book_backend_notify_connection_status
                                                            (EBookBackend *backend,
                                                             gboolean is_online);
    void                e_book_backend_notify_auth_required (EBookBackend *backend);
    void                e_book_backend_sync                 (EBookBackend *backend);
    void                e_book_backend_set_is_loaded        (EBookBackend *backend,
                                                             gboolean is_loaded);
    void                e_book_backend_set_is_writable      (EBookBackend *backend,
                                                             gboolean is_writable);
    void                e_book_backend_set_is_removed       (EBookBackend *backend,
                                                             gboolean is_removed);
    GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_add_new
                                                            (const char *vcard);
    GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_modify_new
                                                            (const char *vcard);
    GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_delete_new
                                                            (const char *id);
    struct              EBookBackendClass;

## Object Hierarchy

      GObject
       +----EBookBackend
             +----EBookBackendSync

## Signals

      "last-client-gone"                               : Run First

## Description

## Details

### struct EBookBackend

    struct EBookBackend;

### e_book_backend_construct ()

    gboolean            e_book_backend_construct            (EBookBackend *backend);

Does nothing.

`backend` :

  an EBookBackend

Returns :

  `TRUE`.

### e_book_backend_load_source ()

    GNOME_Evolution_Addressbook_CallStatus e_book_backend_load_source
                                                            (EBookBackend *backend,
                                                             ESource *source,
                                                             gboolean only_if_exists);

Loads `source` into `backend`.

`backend` :

  an EBookBackend

`source` :

  an ESource to load

`only_if_exists` :

  `TRUE` to prevent the creation of a new book

Returns :

  A GNOME_Evolution_Addressbook_CallStatus indicating the outcome.

### e_book_backend_get_source ()

    ESource*            e_book_backend_get_source           (EBookBackend *backend);

Queries the source that an addressbook backend is serving.

`backend` :

  An addressbook backend.

Returns :

  ESource for the backend.

### e_book_backend_add_client ()

    gboolean            e_book_backend_add_client           (EBookBackend *backend,
                                                             EDataBook *book);

Adds a client to an addressbook backend.

`backend` :

  An addressbook backend.

`book` :

  the corba object representing the client connection.

Returns :

  TRUE on success, FALSE on failure to add the client.

### e_book_backend_remove_client ()

    void                e_book_backend_remove_client        (EBookBackend *backend,
                                                             EDataBook *book);

Removes `book` from the list of `backend`'s clients.

`backend` :

  an EBookBackend

`book` :

  an EDataBook to remove

### e_book_backend_has_out_of_proc_clients ()

    gboolean            e_book_backend_has_out_of_proc_clients
                                                            (EBookBackend *backend);

Checks if `backend` has clients running in other system processes.

`backend` :

  an EBookBackend

Returns :

  `TRUE` if there are clients in other processes, `FALSE` otherwise.

### e_book_backend_get_static_capabilities ()

    char*               e_book_backend_get_static_capabilities
                                                            (EBookBackend *backend);

Gets the capabilities offered by this `backend`.

`backend` :

  an EBookBackend

Returns :

  A string listing the capabilities.

### e_book_backend_is_loaded ()

    gboolean            e_book_backend_is_loaded            (EBookBackend *backend);

Checks if `backend`'s storage has been opened and the backend itself is ready for accessing.

`backend` :

  an EBookBackend

Returns :

  `TRUE` if loaded, `FALSE` otherwise.

### e_book_backend_is_writable ()

    gboolean            e_book_backend_is_writable          (EBookBackend *backend);

Checks if we can write to `backend`.

`backend` :

  an EBookBackend

Returns :

  `TRUE` if writeable, `FALSE` if not.

### e_book_backend_is_removed ()

    gboolean            e_book_backend_is_removed           (EBookBackend *backend);

Checks if `backend` has been removed from its physical storage.

`backend` :

  an EBookBackend

Returns :

  `TRUE` if `backend` has been removed, `FALSE` otherwise.

### e_book_backend_open ()

    void                e_book_backend_open                 (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             gboolean only_if_exists);

Executes an 'open' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

`only_if_exists` :

  `TRUE` to prevent the creation of a new book

### e_book_backend_remove ()

    void                e_book_backend_remove               (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid);

Executes a 'remove' request to remove all of `backend`'s data, specified by `opid` on `book`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

### e_book_backend_create_contact ()

    void                e_book_backend_create_contact       (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *vcard);

Executes a 'create contact' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

`vcard` :

  the VCard to add

### e_book_backend_remove_contacts ()

    void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GList *id_list);

Executes a 'remove contacts' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

`id_list` :

  list of string IDs to remove

### e_book_backend_modify_contact ()

    void                e_book_backend_modify_contact       (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *vcard);

Executes a 'modify contact' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

`vcard` :

  the VCard to update

### e_book_backend_get_contact ()

    void                e_book_backend_get_contact          (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *id);

Executes a 'get contact' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

`id` :

  the ID of the contact to get

### e_book_backend_get_contact_list ()

    void                e_book_backend_get_contact_list     (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *query);

Executes a 'get contact list' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

`query` :

  the s-expression to match

### e_book_backend_get_changes ()

    void                e_book_backend_get_changes          (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *change_id);

Executes a 'get changes' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

`change_id` :

  the ID of the changeset

### e_book_backend_authenticate_user ()

    void                e_book_backend_authenticate_user    (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const char *user,
                                                             const char *passwd,
                                                             const char *auth_method);

Executes an 'authenticate' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

`user` :

  the name of the user account

`passwd` :

  the user's password

`auth_method` :

  the authentication method to use

### e_book_backend_get_supported_fields ()

    void                e_book_backend_get_supported_fields (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid);

Executes a 'get supported fields' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

### e_book_backend_get_required_fields ()

    void                e_book_backend_get_required_fields  (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid);

Executes a 'get required fields' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

### e_book_backend_get_supported_auth_methods ()

    void                e_book_backend_get_supported_auth_methods
                                                            (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid);

Executes a 'get supported auth methods' request specified by `opid` on `book` using `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook

`opid` :

  the ID to use for this operation

### e_book_backend_cancel_operation ()

    GNOME_Evolution_Addressbook_CallStatus e_book_backend_cancel_operation
                                                            (EBookBackend *backend,
                                                             EDataBook *book);

Cancel `book`'s running operation on `backend`.

`backend` :

  an EBookBackend

`book` :

  an EDataBook whose operation should be cancelled

Returns :

  A GNOME_Evolution_Addressbook_CallStatus indicating the outcome.

### e_book_backend_set_mode ()

    void                e_book_backend_set_mode             (EBookBackend *backend,
                                                             GNOME_Evolution_Addressbook_BookMode mode);

Sets `backend`'s online/offline mode to `mode`. Mode can be 1 for offline or 2 indicating that it is connected and online.

`backend` :

  an EBookbackend

`mode` :

  a mode indicating the online/offline status of the backend

### e_book_backend_start_book_view ()

    void                e_book_backend_start_book_view      (EBookBackend *backend,
                                                             EDataBookView *view);

Starts running the query specified by `book_view`, emitting signals for matching contacts.

`backend` :

  an EBookBackend

`view` :

### e_book_backend_stop_book_view ()

    void                e_book_backend_stop_book_view       (EBookBackend *backend,
                                                             EDataBookView *view);

Stops running the query specified by `book_view`, emitting no more signals.

`backend` :

  an EBookBackend

`view` :

### e_book_backend_add_book_view ()

    void                e_book_backend_add_book_view        (EBookBackend *backend,
                                                             EDataBookView *view);

Adds `view` to `backend` for querying.

`backend` :

  an EBookBackend

`view` :

  an EDataBookView

### e_book_backend_remove_book_view ()

    void                e_book_backend_remove_book_view     (EBookBackend *backend,
                                                             EDataBookView *view);

Removes `view` from `backend`.

`backend` :

  an EBookBackend

`view` :

  an EDataBookView

### e_book_backend_get_book_views ()

    EList*              e_book_backend_get_book_views       (EBookBackend *backend);

Gets the list of EDataBookView views running on this backend.

`backend` :

  an EBookBackend

Returns :

  An EList of EDataBookView objects.

### e_book_backend_notify_update ()

    void                e_book_backend_notify_update        (EBookBackend *backend,
                                                             EContact *contact);

Notifies all of `backend`'s book views about the new or modified contacts `contact`.

`e_data_book_respond_create()` and `e_data_book_respond_modify()` call this function for you. You only need to call this from your backend if contacts are created or modified by another (non-PAS-using) client.

`backend` :

  an EBookBackend

`contact` :

  a new or modified contact

### e_book_backend_notify_remove ()

    void                e_book_backend_notify_remove        (EBookBackend *backend,
                                                             const char *id);

Notifies all of `backend`'s book views that the contact with UID `id` has been removed.

`e_data_book_respond_remove_contacts()` calls this function for you. You only need to call this from your backend if contacts are removed by another (non-PAS-using) client.

`backend` :

  an EBookBackend

`id` :

  a contact id

### e_book_backend_notify_complete ()

    void                e_book_backend_notify_complete      (EBookBackend *backend);

Notifies all of `backend`'s book views that the current set of notifications is complete; use this after a series of `e_book_backend_notify_update()` and `e_book_backend_notify_remove()` calls.

`backend` :

  an EBookbackend

### e_book_backend_notify_writable ()

    void                e_book_backend_notify_writable      (EBookBackend *backend,
                                                             gboolean is_writable);

Notifies all backends clients about the current writable state.

`backend` :

  an EBookBackend

`is_writable` :

  flag indicating writable status

### e_book_backend_notify_connection_status ()

    void                e_book_backend_notify_connection_status
                                                            (EBookBackend *backend,
                                                             gboolean is_online);

Notifies clients of `backend`'s connection status indicated by `is_online`. Meant to be used by backend implementations.

`backend` :

  an EBookBackend

`is_online` :

  flag indicating whether `backend` is connected and online

### e_book_backend_notify_auth_required ()

    void                e_book_backend_notify_auth_required (EBookBackend *backend);

Notifies clients that `backend` requires authentication in order to connect. Means to be used by backend implementations.

`backend` :

  an EBookBackend

### e_book_backend_sync ()

    void                e_book_backend_sync                 (EBookBackend *backend);

Write all pending data to disk. This is only required under special circumstances (for example before a live backup) and should not be used in normal use.

`backend` :

  an EBookbackend

### e_book_backend_set_is_loaded ()

    void                e_book_backend_set_is_loaded        (EBookBackend *backend,
                                                             gboolean is_loaded);

Sets the flag indicating whether `backend` is loaded to `is_loaded`. Meant to be used by backend implementations.

`backend` :

  an EBookBackend

`is_loaded` :

  A flag indicating whether the backend is loaded

### e_book_backend_set_is_writable ()

    void                e_book_backend_set_is_writable      (EBookBackend *backend,
                                                             gboolean is_writable);

Sets the flag indicating whether `backend` is writeable to `is_writeable`. Meant to be used by backend implementations.

`backend` :

  an EBookBackend

`is_writable` :

  A flag indicating whether the backend is writeable

### e_book_backend_set_is_removed ()

    void                e_book_backend_set_is_removed       (EBookBackend *backend,
                                                             gboolean is_removed);

Sets the flag indicating whether `backend` was removed to `is_removed`. Meant to be used by backend implementations.

`backend` :

  an EBookBackend

`is_removed` :

  A flag indicating whether the backend's storage was removed

### e_book_backend_change_add_new ()

    GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_add_new
                                                            (const char *vcard);

Creates a new change item indicating `vcard` was added. Meant to be used by backend implementations.

`vcard` :

  a VCard string

Returns :

  A new GNOME_Evolution_Addressbook_BookChangeItem.

### e_book_backend_change_modify_new ()

    GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_modify_new
                                                            (const char *vcard);

Creates a new change item indicating `vcard` was modified. Meant to be used by backend implementations.

`vcard` :

  a VCard string

Returns :

  A new GNOME_Evolution_Addressbook_BookChangeItem.

### e_book_backend_change_delete_new ()

    GNOME_Evolution_Addressbook_BookChangeItem* e_book_backend_change_delete_new
                                                            (const char *id);

Creates a new change item indicating `vcard` was deleted. Meant to be used by backend implementations.

`id` :

Returns :

  A new GNOME_Evolution_Addressbook_BookChangeItem.

### struct EBookBackendClass

    struct EBookBackendClass {
    	GObjectClass parent_class;

    	/* Virtual methods */
    	GNOME_Evolution_Addressbook_CallStatus (*load_source) (EBookBackend *backend, ESource *source, gboolean only_if_exists);
    	void (*remove) (EBookBackend *backend, EDataBook *book, guint32 opid);
            char *(*get_static_capabilities) (EBookBackend *backend);

    	void (*create_contact)  (EBookBackend *backend, EDataBook *book, guint32 opid, const char *vcard);
    	void (*remove_contacts) (EBookBackend *backend, EDataBook *book, guint32 opid, GList *id_list);
    	void (*modify_contact)  (EBookBackend *backend, EDataBook *book, guint32 opid, const char *vcard);
    	void (*get_contact) (EBookBackend *backend, EDataBook *book, guint32 opid, const char *id);
    	void (*get_contact_list) (EBookBackend *backend, EDataBook *book, guint32 opid, const char *query);
    	void (*start_book_view) (EBookBackend *backend, EDataBookView *book_view);
    	void (*stop_book_view) (EBookBackend *backend, EDataBookView *book_view);
    	void (*get_changes) (EBookBackend *backend, EDataBook *book, guint32 opid, const char *change_id);
    	void (*authenticate_user) (EBookBackend *backend, EDataBook *book, guint32 opid, const char *user, const char *passwd, const char *auth_method);
    	void (*get_required_fields) (EBookBackend *backend, EDataBook *bokk, guint32 opid);
    	void (*get_supported_fields) (EBookBackend *backend, EDataBook *book, guint32 opid);
    	void (*get_supported_auth_methods) (EBookBackend *backend, EDataBook *book, guint32 opid);
    	GNOME_Evolution_Addressbook_CallStatus (*cancel_operation) (EBookBackend *backend, EDataBook *book);
    	void (*set_mode) (EBookBackend *backend, GNOME_Evolution_Addressbook_BookMode  mode);

    	/* Notification signals */
    	void (* last_client_gone) (EBookBackend *backend);

    	void (*sync) (EBookBackend *backend);

    	/* Padding for future expansion */
    	void (*_pas_reserved1) (void);
    	void (*_pas_reserved2) (void);
    	void (*_pas_reserved3) (void);
    	void (*_pas_reserved4) (void);
    };

## Signal Details

### The `"last-client-gone"` signal

    void                user_function                      (EBookBackend *ebookbackend,
                                                            gpointer      user_data)         : Run First

`ebookbackend` :

  the object which received the signal.

`user_data` :

  user data set when the signal handler was connected.