![]() |
![]() |
![]() |
Evolution-Data-Server Manual: Address Book Client (libebook) | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS #define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS #define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS #define E_BOOK_CLIENT_ERROR enum EBookClientError; const gchar * e_book_client_error_to_string (EBookClientError code
); GError * e_book_client_error_create (EBookClientError code
,const gchar *custom_msg
); struct EBookClient; EBookClient * e_book_client_new (ESource *source
,GError **error
); EBookClient * e_book_client_new_from_uri (const gchar *uri
,GError **error
); EBookClient * e_book_client_new_system (GError **error
); EBookClient * e_book_client_new_default (GError **error
); gboolean e_book_client_set_default (EBookClient *client
,GError **error
); gboolean e_book_client_set_default_source (ESource *source
,GError **error
); gboolean e_book_client_get_sources (ESourceList **sources
,GError **error
); gboolean e_book_client_get_self (EContact **contact
,EBookClient **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 **added_uid
,GError **error
); gboolean e_book_client_add_contact_sync (EBookClient *client
,EContact *contact
,gchar **added_uid
,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_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 **contact
,GError **error
); gboolean e_book_client_get_contact_sync (EBookClient *client
,const gchar *uid
,EContact **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 **contacts
,GError **error
); gboolean e_book_client_get_contacts_sync (EBookClient *client
,const gchar *sexp
,GSList **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 **contacts_uids
,GError **error
); gboolean e_book_client_get_contacts_uids_sync (EBookClient *client
,const gchar *sexp
,GSList **contacts_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 **view
,GError **error
); gboolean e_book_client_get_view_sync (EBookClient *client
,const gchar *sexp
,EBookClientView **view
,GCancellable *cancellable
,GError **error
);
#define BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS "required-fields"
#define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS "supported-fields"
#define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS "supported-auth-methods"
typedef enum { E_BOOK_CLIENT_ERROR_NO_SUCH_BOOK, E_BOOK_CLIENT_ERROR_CONTACT_NOT_FOUND, E_BOOK_CLIENT_ERROR_CONTACT_ID_ALREADY_EXISTS, E_BOOK_CLIENT_ERROR_NO_SUCH_SOURCE, E_BOOK_CLIENT_ERROR_NO_SPACE } EBookClientError;
const gchar * e_book_client_error_to_string (EBookClientError code
);
GError * e_book_client_error_create (EBookClientError code
,const gchar *custom_msg
);
|
an EBookClientError code to create |
|
custom message to use for the error; can be NULL
|
Returns : |
a new GError containing an E_BOOK_CLIENT_ERROR of the given
code . If the custom_msg is NULL, then the error message is
the one returned from e_book_client_error_to_string() for the code ,
otherwise the given message is used.
Returned pointer should be freed with g_error_free() . |
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()
.
|
An ESource pointer |
|
A GError pointer |
Returns : |
a new but unopened EBookClient. |
Since 3.2
EBookClient * e_book_client_new_from_uri (const gchar *uri
,GError **error
);
Creates a new EBookClient corresponding to the given uri. See the
documentation for e_book_client_new()
for further information.
|
the URI to load |
|
A GError pointer |
Returns : |
a new but unopened EBookClient. |
Since 3.2
EBookClient * e_book_client_new_system (GError **error
);
Creates a new EBookClient corresponding to the user's system
addressbook. See the documentation for e_book_client_new()
for further
information.
|
A GError pointer |
Returns : |
a new but unopened EBookClient. |
Since 3.2
EBookClient * e_book_client_new_default (GError **error
);
Creates a new EBookClient corresponding to the user's default
address book. See the documentation for e_book_client_new()
for
further information.
|
return location for a GError, or NULL
|
Returns : |
a new but unopened EBookClient |
Since 3.2
gboolean e_book_client_set_default (EBookClient *client
,GError **error
);
Sets the ESource of the EBookClient as the "default" addressbook. This is the source
that will be loaded in the e_book_client_get_default_addressbook()
call.
|
An EBookClient pointer |
|
A GError pointer |
Returns : |
TRUE if the setting was stored in libebook's ESourceList, otherwise FALSE . |
Since 3.2
gboolean e_book_client_set_default_source (ESource *source
,GError **error
);
Sets source
as the "default" addressbook. This is the source that
will be loaded in the e_book_client_get_default_addressbook()
call.
|
An ESource pointer |
|
A GError pointer |
Returns : |
TRUE if the setting was stored in libebook's ESourceList, otherwise FALSE . |
Since 3.2
gboolean e_book_client_get_sources (ESourceList **sources
,GError **error
);
Populate @*sources with the list of all sources which have been added to Evolution.
|
A pointer to an ESourceList to set. [out] |
|
A pointer to a GError to set on error |
Returns : |
TRUE if sources was set, otherwise FALSE . |
Since 3.2
gboolean e_book_client_get_self (EContact **contact
,EBookClient **client
,GError **error
);
Get the EContact referring to the user of the address book
and set it in contact
and client
.
|
an EContact pointer to set. [out] |
|
an EBookClient pointer to set. [out] |
|
a GError to set on failure |
Returns : |
TRUE if successful, otherwise FALSE . |
Since 3.2
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.
|
an EBookClient |
|
an EContact |
|
a GError to set on failure |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
gboolean e_book_client_is_self (EContact *contact
);
Check if contact
is the user of the address book.
|
an EContact |
Returns : |
TRUE if contact is the user, FALSE otherwise. |
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
.
|
an EBookClient |
|
an EContact |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
Since 3.2
gboolean e_book_client_add_contact_finish (EBookClient *client
,GAsyncResult *result
,gchar **added_uid
,GError **error
);
Finishes previous call of e_book_client_add_contact()
and
sets 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.
|
an EBookClient |
|
a GAsyncResult |
|
UID of a newly added contact; can be NULL . [out]
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
gboolean e_book_client_add_contact_sync (EBookClient *client
,EContact *contact
,gchar **added_uid
,GCancellable *cancellable
,GError **error
);
Adds contact
to client
and
sets 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).
|
an EBookClient |
|
an EContact |
|
UID of a newly added contact; can be NULL . [out]
|
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
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
.
|
an EBookClient |
|
an EContact |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
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()
.
|
an EBookClient |
|
a GAsyncResult |
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
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
.
|
an EBookClient |
|
an EContact |
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
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
.
|
an EBookClient |
|
an EContact |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
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()
.
|
an EBookClient |
|
a GAsyncResult |
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
gboolean e_book_client_remove_contact_sync (EBookClient *client
,EContact *contact
,GCancellable *cancellable
,GError **error
);
Removes contact
from the client
.
|
an EBookClient |
|
an EContact |
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
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
.
|
an EBookClient |
|
a UID of a contact to remove |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
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()
.
|
an EBookClient |
|
a GAsyncResult |
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
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
.
|
an EBookClient |
|
a UID of a contact to remove |
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
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
.
|
an EBookClient |
|
a GSList of UIDs to remove. [element-type utf8] |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
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()
.
|
an EBookClient |
|
a GAsyncResult |
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
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.
|
an EBookClient |
|
a GSList of UIDs to remove. [element-type utf8] |
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
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
.
|
an EBookClient |
|
a unique string ID specifying the contact |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
Since 3.2
gboolean e_book_client_get_contact_finish (EBookClient *client
,GAsyncResult *result
,EContact **contact
,GError **error
);
Finishes previous call of e_book_client_get_contact()
.
If successful, then the contact
is set to newly allocated
EContact, which should be freed with g_object_unref()
.
|
an EBookClient |
|
a GAsyncResult |
|
an EContact for previously given uid. [out] |
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
gboolean e_book_client_get_contact_sync (EBookClient *client
,const gchar *uid
,EContact **contact
,GCancellable *cancellable
,GError **error
);
Receive EContact from the client
for the gived uid
.
If successful, then the contact
is set to newly allocated
EContact, which should be freed with g_object_unref()
.
|
an EBookClient |
|
a unique string ID specifying the contact |
|
an EContact for given uid . [out]
|
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
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 EBookQuery, by converting it
to a string with e_book_query_to_string()
.
|
an EBookClient |
|
an S-expression representing the query |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
Since 3.2
gboolean e_book_client_get_contacts_finish (EBookClient *client
,GAsyncResult *result
,GSList **contacts
,GError **error
);
Finishes previous call of e_book_client_get_contacts()
.
If successful, then the contacts
is set to newly allocated list of EContact-s,
which should be freed with e_client_util_free_object_slist()
.
|
an EBookClient |
|
a GAsyncResult |
|
a GSList of matched EContact-s. [element-type EContact][out] |
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
gboolean e_book_client_get_contacts_sync (EBookClient *client
,const gchar *sexp
,GSList **contacts
,GCancellable *cancellable
,GError **error
);
Query client
with sexp
, receiving a list of contacts which matched.
If successful, then the 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()
.
|
an EBookClient |
|
an S-expression representing the query |
|
a GSList of matched EContact-s. [element-type EContact][out] |
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
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 EBookQuery, by converting it
to a string with e_book_query_to_string()
.
|
an EBookClient |
|
an S-expression representing the query |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
Since 3.2
gboolean e_book_client_get_contacts_uids_finish (EBookClient *client
,GAsyncResult *result
,GSList **contacts_uids
,GError **error
);
Finishes previous call of e_book_client_get_contacts_uids()
.
If successful, then the contacts_uids
is set to newly allocated list
of UID strings, which should be freed with e_client_util_free_string_slist()
.
|
an EBookClient |
|
a GAsyncResult |
|
a GSList of matched contacts UIDs stored as strings. [element-type utf8][out] |
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
gboolean e_book_client_get_contacts_uids_sync (EBookClient *client
,const gchar *sexp
,GSList **contacts_uids
,GCancellable *cancellable
,GError **error
);
Query client
with sexp
, receiving a list of contacts UIDs which matched.
If successful, then the contacts_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()
.
|
an EBookClient |
|
an S-expression representing the query |
|
a GSList of matched contacts UIDs stored as strings. [element-type utf8][out] |
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
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 EBookQuery, by converting it
to a string with e_book_query_to_string()
.
|
an EBookClient |
|
an S-expression representing the query |
|
a GCancellable; can be NULL
|
|
callback to call when a result is ready |
|
user data for the callback
|
Since 3.2
gboolean e_book_client_get_view_finish (EBookClient *client
,GAsyncResult *result
,EBookClientView **view
,GError **error
);
Finishes previous call of e_book_client_get_view()
.
If successful, then the view
is set to newly allocated EBookClientView,
which should be freed with g_object_unref()
.
|
an EBookClient |
|
a GAsyncResult |
|
an EBookClientView. [out] |
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2
gboolean e_book_client_get_view_sync (EBookClient *client
,const gchar *sexp
,EBookClientView **view
,GCancellable *cancellable
,GError **error
);
Query client
with sexp
, creating an EBookClientView.
If successful, then the 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()
.
|
an EBookClient |
|
an S-expression representing the query |
|
(out) an EBookClientView |
|
a GCancellable; can be NULL
|
|
a GError to set an error, if any. [out] |
Returns : |
TRUE if successful, FALSE otherwise. |
Since 3.2