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,
                                                         guint32 wait_for_connected_seconds,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_client_connect               (ESource *source,
                                                         guint32 wait_for_connected_seconds,
                                                         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,
                                                         guint32 wait_for_connected_seconds,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_client_connect_direct        (ESource *source,
                                                         guint32 wait_for_connected_seconds,
                                                         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,
                                                         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.

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.

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

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.

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.

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

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