EBookClient: Evolution-Data-Server Reference Manual

## EBookClient EBookClient — Accessing and modifying an addressbook |

## Functions

EClient * | e_book_client_connect_sync ()
void | e_book_client_connect ()
EClient * | e_book_client_connect_finish ()
EClient * | e_book_client_connect_direct_sync ()
void | e_book_client_connect_direct ()
EClient * | e_book_client_connect_direct_finish ()
gboolean | e_book_client_get_self ()
gboolean | e_book_client_set_self ()
gboolean | e_book_client_is_self ()
void | e_book_client_add_contact ()
gboolean | e_book_client_add_contact_finish ()
gboolean | e_book_client_add_contact_sync ()
void | e_book_client_add_contacts ()
gboolean | e_book_client_add_contacts_finish ()
gboolean | e_book_client_add_contacts_sync ()
void | e_book_client_modify_contact ()
gboolean | e_book_client_modify_contact_finish ()
gboolean | e_book_client_modify_contact_sync ()
void | e_book_client_modify_contacts ()
gboolean | e_book_client_modify_contacts_finish ()
gboolean | e_book_client_modify_contacts_sync ()
void | e_book_client_remove_contact ()
gboolean | e_book_client_remove_contact_finish ()
gboolean | e_book_client_remove_contact_sync ()
void | e_book_client_remove_contact_by_uid ()
gboolean | e_book_client_remove_contact_by_uid_finish ()
gboolean | e_book_client_remove_contact_by_uid_sync ()
void | e_book_client_remove_contacts ()
gboolean | e_book_client_remove_contacts_finish ()
gboolean | e_book_client_remove_contacts_sync ()
void | e_book_client_get_contact ()
gboolean | e_book_client_get_contact_finish ()
gboolean | e_book_client_get_contact_sync ()
void | e_book_client_get_contacts ()
gboolean | e_book_client_get_contacts_finish ()
gboolean | e_book_client_get_contacts_sync ()
void | e_book_client_get_contacts_uids ()
gboolean | e_book_client_get_contacts_uids_finish ()
gboolean | e_book_client_get_contacts_uids_sync ()
void | e_book_client_get_view ()
gboolean | e_book_client_get_view_finish ()
gboolean | e_book_client_get_view_sync ()
void | e_book_client_get_cursor ()
gboolean | e_book_client_get_cursor_finish ()
gboolean | e_book_client_get_cursor_sync ()
const gchar * | e_book_client_get_locale ()
EBookClient * | e_book_client_new ()

## Properties

gchar * | locale | Read

## Types and Values

struct | EBookClient
struct | EBookClientClass

## Object Hierarchy

        GObject
        ╰── EClient
            ╰── EBookClient

## Implemented Interfaces

EBookClient implements GInitable and GAsyncInitable.

## Includes

    #include <libebook/libebook.h>

## Description

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

## Functions

### e_book_client_connect_sync ()

    EClient *
    e_book_client_connect_sync (ESource *source,
                                guint32 wait_for_connected_seconds,
                                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.

The `wait_for_connected_seconds` argument had been added since 3.16, to let the caller decide how long to wait for the backend to fully connect to its (possibly remote) data store. This is required due to a change in the authentication process, which is fully asynchronous and done on the client side, while not every client is supposed to response to authentication requests. In case the backend will not connect within the set interval, then it is opened in an offline mode. A special value -1 can be used to not wait for the connected state at all.

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

#### Parameters

source | an ESource |
wait_for_connected_seconds | timeout, in seconds, to wait for the backend to be fully connected |
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,
                           guint32 wait_for_connected_seconds,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Asynchronously creates a new EBookClient for `source` .

The `wait_for_connected_seconds` argument had been added since 3.16, to let the caller decide how long to wait for the backend to fully connect to its (possibly remote) data store. This is required due to a change in the authentication process, which is fully asynchronous and done on the client side, while not every client is supposed to response to authentication requests. In case the backend will not connect within the set interval, then it is opened in an offline mode. A special value -1 can be used to not wait for the connected state at all.

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.

#### Parameters

source | an ESource |
wait_for_connected_seconds | timeout, in seconds, to wait for the backend to be fully connected |
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()`.

#### Parameters

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,
                                       guint32 wait_for_connected_seconds,
                                       GCancellable *cancellable,
                                       GError **error);

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

#### Parameters

registry | an ESourceRegistry |
source | an ESource |
wait_for_connected_seconds | timeout, in seconds, to wait for the backend to be fully connected |
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,
                                  guint32 wait_for_connected_seconds,
                                  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.

#### Parameters

source | an ESource |
wait_for_connected_seconds | timeout, in seconds, to wait for the backend to be fully connected |
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()`.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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,
                               guint32 opflags,
                               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` .

#### Parameters

client | an EBookClient |
contact | an EContact |
opflags | bit-or of EBookOperationFlags |
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.

#### Parameters

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,
                                    guint32 opflags,
                                    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).

#### Parameters

client | an EBookClient |
contact | an EContact |
opflags | bit-or of EBookOperationFlags |
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,
                                guint32 opflags,
                                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` .

#### Parameters

client | an EBookClient |
contacts | a GSList of EContact objects to add. | [element-type EContact]
opflags | bit-or of EBookOperationFlags |
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.

#### Parameters

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,
                                     guint32 opflags,
                                     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).

