## 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);
    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_is_removed           (EBookBackend *backend);
    void                e_book_backend_open                 (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             gboolean only_if_exists);
    void                e_book_backend_remove               (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable);
    void                e_book_backend_create_contact       (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *vcard);
    void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *id_list);
    void                e_book_backend_modify_contact       (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *vcard);
    void                e_book_backend_get_contact          (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *id);
    void                e_book_backend_get_contact_list     (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *query);
    void                e_book_backend_authenticate_user    (EBookBackend *backend,
                                                             GCancellable *cancellable,
                                                             ECredentials *credentials);
    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);
    void                e_book_backend_notify_update        (EBookBackend *backend,
                                                             const 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_auth_required (EBookBackend *backend,
                                                             gboolean is_self,
                                                             const ECredentials *credentials);
    void                e_book_backend_sync                 (EBookBackend *backend);
    void                e_book_backend_set_is_removed       (EBookBackend *backend,
                                                             gboolean is_removed);
    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_open()`. Backends should not override the default without good reason.

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

Since 2.32

### 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_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,
                                                             GCancellable *cancellable,
                                                             gboolean only_if_exists);

Executes an 'open' request specified by `opid` on `book` using `backend`. This call might be finished with `e_data_book_respond_open()` or `e_book_backend_respond_opened()`, though the overall opening phase finishes only after call of `e_book_backend_notify_opened()` after which call the backend is either fully opened (including authentication against (remote) server/storage) or an error was encountered during this opening phase. 'opened' and 'opening' properties are updated automatically. The backend refuses all other operations until the opening phase is finished.

The `e_book_backend_notify_opened()` is called either from this function or from `e_book_backend_authenticate_user()`, or after necessary steps initiated by these two functions.

The opening phase usually works like this: 1) client requests open for the backend 2) server receives this request and calls `e_book_backend_open()` - the opening phase begun 3) either the backend is opened during this call, and notifies client with `e_book_backend_notify_opened()` about that. This is usually for local backends; their opening phase is finished 4) or the backend requires authentication, thus it notifies client about that with `e_book_backend_notify_auth_required()` and is waiting for credentials, which will be received from client by `e_book_backend_authenticate_user()` call. Backend's opening phase is still running in this case, thus it doesn't call `e_book_backend_notify_opened()` within `e_book_backend_open()` call. 5) when backend receives credentials in `e_book_backend_authenticate_user()` then it tries to authenticate against a server/storage with them and only after it knows result of the authentication, whether user was or wasn't authenticated, it notifies client with the result by `e_book_backend_notify_opened()` and it's opening phase is finished now. If there was no error returned then the backend is considered opened, otherwise it's considered closed. Use AuthenticationFailed error when the given credentials were rejected by the server/store, which will result in a re-prompt on the client side, otherwise use AuthenticationRequired if there was anything wrong with the given credentials. Set error's message to a reason for a re-prompt, it'll be shown to a user. 6) client checks error returned from `e_book_backend_notify_opened()` and reprompts for a password if it was AuthenticationFailed. Otherwise considers backend opened based on the error presence (no error means success).

In any case, the call of `e_book_backend_open()` should be always finished with `e_data_book_respond_open()`, which has no influence on the opening phase, or alternatively with `e_book_backend_respond_opened()`. Never use authentication errors in `e_data_book_respond_open()` to notify the client the authentication is required, there is `e_book_backend_notify_auth_required()` for this.

`backend` : | an EBookBackend
`book` : | an EDataBook
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the 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,
                                                             GCancellable *cancellable);

Executes a 'remove' request to remove all of `backend`'s data, specified by `opid` on `book`. This might be finished with `e_data_book_respond_remove()`.

`backend` : | an EBookBackend
`book` : | an EDataBook
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation

### e_book_backend_create_contact ()

    void                e_book_backend_create_contact       (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *vcard);

Executes a 'create contact' request specified by `opid` on `book` using `backend`. This might be finished with `e_data_book_respond_create()`.

`backend` : | an EBookBackend
`book` : | an EDataBook
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`vcard` : | the VCard to add

### e_book_backend_remove_contacts ()

    void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const GSList *id_list);

Executes a 'remove contacts' request specified by `opid` on `book` using `backend`. This might be finished with `e_data_book_respond_remove_contacts()`.

`backend` : | an EBookBackend
`book` : | an EDataBook
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the 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,
                                                             GCancellable *cancellable,
                                                             const gchar *vcard);

Executes a 'modify contact' request specified by `opid` on `book` using `backend`. This might be finished with `e_data_book_respond_modify()`.

`backend` : | an EBookBackend
`book` : | an EDataBook
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`vcard` : | the VCard to update

### e_book_backend_get_contact ()

    void                e_book_backend_get_contact          (EBookBackend *backend,
                                                             EDataBook *book,
                                                             guint32 opid,
                                                             GCancellable *cancellable,
                                                             const gchar *id);

Executes a 'get contact' request specified by `opid` on `book` using `backend`. This might be finished with `e_data_book_respond_get_contact()`.

`backend` : | an EBookBackend
`book` : | an EDataBook
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the 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,
                                                             GCancellable *cancellable,
                                                             const gchar *query);

Executes a 'get contact list' request specified by `opid` on `book` using `backend`. This might be finished with `e_data_book_respond_get_contact_list()`.

`backend` : | an EBookBackend
`book` : | an EDataBook
`opid` : | the ID to use for this operation
`cancellable` : | a GCancellable for the operation
`query` : | the s-expression to match

### e_book_backend_authenticate_user ()

    void                e_book_backend_authenticate_user    (EBookBackend *backend,
                                                             GCancellable *cancellable,
                                                             ECredentials *credentials);

Notifies `backend` about `credentials` provided by user to use for authentication. This notification is usually called during opening phase as a response to `e_book_backend_notify_auth_required()` on the client side and it results in setting property 'opening' to `TRUE` unless the backend is already opened. This function finishes opening phase, thus it should be finished with `e_book_backend_notify_opened()`.

See information at `e_book_backend_open()` for more details how the opening phase works.

`backend` : | an EBookBackend
`cancellable` : | a GCancellable for the operation
`credentials` : | ECredentials to use for authentication

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

    void                e_book_backend_notify_update        (EBookBackend *backend,
                                                             const 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_auth_required ()

    void                e_book_backend_notify_auth_required (EBookBackend *backend,
                                                             gboolean is_self,
                                                             const ECredentials *credentials);

Notifies clients that `backend` requires authentication in order to connect. This function call does not influence 'opening', but influences 'opened' property, which is set to `FALSE` when `is_self` is `TRUE` or `credentials` is `NULL`. Opening phase is finished by `e_book_backend_notify_opened()` if this is requested for `backend`.

See `e_book_backend_open()` for a description how the whole opening phase works.

Meant to be used by backend implementations.

`backend` : | an EBookBackend
`is_self` : | Use `TRUE` to indicate the authentication is required for the `backend`, otheriwse the authentication is for any other source. Having `credentials` `NULL` means `is_self` automatically.
`credentials` : | an ECredentials that contains extra information for a source for which authentication is requested. This parameter can be `NULL` to indicate "for this book".

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

### struct EBookBackendClass

    struct EBookBackendClass {
    	GObjectClass parent_class;

    	/* Virtual methods */
            void (* get_backend_property) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *prop_name);
            void (* set_backend_property) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *prop_name, const gchar *prop_value);

    	void (* open)			(EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, gboolean only_if_exists);
    	void (* remove)			(EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable);
    	void (* set_online)			(EBookBackend *backend, gboolean is_online);
    	void (* authenticate_user)		(EBookBackend *backend, GCancellable *cancellable, ECredentials *credentials);

    	void (* refresh)			(EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable);
    	void (* create_contact)		(EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *vcard);
    	void (* remove_contacts)		(EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const GSList *id_list);
    	void (* modify_contact)		(EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *vcard);
    	void (* get_contact)			(EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *id);
    	void (* get_contact_list)		(EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *query);
    	void (* get_contact_list_uids) (EBookBackend *backend, EDataBook *book, guint32 opid, GCancellable *cancellable, const gchar *query);

    	void (* start_book_view)		(EBookBackend *backend, EDataBookView *book_view);
    	void (* stop_book_view)		(EBookBackend *backend, EDataBookView *book_view);

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

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