| 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"
FIXME: Document me.
Since 3.2
#define BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS "supported-fields"
FIXME: Document me.
Since 3.2
#define BOOK_BACKEND_PROPERTY_SUPPORTED_AUTH_METHODS "supported-auth-methods"
FIXME: Document me.
Since 3.2
#define E_BOOK_CLIENT_ERROR e_book_client_error_quark ()
FIXME: Document me.
Since 3.2
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;
FIXME: Document me.
Since 3.2
const gchar * e_book_client_error_to_string (EBookClientError code);
FIXME: Document me.
Since 3.2
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(). |
Since 3.2
struct EBookClient;
Contains only private data that should be read and manipulated using the functions below.
Since 3.2
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