#### Parameters

client | an EBookClient |
contacts | a GSList of EContact objects to add. | [element-type EContact]
opflags | bit-or of EBookOperationFlags |
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,
                                  guint32 opflags,
                                  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` .

#### Parameters

client | an EBookClient |
contact | an EContact |
opflags | bit-or of EBookOperationFlags |
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()`.

#### Parameters

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,
                                       guint32 opflags,
                                       GCancellable *cancellable,
                                       GError **error);

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

#### Parameters

client | an EBookClient |
contact | an EContact |
opflags | bit-or of EBookOperationFlags |
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,
                                   guint32 opflags,
                                   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` .

#### Parameters

client | an EBookClient |
contacts | a GSList of EContact objects. | [element-type EContact]
opflags | bit-or of EBookOperationFlags |
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()`.

#### Parameters

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,
                                        guint32 opflags,
                                        GCancellable *cancellable,
                                        GError **error);

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

#### Parameters

client | an EBookClient |
contacts | a GSList of EContact objects. | [element-type EContact]
opflags | bit-or of EBookOperationFlags |
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,
                                  guint32 opflags,
                                  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` .

#### Parameters

client | an EBookClient |
contact | an EContact |
opflags | bit-or of EBookOperationFlags |
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()`.

#### Parameters

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,
                                       guint32 opflags,
                                       GCancellable *cancellable,
                                       GError **error);

Removes `contact` from the `client` .

#### Parameters

client | an EBookClient |
contact | an EContact |
opflags | bit-or of EBookOperationFlags |
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,
                                         guint32 opflags,
                                         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` .

#### Parameters

client | an EBookClient |
uid | a UID of a contact to remove |
opflags | bit-or of EBookOperationFlags |
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()`.

#### Parameters

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,
                                    guint32 opflags,
                                    GCancellable *cancellable,
                                    GError **error);

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

#### Parameters

client | an EBookClient |
uid | a UID of a contact to remove |
opflags | bit-or of EBookOperationFlags |
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,
                                   guint32 opflags,
                                   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` .

#### Parameters

client | an EBookClient |
uids | a GSList of UIDs to remove. | [element-type utf8]
opflags | bit-or of EBookOperationFlags |
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()`.

#### Parameters

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,
                                        guint32 opflags,
                                        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.

#### Parameters

client | an EBookClient |
uids | a GSList of UIDs to remove. | [element-type utf8]
opflags | bit-or of EBookOperationFlags |
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` .

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

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()`.

#### Parameters

client | an EBookClient |
sexp | an S-expression representing the query |
out_view | an EBookClientView. | [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_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()`.

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

client | an EBookClient |

#### Returns

The currently set locale for `client` .

[transfer none]

Since: 3.12

### e_book_client_new ()

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

`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()`.

#### Parameters

source | An ESource pointer |
error | A GError pointer |

#### Returns

a new but unopened EBookClient.

Since: 3.2

## Types and Values

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

## Property Details

### The `“locale”` property

      “locale”                   gchar *

The currently active locale for this addressbook.

Owner: EBookClient

Flags: Read

Default value: NULL

Since: 3.12