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 .

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.

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

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.

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.

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

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 .

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.

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.

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 .

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.

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

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 .

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.

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

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 .

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

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 .

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 .

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

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 .

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 .

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

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 .

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 .

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

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 .

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 .

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

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.

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 .

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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.

Since: 3.12

e_book_client_new ()

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

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

Since: 3.2

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

BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS

#define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS "supported-auth-methods"

Since: 3.2

The “locale” property

  “locale”                   gchar *

The currently active locale for this addressbook.

Flags: Read

Default value: NULL

Since: 3.12