## EBookClient

EBookClient — Accessing and modifying an addressbook

## Synopsis

    #include <libebook/libebook.h>

    #define             BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS
    #define             BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS
    struct              EBookClient;
    struct              EBookClientClass;
    EClient *           e_book_client_connect_sync          (ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_connect               (ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    EClient *           e_book_client_connect_finish        (GAsyncResult *result,
                                                             GError **error);
    EClient *           e_book_client_connect_direct_sync   (ESourceRegistry *registry,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_connect_direct        (ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    EClient *           e_book_client_connect_direct_finish (GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_client_get_self              (ESourceRegistry *registry,
                                                             EContact **out_contact,
                                                             EBookClient **out_client,
                                                             GError **error);
    gboolean            e_book_client_set_self              (EBookClient *client,
                                                             EContact *contact,
                                                             GError **error);
    gboolean            e_book_client_is_self               (EContact *contact);
    void                e_book_client_add_contact           (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_add_contact_finish    (EBookClient *client,
                                                             GAsyncResult *result,
                                                             gchar **out_added_uid,
                                                             GError **error);
    gboolean            e_book_client_add_contact_sync      (EBookClient *client,
                                                             EContact *contact,
                                                             gchar **out_added_uid,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_add_contacts          (EBookClient *client,
                                                             GSList *contacts,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_add_contacts_finish   (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GSList **out_added_uids,
                                                             GError **error);
    gboolean            e_book_client_add_contacts_sync     (EBookClient *client,
                                                             GSList *contacts,
                                                             GSList **out_added_uids,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_modify_contact        (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_modify_contact_finish (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_client_modify_contact_sync   (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_modify_contacts       (EBookClient *client,
                                                             GSList *contacts,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_modify_contacts_finish
                                                            (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_client_modify_contacts_sync  (EBookClient *client,
                                                             GSList *contacts,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_remove_contact        (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_remove_contact_finish (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_client_remove_contact_sync   (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_remove_contact_by_uid (EBookClient *client,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_remove_contact_by_uid_finish
                                                            (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_client_remove_contact_by_uid_sync
                                                            (EBookClient *client,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_remove_contacts       (EBookClient *client,
                                                             const GSList *uids,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_remove_contacts_finish
                                                            (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_book_client_remove_contacts_sync  (EBookClient *client,
                                                             const GSList *uids,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_get_contact           (EBookClient *client,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_get_contact_finish    (EBookClient *client,
                                                             GAsyncResult *result,
                                                             EContact **out_contact,
                                                             GError **error);
    gboolean            e_book_client_get_contact_sync      (EBookClient *client,
                                                             const gchar *uid,
                                                             EContact **out_contact,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_get_contacts          (EBookClient *client,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_get_contacts_finish   (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GSList **out_contacts,
                                                             GError **error);
    gboolean            e_book_client_get_contacts_sync     (EBookClient *client,
                                                             const gchar *sexp,
                                                             GSList **out_contacts,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_get_contacts_uids     (EBookClient *client,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_get_contacts_uids_finish
                                                            (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GSList **out_contact_uids,
                                                             GError **error);
    gboolean            e_book_client_get_contacts_uids_sync
                                                            (EBookClient *client,
                                                             const gchar *sexp,
                                                             GSList **out_contact_uids,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_get_view              (EBookClient *client,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_get_view_finish       (EBookClient *client,
                                                             GAsyncResult *result,
                                                             EBookClientView **out_view,
                                                             GError **error);
    gboolean            e_book_client_get_view_sync         (EBookClient *client,
                                                             const gchar *sexp,
                                                             EBookClientView **out_view,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_client_get_cursor            (EBookClient *client,
                                                             const gchar *sexp,
                                                             const EContactField *sort_fields,
                                                             const EBookCursorSortType *sort_types,
                                                             guint n_fields,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_book_client_get_cursor_finish     (EBookClient *client,
                                                             GAsyncResult *result,
                                                             EBookClientCursor **out_cursor,
                                                             GError **error);
    gboolean            e_book_client_get_cursor_sync       (EBookClient *client,
                                                             const gchar *sexp,
                                                             const EContactField *sort_fields,
                                                             const EBookCursorSortType *sort_types,
                                                             guint n_fields,
                                                             EBookClientCursor **out_cursor,
                                                             GCancellable *cancellable,
                                                             GError **error);
    const gchar *       e_book_client_get_locale            (EBookClient *client);
    #define             BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS
    EBookClient *       e_book_client_new                   (ESource *source,
                                                             GError **error);

## Description

This class is the main user facing API for accessing and modifying the addressbook.

## Details

### BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

    #define             BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

FIXME: Document me.

Since 3.2

### BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

    #define             BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

FIXME: Document me.

Since 3.2

### struct EBookClient

    struct EBookClient {
    };

Contains only private data that should be read and manipulated using the functions below.

Since 3.2

### struct EBookClientClass

    struct EBookClientClass {
    };

Class structure for the EBookClient class.

Since 3.2

### e_book_client_connect_sync ()

    EClient *           e_book_client_connect_sync          (ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);

Creates a new EBookClient for `source`. If an error occurs, the function will set `error` and return `FALSE`.

Unlike with `e_book_client_new()`, there is no need to call `e_client_open_sync()` after obtaining the EBookClient.

For error handling convenience, any error message returned by this function will have a descriptive prefix that includes the display name of `source`.

`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | a new EBookClient, or `NULL`. [transfer full][type EBookClient]

Since 3.8

### e_book_client_connect ()

    void                e_book_client_connect               (ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously creates a new EBookClient for `source`.

Unlike with `e_book_client_new()`, there is no need to call `e_client_open()` after obtaining the EBookClient.

When the operation is finished, `callback` will be called. You can then call `e_book_client_connect_finish()` to get the result of the operation.

`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

Since 3.8

### e_book_client_connect_finish ()

    EClient *           e_book_client_connect_finish        (GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_book_client_connect()`. If an error occurs in connecting to the D-Bus service, the function sets `error` and returns `NULL`.

For error handling convenience, any error message returned by this function will have a descriptive prefix that includes the display name of the ESource passed to `e_book_client_connect()`.

`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | a new EBookClient, or `NULL`. [transfer full][type EBookClient]

Since 3.8

### e_book_client_connect_direct_sync ()

    EClient *           e_book_client_connect_direct_sync   (ESourceRegistry *registry,
                                                             ESource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);

Like `e_book_client_connect_sync()`, except creates the book client for direct read access to the underlying addressbook.

`registry` : | an ESourceRegistry
`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`
Returns : | a new but unopened EBookClient. [transfer full][type EBookClient]

Since 3.8

### e_book_client_connect_direct ()

    void                e_book_client_connect_direct        (ESource *source,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Like `e_book_client_connect()`, except creates the book client for direct read access to the underlying addressbook.

When the operation is finished, `callback` will be called. You can then call `e_book_client_connect_direct_finish()` to get the result of the operation.

`source` : | an ESource
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to the callback function. [closure]

Since 3.12

### e_book_client_connect_direct_finish ()

    EClient *           e_book_client_connect_direct_finish (GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_book_client_connect_direct()`. If an error occurs in connecting to the D-Bus service, the function sets `error` and returns `NULL`.

For error handling convenience, any error message returned by this function will have a descriptive prefix that includes the display name of the ESource passed to `e_book_client_connect_direct()`.

`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`
Returns : | a new EBookClient, or `NULL`. [transfer full][type EBookClient]

Since 3.12

### e_book_client_get_self ()

    gboolean            e_book_client_get_self              (ESourceRegistry *registry,
                                                             EContact **out_contact,
                                                             EBookClient **out_client,
                                                             GError **error);

Get the EContact referring to the user of the address book and set it in `out_contact` and `out_client`.

`registry` : | an ESourceRegistry
`out_contact` : | an EContact pointer to set. [out]
`out_client` : | an EBookClient pointer to set. [out]
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, otherwise `FALSE`.

Since 3.2

### e_book_client_set_self ()

    gboolean            e_book_client_set_self              (EBookClient *client,
                                                             EContact *contact,
                                                             GError **error);

Specify that `contact` residing in `client` is the EContact that refers to the user of the address book.

`client` : | an EBookClient
`contact` : | an EContact
`error` : | a GError to set on failure
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_is_self ()

    gboolean            e_book_client_is_self               (EContact *contact);

Check if `contact` is the user of the address book.

`contact` : | an EContact
Returns : | `TRUE` if `contact` is the user, `FALSE` otherwise.

Since 3.2

### e_book_client_add_contact ()

    void                e_book_client_add_contact           (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Adds `contact` to `client`. The call is finished by `e_book_client_add_contact_finish()` from the `callback`.

`client` : | an EBookClient
`contact` : | an EContact
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_add_contact_finish ()

    gboolean            e_book_client_add_contact_finish    (EBookClient *client,
                                                             GAsyncResult *result,
                                                             gchar **out_added_uid,
                                                             GError **error);

Finishes previous call of `e_book_client_add_contact()` and sets `out_added_uid` to a UID of a newly added contact. This string should be freed with `g_free()`.

Note: This is not modifying original EContact.

`client` : | an EBookClient
`result` : | a GAsyncResult
`out_added_uid` : | UID of a newly added contact; can be `NULL`. [out]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_add_contact_sync ()

    gboolean            e_book_client_add_contact_sync      (EBookClient *client,
                                                             EContact *contact,
                                                             gchar **out_added_uid,
                                                             GCancellable *cancellable,
                                                             GError **error);

Adds `contact` to `client` and sets `out_added_uid` to a UID of a newly added contact. This string should be freed with `g_free()`.

Note: This is not modifying original `contact`, thus if it's needed, then use e_contact_set (contact, E_CONTACT_UID, new_uid).

`client` : | an EBookClient
`contact` : | an EContact
`out_added_uid` : | UID of a newly added contact; can be `NULL`. [out]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_add_contacts ()

    void                e_book_client_add_contacts          (EBookClient *client,
                                                             GSList *contacts,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Adds `contacts` to `client`. The call is finished by `e_book_client_add_contacts_finish()` from the `callback`.

`client` : | an EBookClient
`contacts` : | a GSList of EContact objects to add. [element-type EContact]
`cancellable` : | a GCancellable; can be `NULL`. [allow-none]
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.4

### e_book_client_add_contacts_finish ()

    gboolean            e_book_client_add_contacts_finish   (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GSList **out_added_uids,
                                                             GError **error);

Finishes previous call of `e_book_client_add_contacts()` and sets `out_added_uids` to the UIDs of newly added contacts if successful. This GSList should be freed with `e_client_util_free_string_slist()`.

If any of the contacts cannot be inserted, all of the insertions will be reverted and this method will return `FALSE`.

Note: This is not modifying original EContact objects.

`client` : | an EBookClient
`result` : | a GAsyncResult
`out_added_uids` : | UIDs of newly added contacts; can be `NULL`. [out][element-type utf8][allow-none]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.4

### e_book_client_add_contacts_sync ()

    gboolean            e_book_client_add_contacts_sync     (EBookClient *client,
                                                             GSList *contacts,
                                                             GSList **out_added_uids,
                                                             GCancellable *cancellable,
                                                             GError **error);

Adds `contacts` to `client` and sets `out_added_uids` to the UIDs of newly added contacts if successful. This GSList should be freed with `e_client_util_free_string_slist()`.

If any of the contacts cannot be inserted, all of the insertions will be reverted and this method will return `FALSE`.

Note: This is not modifying original `contacts`, thus if it's needed, then use e_contact_set (contact, E_CONTACT_UID, new_uid).

`client` : | an EBookClient
`contacts` : | a GSList of EContact objects to add. [element-type EContact]
`out_added_uids` : | UIDs of newly added contacts; can be `NULL`. [out][element-type utf8][allow-none]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.4

### e_book_client_modify_contact ()

    void                e_book_client_modify_contact        (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Applies the changes made to `contact` to the stored version in `client`. The call is finished by `e_book_client_modify_contact_finish()` from the `callback`.

`client` : | an EBookClient
`contact` : | an EContact
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_modify_contact_finish ()

    gboolean            e_book_client_modify_contact_finish (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes previous call of `e_book_client_modify_contact()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_modify_contact_sync ()

    gboolean            e_book_client_modify_contact_sync   (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GError **error);

Applies the changes made to `contact` to the stored version in `client`.

`client` : | an EBookClient
`contact` : | an EContact
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_modify_contacts ()

    void                e_book_client_modify_contacts       (EBookClient *client,
                                                             GSList *contacts,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Applies the changes made to `contacts` to the stored versions in `client`. The call is finished by `e_book_client_modify_contacts_finish()` from the `callback`.

`client` : | an EBookClient
`contacts` : | a GSList of EContact objects. [element-type EContact]
`cancellable` : | a GCancellable; can be `NULL`. [allow-none]
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.4

### e_book_client_modify_contacts_finish ()

    gboolean            e_book_client_modify_contacts_finish
                                                            (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes previous call of `e_book_client_modify_contacts()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.4

### e_book_client_modify_contacts_sync ()

    gboolean            e_book_client_modify_contacts_sync  (EBookClient *client,
                                                             GSList *contacts,
                                                             GCancellable *cancellable,
                                                             GError **error);

Applies the changes made to `contacts` to the stored versions in `client`.

`client` : | an EBookClient
`contacts` : | a GSList of EContact objects. [element-type EContact]
`cancellable` : | a GCancellable; can be `NULL`. [allow-none]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.4

### e_book_client_remove_contact ()

    void                e_book_client_remove_contact        (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Removes `contact` from the `client`. The call is finished by `e_book_client_remove_contact_finish()` from the `callback`.

`client` : | an EBookClient
`contact` : | an EContact
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_remove_contact_finish ()

    gboolean            e_book_client_remove_contact_finish (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes previous call of `e_book_client_remove_contact()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_remove_contact_sync ()

    gboolean            e_book_client_remove_contact_sync   (EBookClient *client,
                                                             EContact *contact,
                                                             GCancellable *cancellable,
                                                             GError **error);

Removes `contact` from the `client`.

`client` : | an EBookClient
`contact` : | an EContact
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_remove_contact_by_uid ()

    void                e_book_client_remove_contact_by_uid (EBookClient *client,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Removes contact with `uid` from the `client`. The call is finished by `e_book_client_remove_contact_by_uid_finish()` from the `callback`.

`client` : | an EBookClient
`uid` : | a UID of a contact to remove
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_remove_contact_by_uid_finish ()

    gboolean            e_book_client_remove_contact_by_uid_finish
                                                            (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes previous call of `e_book_client_remove_contact_by_uid()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_remove_contact_by_uid_sync ()

    gboolean            e_book_client_remove_contact_by_uid_sync
                                                            (EBookClient *client,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GError **error);

Removes contact with `uid` from the `client`.

`client` : | an EBookClient
`uid` : | a UID of a contact to remove
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_remove_contacts ()

    void                e_book_client_remove_contacts       (EBookClient *client,
                                                             const GSList *uids,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Removes the contacts with uids from the list `uids` from `client`. This is always more efficient than calling `e_book_client_remove_contact()` if you have more than one uid to remove, as some backends can implement it as a batch request. The call is finished by `e_book_client_remove_contacts_finish()` from the `callback`.

`client` : | an EBookClient
`uids` : | a GSList of UIDs to remove. [element-type utf8]
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_remove_contacts_finish ()

    gboolean            e_book_client_remove_contacts_finish
                                                            (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes previous call of `e_book_client_remove_contacts()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_remove_contacts_sync ()

    gboolean            e_book_client_remove_contacts_sync  (EBookClient *client,
                                                             const GSList *uids,
                                                             GCancellable *cancellable,
                                                             GError **error);

Removes the contacts with uids from the list `uids` from `client`. This is always more efficient than calling `e_book_client_remove_contact()` if you have more than one uid to remove, as some backends can implement it as a batch request.

`client` : | an EBookClient
`uids` : | a GSList of UIDs to remove. [element-type utf8]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_contact ()

    void                e_book_client_get_contact           (EBookClient *client,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Receive EContact from the `client` for the gived `uid`. The call is finished by `e_book_client_get_contact_finish()` from the `callback`.

`client` : | an EBookClient
`uid` : | a unique string ID specifying the contact
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_get_contact_finish ()

    gboolean            e_book_client_get_contact_finish    (EBookClient *client,
                                                             GAsyncResult *result,
                                                             EContact **out_contact,
                                                             GError **error);

Finishes previous call of `e_book_client_get_contact()`. If successful, then the `out_contact` is set to newly allocated EContact, which should be freed with `g_object_unref()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`out_contact` : | an EContact for previously given uid. [out]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_contact_sync ()

    gboolean            e_book_client_get_contact_sync      (EBookClient *client,
                                                             const gchar *uid,
                                                             EContact **out_contact,
                                                             GCancellable *cancellable,
                                                             GError **error);

Receive EContact from the `client` for the gived `uid`. If successful, then the `out_contact` is set to newly allocated EContact, which should be freed with `g_object_unref()`.

`client` : | an EBookClient
`uid` : | a unique string ID specifying the contact
`out_contact` : | an EContact for given `uid`. [out]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_contacts ()

    void                e_book_client_get_contacts          (EBookClient *client,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Query `client` with `sexp`, receiving a list of contacts which matched. The call is finished by `e_book_client_get_contacts_finish()` from the `callback`.

Note: `sexp` can be obtained through EBookQuery, by converting it to a string with `e_book_query_to_string()`.

`client` : | an EBookClient
`sexp` : | an S-expression representing the query
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_get_contacts_finish ()

    gboolean            e_book_client_get_contacts_finish   (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GSList **out_contacts,
                                                             GError **error);

Finishes previous call of `e_book_client_get_contacts()`. If successful, then the `out_contacts` is set to newly allocated list of EContact-s, which should be freed with `e_client_util_free_object_slist()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`out_contacts` : | a GSList of matched EContact-s. [element-type EContact][out][transfer full]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_contacts_sync ()

    gboolean            e_book_client_get_contacts_sync     (EBookClient *client,
                                                             const gchar *sexp,
                                                             GSList **out_contacts,
                                                             GCancellable *cancellable,
                                                             GError **error);

Query `client` with `sexp`, receiving a list of contacts which matched. If successful, then the `out_contacts` is set to newly allocated GSList of EContact-s, which should be freed with `e_client_util_free_object_slist()`.

Note: `sexp` can be obtained through EBookQuery, by converting it to a string with `e_book_query_to_string()`.

`client` : | an EBookClient
`sexp` : | an S-expression representing the query
`out_contacts` : | a GSList of matched EContact-s. [element-type EContact][out]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_contacts_uids ()

    void                e_book_client_get_contacts_uids     (EBookClient *client,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Query `client` with `sexp`, receiving a list of contacts UIDs which matched. The call is finished by `e_book_client_get_contacts_uids_finish()` from the `callback`.

Note: `sexp` can be obtained through EBookQuery, by converting it to a string with `e_book_query_to_string()`.

`client` : | an EBookClient
`sexp` : | an S-expression representing the query
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_get_contacts_uids_finish ()

    gboolean            e_book_client_get_contacts_uids_finish
                                                            (EBookClient *client,
                                                             GAsyncResult *result,
                                                             GSList **out_contact_uids,
                                                             GError **error);

Finishes previous call of `e_book_client_get_contacts_uids()`. If successful, then the `out_contact_uids` is set to newly allocated list of UID strings, which should be freed with `e_client_util_free_string_slist()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`out_contact_uids` : | a GSList of matched contact UIDs stored as strings. [element-type utf8][out]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_contacts_uids_sync ()

    gboolean            e_book_client_get_contacts_uids_sync
                                                            (EBookClient *client,
                                                             const gchar *sexp,
                                                             GSList **out_contact_uids,
                                                             GCancellable *cancellable,
                                                             GError **error);

Query `client` with `sexp`, receiving a list of contacts UIDs which matched. If successful, then the `out_contact_uids` is set to newly allocated list of UID strings, which should be freed with `e_client_util_free_string_slist()`.

Note: `sexp` can be obtained through EBookQuery, by converting it to a string with `e_book_query_to_string()`.

`client` : | an EBookClient
`sexp` : | an S-expression representing the query
`out_contact_uids` : | a GSList of matched contacts UIDs stored as strings. [element-type utf8][out]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_view ()

    void                e_book_client_get_view              (EBookClient *client,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Query `client` with `sexp`, creating an EBookClientView. The call is finished by `e_book_client_get_view_finish()` from the `callback`.

Note: `sexp` can be obtained through EBookQuery, by converting it to a string with `e_book_query_to_string()`.

`client` : | an EBookClient
`sexp` : | an S-expression representing the query
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.2

### e_book_client_get_view_finish ()

    gboolean            e_book_client_get_view_finish       (EBookClient *client,
                                                             GAsyncResult *result,
                                                             EBookClientView **out_view,
                                                             GError **error);

Finishes previous call of `e_book_client_get_view()`. If successful, then the `out_view` is set to newly allocated EBookClientView, which should be freed with `g_object_unref()`.

`client` : | an EBookClient
`result` : | a GAsyncResult
`out_view` : | an EBookClientView. [out]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_view_sync ()

    gboolean            e_book_client_get_view_sync         (EBookClient *client,
                                                             const gchar *sexp,
                                                             EBookClientView **out_view,
                                                             GCancellable *cancellable,
                                                             GError **error);

Query `client` with `sexp`, creating an EBookClientView. If successful, then the `out_view` is set to newly allocated EBookClientView, which should be freed with `g_object_unref()`.

Note: `sexp` can be obtained through EBookQuery, by converting it to a string with `e_book_query_to_string()`.

`client` : | an EBookClient
`sexp` : | an S-expression representing the query
`out_view` : | (out) an EBookClientView
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.2

### e_book_client_get_cursor ()

    void                e_book_client_get_cursor            (EBookClient *client,
                                                             const gchar *sexp,
                                                             const EContactField *sort_fields,
                                                             const EBookCursorSortType *sort_types,
                                                             guint n_fields,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Create an EBookClientCursor. The call is finished by `e_book_client_get_view_finish()` from the `callback`.

Note: `sexp` can be obtained through EBookQuery, by converting it to a string with `e_book_query_to_string()`.

`client` : | an EBookClient
`sexp` : | an S-expression representing the query
`sort_fields` : | an array of EContactFields to sort the cursor with
`sort_types` : | an array of EBookCursorSortTypes to complement `sort_fields`
`n_fields` : | the length of the input `sort_fields` and `sort_types` arrays
`cancellable` : | a GCancellable; can be `NULL`
`callback` : | callback to call when a result is ready
`user_data` : | user data for the `callback`

Since 3.12

### e_book_client_get_cursor_finish ()

    gboolean            e_book_client_get_cursor_finish     (EBookClient *client,
                                                             GAsyncResult *result,
                                                             EBookClientCursor **out_cursor,
                                                             GError **error);

Finishes previous call of `e_book_client_get_cursor()`. If successful, then the `out_cursor` is set to newly create EBookClientCursor, the cursor should be freed with `g_object_unref()` when no longer needed.

`client` : | an EBookClient
`result` : | a GAsyncResult
`out_cursor` : | return location for an EBookClientCursor. [out]
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.12

### e_book_client_get_cursor_sync ()

    gboolean            e_book_client_get_cursor_sync       (EBookClient *client,
                                                             const gchar *sexp,
                                                             const EContactField *sort_fields,
                                                             const EBookCursorSortType *sort_types,
                                                             guint n_fields,
                                                             EBookClientCursor **out_cursor,
                                                             GCancellable *cancellable,
                                                             GError **error);

Create an EBookClientCursor. If successful, then the `out_cursor` is set to newly allocated EBookClientCursor, the cursor should be freed with `g_object_unref()` when no longer needed.

Note: `sexp` can be obtained through EBookQuery, by converting it to a string with `e_book_query_to_string()`.

`client` : | an EBookClient
`sexp` : | an S-expression representing the query
`sort_fields` : | an array of EContactFields to sort the cursor with
`sort_types` : | an array of EBookCursorSortTypes to complement `sort_fields`
`n_fields` : | the length of the input `sort_fields` and `sort_types` arrays
`out_cursor` : | return location for an EBookClientCursor. [out]
`cancellable` : | a GCancellable; can be `NULL`
`error` : | a GError to set an error, if any. [out]
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 3.12

### e_book_client_get_locale ()

    const gchar *       e_book_client_get_locale            (EBookClient *client);

Reports the locale in use for `client`. The addressbook might sort contacts in different orders, or store and compare phone numbers in different ways depending on the currently set locale.

Locales can change dynamically if systemd decides to change the locale, so it's important to listen for notifications on the "locale" property if you depend on sorted result lists. Ordered results should be reloaded after a locale change is detected.

`client` : | an EBookClient
Returns : | The currently set locale for `client`. [transfer none]

Since 3.12

### BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS

    #define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS "supported-auth-methods"

### Warning

`BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS` has been deprecated since version 3.8 and should not be used in newly-written code. The property is no longer supported.

Since 3.2

### e_book_client_new ()

    EBookClient *       e_book_client_new                   (ESource *source,
                                                             GError **error);

### Warning

`e_book_client_new` has been deprecated since version 3.8 and should not be used in newly-written code. It covertly makes synchronous D-Bus calls, with no way to cancel. Use `e_book_client_connect()` instead, which combines `e_book_client_new()` and `e_client_open()` into one step.

Creates a new EBookClient corresponding to the given source. There are only two operations that are valid on this book at this point: `e_client_open()`, and `e_client_remove()`.

`source` : | An ESource pointer
`error` : | A GError pointer
Returns : | a new but unopened EBookClient.

Since 3.2