Top | ![]() |
![]() |
![]() |
![]() |
#define | BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS |
#define | BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS |
struct | EBookClient |
struct | EBookClientClass |
#define | BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS |
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 |
[allow-none] |
error |
return location for a |
Since: 3.8
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 |
[allow-none] |
callback |
a |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
Since: 3.8
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
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 |
||
source |
an ESource |
|
wait_for_connected_seconds |
timeout, in seconds, to wait for the backend to be fully connected |
|
cancellable |
optional |
[allow-none] |
error |
return location for a |
Since: 3.8
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 |
[allow-none] |
callback |
a |
[scope async] |
user_data |
data to pass to the callback function. |
[closure] |
Since: 3.12
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
gboolean e_book_client_get_self (ESourceRegistry *registry
,,
EContact **out_contactEBookClient **out_client
,);
GError **error
Get the out_contact
and out_client
.
registry |
||
out_contact |
an |
[out] |
out_client |
an EBookClient pointer to set. |
[out] |
error |
a |
Since: 3.2
gboolean e_book_client_set_self (EBookClient *client
,,
EContact *contact);
GError **error
Specify that contact
residing in client
is the
Since: 3.2
gboolean e_book_client_is_self ();
EContact *contact
Check if contact
is the user of the address book.
Since: 3.2
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 |
|
cancellable |
a |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
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
client |
an EBookClient |
|
result |
a |
|
out_added_uid |
UID of a newly added contact; can be |
[out] |
error |
a |
[out] |
Since: 3.2
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 |
|
out_added_uid |
UID of a newly added contact; can be |
[out] |
cancellable |
a |
|
error |
a |
[out] |
Since: 3.2
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 |
[element-type EContact] |
cancellable |
a |
[allow-none] |
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.4
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 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
client |
an EBookClient |
|
result |
a |
|
out_added_uids |
UIDs of
newly added contacts; can be |
[out][element-type utf8][allow-none] |
error |
a |
[out] |
Since: 3.4
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 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 |
[element-type EContact] |
out_added_uids |
UIDs of newly
added contacts; can be |
[out][element-type utf8][allow-none] |
cancellable |
a |
|
error |
a |
[out] |
Since: 3.4
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 |
|
cancellable |
a |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
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 |
|
error |
a |
[out] |
Since: 3.2
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 |
|
cancellable |
a |
|
error |
a |
[out] |
Since: 3.2
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 |
[element-type EContact] |
cancellable |
a |
[allow-none] |
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.4
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 |
|
error |
a |
[out] |
Since: 3.4
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 |
[element-type EContact] |
cancellable |
a |
[allow-none] |
error |
a |
[out] |
Since: 3.4
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 |
|
cancellable |
a |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
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 |
|
error |
a |
[out] |
Since: 3.2
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 |
|
cancellable |
a |
|
error |
a |
[out] |
Since: 3.2
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 |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
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 |
|
error |
a |
[out] |
Since: 3.2
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 |
|
error |
a |
[out] |
Since: 3.2
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 |
[element-type utf8] |
cancellable |
a |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
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 |
|
error |
a |
[out] |
Since: 3.2
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 |
[element-type utf8] |
cancellable |
a |
|
error |
a |
[out] |
Since: 3.2
void e_book_client_get_contact (EBookClient *client
,const
,gchar *uid,
GCancellable *cancellable,
GAsyncReadyCallback callback);
gpointer user_data
Receive 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 |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
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
g_object_unref()
client |
an EBookClient |
|
result |
a |
|
out_contact |
an |
[out] |
error |
a |
[out] |
Since: 3.2
gboolean e_book_client_get_contact_sync (EBookClient *client
,const
,gchar *uid,
EContact **out_contact,
GCancellable *cancellable);
GError **error
Receive client
for the gived uid
.
If successful, then the out_contact
is set to newly allocated
g_object_unref()
client |
an EBookClient |
|
uid |
a unique string ID specifying the contact |
|
out_contact |
an |
[out] |
cancellable |
a |
|
error |
a |
[out] |
Since: 3.2
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 e_book_query_to_string()
.
client |
an EBookClient |
|
sexp |
an S-expression representing the query |
|
cancellable |
a |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
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
e_client_util_free_object_slist()
.
client |
an EBookClient |
|
result |
a |
|
out_contacts |
a |
[element-type EContact][out][transfer full] |
error |
a |
[out] |
Since: 3.2
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 e_client_util_free_object_slist()
.
Note: sexp
can be obtained through e_book_query_to_string()
.
client |
an EBookClient |
|
sexp |
an S-expression representing the query |
|
out_contacts |
a |
[element-type EContact][out] |
cancellable |
a |
|
error |
a |
[out] |
Since: 3.2
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 e_book_query_to_string()
.
client |
an EBookClient |
|
sexp |
an S-expression representing the query |
|
cancellable |
a |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
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 |
|
out_contact_uids |
a |
[element-type utf8][out] |
error |
a |
[out] |
Since: 3.2
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 e_book_query_to_string()
.
client |
an EBookClient |
|
sexp |
an S-expression representing the query |
|
out_contact_uids |
a |
[element-type utf8][out] |
cancellable |
a |
|
error |
a |
[out] |
Since: 3.2
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 e_book_query_to_string()
.
client |
an EBookClient |
|
sexp |
an S-expression representing the query |
|
cancellable |
a |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.2
gboolean e_book_client_get_view_finish (EBookClient *client
,,
GAsyncResult *resultEBookClientView **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 |
|
out_view |
an EBookClientView. |
[out] |
error |
a |
[out] |
Since: 3.2
gboolean e_book_client_get_view_sync (EBookClient *client
,const
,gchar *sexpEBookClientView **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 e_book_query_to_string()
.
client |
an EBookClient |
|
sexp |
an S-expression representing the query |
|
out_view |
an EBookClientView. |
[out] |
cancellable |
a |
|
error |
a |
[out] |
Since: 3.2
void e_book_client_get_cursor (EBookClient *client
,const
,gchar *sexpconst 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 e_book_query_to_string()
.
client |
an EBookClient |
|
sexp |
an S-expression representing the query |
|
sort_fields |
an array of |
|
sort_types |
an array of |
|
n_fields |
the length of the input |
|
cancellable |
a |
|
callback |
callback to call when a result is ready |
|
user_data |
user data for the |
Since: 3.12
gboolean e_book_client_get_cursor_finish (EBookClient *client
,,
GAsyncResult *resultEBookClientCursor **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()
client |
an EBookClient |
|
result |
a |
|
out_cursor |
return location for an EBookClientCursor. |
[out] |
error |
a |
[out] |
Since: 3.12
gboolean e_book_client_get_cursor_sync (EBookClient *client
,const
,gchar *sexpconst EContactField *sort_fields
,const EBookCursorSortType *sort_types
,,
guint n_fieldsEBookClientCursor **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()
Note: sexp
can be obtained through e_book_query_to_string()
.
client |
an EBookClient |
|
sexp |
an S-expression representing the query |
|
sort_fields |
an array of |
|
sort_types |
an array of |
|
n_fields |
the length of the input |
|
out_cursor |
return location for an EBookClientCursor. |
[out] |
cancellable |
a |
|
error |
a |
[out] |
Since: 3.12
constgchar * 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
Since: 3.12
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()
.
Since: 3.2
#define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS
FIXME: Document me.
Since: 3.2
#define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS
FIXME: Document me.
Since: 3.2
struct EBookClient { };
Contains only private data that should be read and manipulated using the functions below.
Since: 3.2
struct EBookClientClass { };
Class structure for the EBookClient class.
Since: 3.2