EBookBackend

## EBookBackend EBookBackend |

## Synopsis

    struct              EBookBackend;
    const gchar *       e_book_backend_get_cache_dir        (EBookBackend *backend);
    void                e_book_backend_set_cache_dir        (EBookBackend *backend,
                                                             const gchar *cache_dir);
    void                e_book_backend_load_source          (EBookBackend *backend,
                                                             ESource *source,
                                                             gboolean only_if_exists,
                                                             GError **error);
    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);
    gchar *             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 gchar *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 gchar *vcard);
    void                e_book_backend_get_contact          (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const gchar *id);
    void                e_book_backend_get_contact_list     (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const gchar *query);
    void                e_book_backend_get_changes          (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const gchar *change_id);
    void                e_book_backend_authenticate_user    (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             const gchar *user,
                                                             const gchar *passwd,
                                                             const gchar *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);
    void                e_book_backend_cancel_operation     (EBookBackend *backend,
                                                             EDataBook *book,
                                                             GError **error);
    void                e_book_backend_set_mode             (EBookBackend *backend,
                                                             EDataBookMode 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 gchar *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);
    EDataBookChange*    e_book_backend_change_add_new       (const gchar *vcard);
    EDataBookChange*    e_book_backend_change_modify_new    (const gchar *vcard);
    EDataBookChange*    e_book_backend_change_delete_new    (const gchar *id);
    struct              EBookBackendClass;

## Object Hierarchy

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

## Properties

      "cache-dir"                gchar*                : Read / Write

## Signals

      "last-client-gone"                               : Run First

## Description

## Details

### struct EBookBackend

    struct EBookBackend;

### e_book_backend_get_cache_dir ()

    const gchar *       e_book_backend_get_cache_dir        (EBookBackend *backend);

Returns the cache directory for the given backend.

`backend` : | an EBookBackend
Returns : | the cache directory for the backend

Since 2.32

### e_book_backend_set_cache_dir ()

    void                e_book_backend_set_cache_dir        (EBookBackend *backend,
                                                             const gchar *cache_dir);

Sets the cache directory for the given backend.

Note that EBookBackend is initialized with a usable default based on the ESource given to `e_book_backend_load_source()`. Backends should not override the default without good reason.

`backend` : | an EBookBackend
`cache_dir` : | a local cache directory

Since 2.32

### e_book_backend_load_source ()

    void                e_book_backend_load_source          (EBookBackend *backend,
                                                             ESource *source,
                                                             gboolean only_if_exists,
                                                             GError **error);

Loads `source` into `backend`.

`backend` : | an EBookBackend
`source` : | an ESource to load
`only_if_exists` : | `TRUE` to prevent the creation of a new book
`error` : | GError to set, when something fails

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

    gchar *             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 gchar *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 gchar *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 gchar *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 gchar *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 gchar *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 gchar *user,
                                                             const gchar *passwd,
                                                             const gchar *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 ()

    void                e_book_backend_cancel_operation     (EBookBackend *backend,
                                                             EDataBook *book,
                                                             GError **error);

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

`backend` : | an EBookBackend
`book` : | an EDataBook whose operation should be cancelled
`error` : | GError to set, when something fails

### e_book_backend_set_mode ()

    void                e_book_backend_set_mode             (EBookBackend *backend,
                                                             EDataBookMode 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 gchar *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

Since 1.12

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

    EDataBookChange*    e_book_backend_change_add_new       (const gchar *vcard);

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

`vcard` : | a VCard string
Returns : | A new EDataBookChange.

### e_book_backend_change_modify_new ()

    EDataBookChange*    e_book_backend_change_modify_new    (const gchar *vcard);

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

`vcard` : | a VCard string
Returns : | A new EDataBookChange.

### e_book_backend_change_delete_new ()

    EDataBookChange*    e_book_backend_change_delete_new    (const gchar *id);

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

`id` : |
Returns : | A new EDataBookChange.

### struct EBookBackendClass

    struct EBookBackendClass {
    	GObjectClass parent_class;

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

    	void (*create_contact)  (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *vcard);
    	void (*remove_contacts) (EBookBackend *backend, EDataBook *book, guint32 opid, GList *id_list);
    	void (*modify_contact)  (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *vcard);
    	void (*get_contact) (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *id);
    	void (*get_contact_list) (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *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 gchar *change_id);
    	void (*authenticate_user) (EBookBackend *backend, EDataBook *book, guint32 opid, const gchar *user, const gchar *passwd, const gchar *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);
    	void (*cancel_operation) (EBookBackend *backend, EDataBook *book, GError **error);
    	void (*set_mode) (EBookBackend *backend, EDataBookMode 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);
    };

## Property Details

### The `"cache-dir"` property

      "cache-dir"                gchar*                : Read / Write

Default value: NULL

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