EBookBackend

EBookBackend — An abstract class for implementing addressbook backends

Synopsis

#include <libedata-book/libedata-book.h>

#define             CLIENT_BACKEND_PROPERTY_CAPABILITIES
#define             BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS
#define             BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS
#define             BOOK_BACKEND_PROPERTY_REVISION
struct              EBookBackend;
struct              EBookBackendClass;
const gchar *       e_book_backend_get_cache_dir        (EBookBackend *backend);
gchar *             e_book_backend_dup_cache_dir        (EBookBackend *backend);
void                e_book_backend_set_cache_dir        (EBookBackend *backend,
                                                         const gchar *cache_dir);
EDataBook *         e_book_backend_ref_data_book        (EBookBackend *backend);
void                e_book_backend_set_data_book        (EBookBackend *backend,
                                                         EDataBook *data_book);
GProxyResolver *    e_book_backend_ref_proxy_resolver   (EBookBackend *backend);
ESourceRegistry *   e_book_backend_get_registry         (EBookBackend *backend);
gboolean            e_book_backend_get_writable         (EBookBackend *backend);
void                e_book_backend_set_writable         (EBookBackend *backend,
                                                         gboolean writable);
gboolean            e_book_backend_is_opened            (EBookBackend *backend);
gboolean            e_book_backend_is_readonly          (EBookBackend *backend);
gchar *             e_book_backend_get_backend_property (EBookBackend *backend,
                                                         const gchar *prop_name);
gboolean            e_book_backend_open_sync            (EBookBackend *backend,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_backend_open                 (EBookBackend *backend,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_book_backend_open_finish          (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            e_book_backend_refresh_sync         (EBookBackend *backend,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_backend_refresh              (EBookBackend *backend,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_book_backend_refresh_finish       (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            e_book_backend_create_contacts_sync (EBookBackend *backend,
                                                         const gchar * const *vcards,
                                                         GQueue *out_contacts,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_backend_create_contacts      (EBookBackend *backend,
                                                         const gchar * const *vcards,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_book_backend_create_contacts_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GQueue *out_contacts,
                                                         GError **error);
gboolean            e_book_backend_modify_contacts_sync (EBookBackend *backend,
                                                         const gchar * const *vcards,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_backend_modify_contacts      (EBookBackend *backend,
                                                         const gchar * const *vcards,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_book_backend_modify_contacts_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            e_book_backend_remove_contacts_sync (EBookBackend *backend,
                                                         const gchar * const *uids,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                         const gchar * const *uids,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_book_backend_remove_contacts_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);
EContact *          e_book_backend_get_contact_sync     (EBookBackend *backend,
                                                         const gchar *uid,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_backend_get_contact          (EBookBackend *backend,
                                                         const gchar *uid,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
EContact *          e_book_backend_get_contact_finish   (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);
gboolean            e_book_backend_get_contact_list_sync
                                                        (EBookBackend *backend,
                                                         const gchar *query,
                                                         GQueue *out_contacts,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_backend_get_contact_list     (EBookBackend *backend,
                                                         const gchar *query,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_book_backend_get_contact_list_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GQueue *out_contacts,
                                                         GError **error);
gboolean            e_book_backend_get_contact_list_uids_sync
                                                        (EBookBackend *backend,
                                                         const gchar *query,
                                                         GQueue *out_uids,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                e_book_backend_get_contact_list_uids
                                                        (EBookBackend *backend,
                                                         const gchar *query,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
gboolean            e_book_backend_get_contact_list_uids_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GQueue *out_uids,
                                                         GError **error);
void                e_book_backend_start_view           (EBookBackend *backend,
                                                         EDataBookView *view);
void                e_book_backend_stop_view            (EBookBackend *backend,
                                                         EDataBookView *view);
void                e_book_backend_add_view             (EBookBackend *backend,
                                                         EDataBookView *view);
void                e_book_backend_remove_view          (EBookBackend *backend,
                                                         EDataBookView *view);
GList *             e_book_backend_list_views           (EBookBackend *backend);
void                e_book_backend_notify_update        (EBookBackend *backend,
                                                         const EContact *contact);
void                e_book_backend_notify_remove        (EBookBackend *backend,
                                                         const gchar *id);
void                e_book_backend_notify_complete      (EBookBackend *backend);
void                e_book_backend_notify_error         (EBookBackend *backend,
                                                         const gchar *message);
void                e_book_backend_notify_property_changed
                                                        (EBookBackend *backend,
                                                         const gchar *prop_name,
                                                         const gchar *prop_value);
EDataBookDirect *   e_book_backend_get_direct_book      (EBookBackend *backend);
void                e_book_backend_configure_direct     (EBookBackend *backend,
                                                         const gchar *config);
void                e_book_backend_sync                 (EBookBackend *backend);
gboolean            e_book_backend_set_locale           (EBookBackend *backend,
                                                         const gchar *locale,
                                                         GCancellable *cancellable,
                                                         GError **error);
gchar *             e_book_backend_dup_locale           (EBookBackend *backend);
EDataBookCursor *   e_book_backend_create_cursor        (EBookBackend *backend,
                                                         EContactField *sort_fields,
                                                         EBookCursorSortType *sort_types,
                                                         guint n_fields,
                                                         GError **error);
gboolean            e_book_backend_delete_cursor        (EBookBackend *backend,
                                                         EDataBookCursor *cursor,
                                                         GError **error);
GSimpleAsyncResult * e_book_backend_prepare_for_completion
                                                        (EBookBackend *backend,
                                                         guint32 opid,
                                                         GQueue **result_queue);

Description

This is the main server facing API for interfacing with addressbook backends, addressbook backends must implement methods on this class.

Details

CLIENT_BACKEND_PROPERTY_CAPABILITIES

#define             CLIENT_BACKEND_PROPERTY_CAPABILITIES

FIXME: Document me.

Since 3.2


BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

#define             BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

FIXME: Document me.

Since 3.2


BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

#define             BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

FIXME: Document me.

Since 3.2


BOOK_BACKEND_PROPERTY_REVISION

#define BOOK_BACKEND_PROPERTY_REVISION			"revision"

The current overall revision string, this can be used as a quick check to see if data has changed at all since the last time the addressbook revision was observed.

Since 3.4


struct EBookBackend

struct EBookBackend {
};

Contains only private data that should be read and manipulated using the functions below.


struct EBookBackendClass

struct EBookBackendClass {
	/* Set this to TRUE to use a serial dispatch queue, instead
	 * of a concurrent dispatch queue.  A serial dispatch queue
	 * executes one method at a time in the order in which they
	 * were called.  This is generally slower than a concurrent
	 * dispatch queue, but helps avoid thread-safety issues. */
	gboolean use_serial_dispatch_queue;

	gchar *		(*get_backend_property) (EBookBackend *backend,
						 const gchar *prop_name);

	gboolean (*open_sync)		(EBookBackend *backend,
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*refresh_sync)		(EBookBackend *backend,
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*create_contacts_sync) (EBookBackend *backend,
						 const gchar * const *vcards,
						 GQueue *out_contacts,
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*modify_contacts_sync) (EBookBackend *backend,
						 const gchar * const *vcards,
						 GQueue *out_contacts,
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*remove_contacts_sync) (EBookBackend *backend,
						 const gchar * const *uids,
						 GCancellable *cancellable,
						 GError **error);
	EContact * (*get_contact_sync) (EBookBackend *backend,
						 const gchar *uid,
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*get_contact_list_sync)
						(EBookBackend *backend,
						 const gchar *query,
						 GQueue *out_contacts,
						 GCancellable *cancellable,
						 GError **error);

	/* This method is optional.  By default, it simply calls
	 * get_contact_list_sync() and extracts UID strings from
	 * the matched EContacts.  Backends may override this if
	 * they can implement it more efficiently. */
	gboolean (*get_contact_list_uids_sync)
						(EBookBackend *backend,
						 const gchar *query,
						 GQueue *out_uids,
						 GCancellable *cancellable,
						 GError **error);

	/* These methods are deprecated and will be removed once all
	 * known subclasses are converted to the new methods above. */
	void		(*open)			(EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 gboolean only_if_exists);
	void		(*refresh)		(EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable);
	void		(*create_contacts) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const GSList *vcards);
	void		(*remove_contacts) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const GSList *id_list);
	void		(*modify_contacts) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const GSList *vcards);
	void		(*get_contact)		(EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar *id);
	void		(*get_contact_list) (EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar *query);
	void		(*get_contact_list_uids)
						(EBookBackend *backend,
						 EDataBook *book,
						 guint32 opid,
						 GCancellable *cancellable,
						 const gchar *query);

	void		(*start_view)		(EBookBackend *backend,
						 EDataBookView *book_view);
	void		(*stop_view)		(EBookBackend *backend,
						 EDataBookView *book_view);

	void		(*notify_update) (EBookBackend *backend,
						 const EContact *contact);

	EDataBookDirect *
			(*get_direct_book) (EBookBackend *backend);
	void		(*configure_direct) (EBookBackend *backend,
						 const gchar *config);

	void		(*sync)			(EBookBackend *backend);

	gboolean (*set_locale)		(EBookBackend *backend,
						 const gchar *locale,
						 GCancellable *cancellable,
						 GError **error);
	gchar *		(*dup_locale)		(EBookBackend *backend);
	EDataBookCursor *
			(*create_cursor) (EBookBackend *backend,
						 EContactField *sort_fields,
						 EBookCursorSortType *sort_types,
						 guint n_fields,
						 GError **error);
	gboolean (*delete_cursor) (EBookBackend *backend,
						 EDataBookCursor *cursor,
						 GError **error);

	/* Signals */
	void		(*closed)		(EBookBackend *backend,
						 const gchar *sender);
	void		(*shutdown)		(EBookBackend *backend);
};

Class structure for the EBookBackend class.

These virtual methods must be implemented when writing an addressbook backend.

gboolean use_serial_dispatch_queue;

Whether a serial dispatch queue should be used for this backend or not.

get_backend_property ()

Fetch a property value by name from the backend

open_sync ()

Open the backend

refresh_sync ()

Refresh the backend

create_contacts_sync ()

Add and store the passed vcards

modify_contacts_sync ()

Modify the existing contacts using the passed vcards

remove_contacts_sync ()

Remove the contacts specified by the passed UIDs

get_contact_sync ()

Fetch a contact by UID

get_contact_list_sync ()

Fetch a list of contacts based on a search expression

get_contact_list_uids_sync ()

Fetch a list of contact UIDs based on a search expression (optional)

open ()

Deprecated method

refresh ()

Deprecated method

create_contacts ()

Deprecated method

remove_contacts ()

Deprecated method

modify_contacts ()

Deprecated method

get_contact ()

Deprecated method

get_contact_list ()

Deprecated method

get_contact_list_uids ()

Deprecated method

start_view ()

Start up the specified view

stop_view ()

Stop the specified view

notify_update ()

Notify changes which might have occured for a given contact

get_direct_book ()

For addressbook backends which support Direct Read Access, report some information on how to access the addressbook persistance directly

configure_direct ()

For addressbook backends which support Direct Read Access, configure a backend instantiated on the client side for Direct Read Access, using data reported from the server via the get_direct_book method.

sync ()

Sync the backend's persistance

set_locale ()

Store & remember the passed locale setting

dup_locale ()

Return the currently set locale setting (must be a string duplicate, for thread safety).

create_cursor ()

Create an EDataBookCursor

delete_cursor ()

Delete an EDataBookCursor previously created by this backend

closed ()

A signal notifying that the backend was closed

shutdown ()

A signal notifying that the backend is being shut down

e_book_backend_get_cache_dir ()

const gchar *       e_book_backend_get_cache_dir        (EBookBackend *backend);

Returns the cache directory path used by backend.

backend :

an EBookBackend

Returns :

the cache directory path

Since 2.32


e_book_backend_dup_cache_dir ()

gchar *             e_book_backend_dup_cache_dir        (EBookBackend *backend);

Thread-safe variation of e_book_backend_get_cache_dir(). Use this function when accessing backend from multiple threads.

The returned string should be freed with g_free() when no longer needed.

backend :

an EBookBackend

Returns :

a newly-allocated copy of "cache-dir"

Since 3.10


e_book_backend_set_cache_dir ()

void                e_book_backend_set_cache_dir        (EBookBackend *backend,
                                                         const gchar *cache_dir);

Sets the cache directory path for use by backend.

Note that EBookBackend is initialized with a default cache directory path which should suffice for most cases. Backends should not override the default path without good reason.

backend :

an EBookBackend

cache_dir :

a local cache directory path

Since 2.32


e_book_backend_ref_data_book ()

EDataBook *         e_book_backend_ref_data_book        (EBookBackend *backend);

Returns the EDataBook for backend. The EDataBook is essentially the glue between incoming D-Bus requests and backend's native API.

An EDataBook should be set only once after backend is first created. If an EDataBook has not yet been set, the function returns NULL.

The returned EDataBook is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

backend :

an EBookBackend

Returns :

an EDataBook, or NULL

Since 3.10


e_book_backend_set_data_book ()

void                e_book_backend_set_data_book        (EBookBackend *backend,
                                                         EDataBook *data_book);

Sets the EDataBook for backend. The EDataBook is essentially the glue between incoming D-Bus requests and backend's native API.

An EDataBook should be set only once after backend is first created.

backend :

an EBookBackend

data_book :

an EDataBook

Since 3.10


e_book_backend_ref_proxy_resolver ()

GProxyResolver *    e_book_backend_ref_proxy_resolver   (EBookBackend *backend);

Returns the GProxyResolver for backend (if applicable), as indicated by the "proxy-uid" of backend's "source" or one of its ancestors.

The returned GProxyResolver is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

backend :

an EBookBackend

Returns :

a GProxyResolver, or NULL

Since 3.12


e_book_backend_get_registry ()

ESourceRegistry *   e_book_backend_get_registry         (EBookBackend *backend);

Returns the data source registry to which "source" belongs.

backend :

an EBookBackend

Returns :

an ESourceRegistry

Since 3.6


e_book_backend_get_writable ()

gboolean            e_book_backend_get_writable         (EBookBackend *backend);

Returns whether backend will accept changes to its data content.

backend :

an EBookBackend

Returns :

whether backend is writable

Since 3.8


e_book_backend_set_writable ()

void                e_book_backend_set_writable         (EBookBackend *backend,
                                                         gboolean writable);

Sets whether backend will accept changes to its data content.

backend :

an EBookBackend

writable :

whether backend is writable

Since 3.8


e_book_backend_is_opened ()

gboolean            e_book_backend_is_opened            (EBookBackend *backend);

Checks if backend's storage has been opened (and authenticated, if necessary) and the backend itself is ready for accessing. This property is changed automatically within call of e_book_backend_notify_opened().

backend :

an EBookBackend

Returns :

TRUE if fully opened, FALSE otherwise.

Since 3.2


e_book_backend_is_readonly ()

gboolean            e_book_backend_is_readonly          (EBookBackend *backend);

Checks if we can write to backend.

backend :

an EBookBackend

Returns :

TRUE if read-only, FALSE if not.

Since 3.2


e_book_backend_get_backend_property ()

gchar *             e_book_backend_get_backend_property (EBookBackend *backend,
                                                         const gchar *prop_name);

Obtains the value of the backend property named prop_name. Freed the returned string with g_free() when finished with it.

backend :

an EBookBackend

prop_name :

a backend property name

Returns :

the value for prop_name

Since 3.10


e_book_backend_open_sync ()

gboolean            e_book_backend_open_sync            (EBookBackend *backend,
                                                         GCancellable *cancellable,
                                                         GError **error);

"Opens" the backend. Opening a backend is something of an outdated concept, but the operation is hanging around for a little while longer. This usually involves some custom initialization logic, and testing of remote authentication if applicable.

If an error occurs, the function will set error and return FALSE.

backend :

an EBookBackend

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_open ()

void                e_book_backend_open                 (EBookBackend *backend,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously "opens" the backend. Opening a backend is something of an outdated concept, but the operation is hanging around for a little while longer. This usually involves some custom initialization logic, and testing of remote authentication if applicable.

When the operation is finished, callback will be called. You can then call e_book_backend_open_finish() to get the result of the operation.

backend :

an EBookBackend

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.10


e_book_backend_open_finish ()

gboolean            e_book_backend_open_finish          (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_book_backend_open().

If an error occurred, the function will set error and return FALSE.

backend :

an EBookBackend

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_refresh_sync ()

gboolean            e_book_backend_refresh_sync         (EBookBackend *backend,
                                                         GCancellable *cancellable,
                                                         GError **error);

Initiates a refresh for backend, if the backend supports refreshing. The actual refresh operation completes on its own time. This function merely initiates the operation.

If an error occurs while initiating the refresh, the function will set error and return FALSE. If the backend does not support refreshing, the function will set an E_CLIENT_ERROR_NOT_SUPPORTED error and return FALSE.

backend :

an EBookBackend

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_refresh ()

void                e_book_backend_refresh              (EBookBackend *backend,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously initiates a refresh for backend, if the backend supports refreshing. The actual refresh operation completes on its own time. This function, along with e_book_backend_refresh_finish(), merely initiates the operation.

Once the refresh is initiated, callback will be called. You can then call e_book_backend_refresh_finish() to get the result of the initiation.

backend :

an EBookBackend

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.10


e_book_backend_refresh_finish ()

gboolean            e_book_backend_refresh_finish       (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the refresh initiation started with e_book_backend_refresh().

If an error occurred while initiating the refresh, the function will set error and return FALSE. If the backend does not support refreshing, the function will set an E_CLIENT_ERROR_NOT_SUPPORTED error and return FALSE.

backend :

an EBookBackend

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_create_contacts_sync ()

gboolean            e_book_backend_create_contacts_sync (EBookBackend *backend,
                                                         const gchar * const *vcards,
                                                         GQueue *out_contacts,
                                                         GCancellable *cancellable,
                                                         GError **error);

Creates one or more new contacts from vcards, and deposits an EContact instance for each newly-created contact in out_contacts.

The returned EContact instances are referenced for thread-safety and must be unreferenced with g_object_unref() when finished with them.

If an error occurs, the function will set error and return FALSE.

backend :

an EBookBackend

vcards :

a NULL-terminated array of vCard strings

out_contacts :

a GQueue in which to deposit results

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_create_contacts ()

void                e_book_backend_create_contacts      (EBookBackend *backend,
                                                         const gchar * const *vcards,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously creates one or more new contacts from vcards.

When the operation is finished, callback will be called. You can then call e_book_backend_create_contacts_finish() to get the result of the operation.

backend :

an EBookBackend

vcards :

a NULL-terminated array of vCard strings

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.10


e_book_backend_create_contacts_finish ()

gboolean            e_book_backend_create_contacts_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GQueue *out_contacts,
                                                         GError **error);

Finishes the operation started with e_book_backend_create_contacts().

An EContact instance for each newly-created contact is deposited in out_contacts. The returned EContact instances are referenced for thread-safety and must be unreferenced with g_object_unref() when finished with them.

If an error occurred, the function will set error and return FALSE.

backend :

an EBookBackend

result :

a GAsyncResult

out_contacts :

a GQueue in which to deposit results

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_modify_contacts_sync ()

gboolean            e_book_backend_modify_contacts_sync (EBookBackend *backend,
                                                         const gchar * const *vcards,
                                                         GCancellable *cancellable,
                                                         GError **error);

Modifies one or more contacts according to vcards.

If an error occurs, the function will set error and return FALSE.

backend :

an EBookBackend

vcards :

a NULL-terminated array of vCard strings

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_modify_contacts ()

void                e_book_backend_modify_contacts      (EBookBackend *backend,
                                                         const gchar * const *vcards,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously modifies one or more contacts according to vcards.

When the operation is finished, callback will be called. You can then call e_book_backend_modify_contacts_finish() to get the result of the operation.

backend :

an EBookBackend

vcards :

a NULL-terminated array of vCard strings

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.10


e_book_backend_modify_contacts_finish ()

gboolean            e_book_backend_modify_contacts_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_book_backend_modify_contacts().

If an error occurred, the function will set error and return FALSE.

backend :

an EBookBackend

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_remove_contacts_sync ()

gboolean            e_book_backend_remove_contacts_sync (EBookBackend *backend,
                                                         const gchar * const *uids,
                                                         GCancellable *cancellable,
                                                         GError **error);

Removes one or more contacts according to uids.

If an error occurs, the function will set error and return FALSE.

backend :

an EBookBackend

uids :

a NULL-terminated array of contact ID strings

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_remove_contacts ()

void                e_book_backend_remove_contacts      (EBookBackend *backend,
                                                         const gchar * const *uids,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously removes one or more contacts according to uids.

When the operation is finished, callback will be called. You can then call e_book_backend_remove_contacts_finish() to get the result of the operation.

backend :

an EBookBackend

uids :

a NULL-terminated array of contact ID strings

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.10


e_book_backend_remove_contacts_finish ()

gboolean            e_book_backend_remove_contacts_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_book_backend_remove_contacts().

If an error occurred, the function will set error and return FALSE.

backend :

an EBookBackend

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_get_contact_sync ()

EContact *          e_book_backend_get_contact_sync     (EBookBackend *backend,
                                                         const gchar *uid,
                                                         GCancellable *cancellable,
                                                         GError **error);

Obtains an EContact for uid.

The returned EContact is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

If an error occurs, the function will set error and return NULL.

backend :

an EBookBackend

uid :

a contact ID

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

an EContact, or NULL

Since 3.10


e_book_backend_get_contact ()

void                e_book_backend_get_contact          (EBookBackend *backend,
                                                         const gchar *uid,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously obtains an EContact for uid.

When the operation is finished, callback will be called. You can then call e_book_backend_get_contact_finish() to get the result of the operation.

backend :

an EBookBackend

uid :

a contact ID

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.10


e_book_backend_get_contact_finish ()

EContact *          e_book_backend_get_contact_finish   (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GError **error);

Finishes the operation started with e_book_backend_get_contact_finish().

The returned EContact is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

If an error occurred, the function will set error and return NULL.

backend :

an EBookBackend

result :

a GAsyncResult

error :

return location for a GError, or NULL

Returns :

an EContact, or NULL

Since 3.10


e_book_backend_get_contact_list_sync ()

gboolean            e_book_backend_get_contact_list_sync
                                                        (EBookBackend *backend,
                                                         const gchar *query,
                                                         GQueue *out_contacts,
                                                         GCancellable *cancellable,
                                                         GError **error);

Obtains a set of EContact instances which satisfy the criteria specified in query, and deposits them in out_contacts.

The returned EContact instances are referenced for thread-safety and must be unreferenced with g_object_unref() when finished with them.

If an error occurs, the function will set error and return FALSE. Note that an empty result set does not necessarily imply an error.

backend :

an EBookBackend

query :

a search query in S-expression format

out_contacts :

a GQueue in which to deposit results

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_get_contact_list ()

void                e_book_backend_get_contact_list     (EBookBackend *backend,
                                                         const gchar *query,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously obtains a set of EContact instances which satisfy the criteria specified in query.

When the operation is finished, callback will be called. You can then call e_book_backend_get_contact_list_finish() to get the result of the operation.

backend :

an EBookBackend

query :

a search query in S-expression format

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.10


e_book_backend_get_contact_list_finish ()

gboolean            e_book_backend_get_contact_list_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GQueue *out_contacts,
                                                         GError **error);

Finishes the operation started with e_book_backend_get_contact_list().

The matching EContact instances are deposited in out_contacts. The returned EContact instances are referenced for thread-safety and must be unreferenced with g_object_unref() when finished with them.

If an error occurred, the function will set error and return FALSE. Note that an empty result set does not necessarily imply an error.

backend :

an EBookBackend

result :

a GAsyncResult

out_contacts :

a GQueue in which to deposit results

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_get_contact_list_uids_sync ()

gboolean            e_book_backend_get_contact_list_uids_sync
                                                        (EBookBackend *backend,
                                                         const gchar *query,
                                                         GQueue *out_uids,
                                                         GCancellable *cancellable,
                                                         GError **error);

Obtains a set of ID strings for contacts which satisfy the criteria specified in query, and deposits them in out_uids.

The returned ID strings must be freed with g_free() with finished with them.

If an error occurs, the function will set error and return FALSE. Note that an empty result set does not necessarily imply an error.

backend :

an EBookBackend

query :

a search query in S-expression format

out_uids :

a GQueue in which to deposit results

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_get_contact_list_uids ()

void                e_book_backend_get_contact_list_uids
                                                        (EBookBackend *backend,
                                                         const gchar *query,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Asynchronously obtains a set of ID strings for contacts which satisfy the criteria specified in query.

When the operation is finished, callback will be called. You can then call e_book_backend_get_contact_list_uids_finish() to get the result of the operation.

backend :

an EBookBackend

query :

a search query in S-expression format

cancellable :

optional GCancellable object, or NULL

callback :

a GAsyncReadyCallback to call when the request is satisfied

user_data :

data to pass to the callback function

Since 3.10


e_book_backend_get_contact_list_uids_finish ()

gboolean            e_book_backend_get_contact_list_uids_finish
                                                        (EBookBackend *backend,
                                                         GAsyncResult *result,
                                                         GQueue *out_uids,
                                                         GError **error);

Finishes the operation started with e_book_backend_get_contact_list_uids_finish().

ID strings for the matching contacts are deposited in out_uids, and must be freed with g_free() when finished with them.

If an error occurs, the function will set error and return FALSE. Note that an empty result set does not necessarily imply an error.

backend :

an EBookBackend

result :

a GAsyncResult

out_uids :

a GQueue in which to deposit results

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.10


e_book_backend_start_view ()

void                e_book_backend_start_view           (EBookBackend *backend,
                                                         EDataBookView *view);

Starts running the query specified by view, emitting signals for matching contacts.

backend :

an EBookBackend

view :

the EDataBookView to start

e_book_backend_stop_view ()

void                e_book_backend_stop_view            (EBookBackend *backend,
                                                         EDataBookView *view);

Stops running the query specified by view, emitting no more signals.

backend :

an EBookBackend

view :

the EDataBookView to stop

e_book_backend_add_view ()

void                e_book_backend_add_view             (EBookBackend *backend,
                                                         EDataBookView *view);

Adds view to backend for querying.

backend :

an EBookBackend

view :

an EDataBookView

e_book_backend_remove_view ()

void                e_book_backend_remove_view          (EBookBackend *backend,
                                                         EDataBookView *view);

Removes view from backend.

backend :

an EBookBackend

view :

an EDataBookView

e_book_backend_list_views ()

GList *             e_book_backend_list_views           (EBookBackend *backend);

Returns a list of EDataBookView instances added with e_book_backend_add_view().

The views returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list properly in one step is as follows:

backend :

an EBookBackend

Returns :

a list of book views

Since 3.8


e_book_backend_notify_update ()

void                e_book_backend_notify_update        (EBookBackend *backend,
                                                         const EContact *contact);

Notifies all of backend's book views about the new or modified contacts contact.

e_data_book_respond_create_contacts() and e_data_book_respond_modify_contacts() call this function for you. You only need to call this from your backend if contacts are created or modified by another (non-PAS-using) client.

backend :

an EBookBackend

contact :

a new or modified contact

e_book_backend_notify_remove ()

void                e_book_backend_notify_remove        (EBookBackend *backend,
                                                         const gchar *id);

Notifies all of backend's book views that the contact with UID id has been removed.

e_data_book_respond_remove_contacts() calls this function for you. You only need to call this from your backend if contacts are removed by another (non-PAS-using) client.

backend :

an EBookBackend

id :

a contact id

e_book_backend_notify_complete ()

void                e_book_backend_notify_complete      (EBookBackend *backend);

Notifies all of backend's book views that the current set of notifications is complete; use this after a series of e_book_backend_notify_update() and e_book_backend_notify_remove() calls.

backend :

an EBookbackend

e_book_backend_notify_error ()

void                e_book_backend_notify_error         (EBookBackend *backend,
                                                         const gchar *message);

Notifies each backend listener about an error. This is meant to be used for cases where is no GError return possibility, to notify user about an issue.

backend :

an EBookBackend

message :

an error message

Since 3.2


e_book_backend_notify_property_changed ()

void                e_book_backend_notify_property_changed
                                                        (EBookBackend *backend,
                                                         const gchar *prop_name,
                                                         const gchar *prop_value);

Notifies clients about property value change.

backend :

an EBookBackend

prop_name :

property name, which changed

prop_value :

new property value

Since 3.2


e_book_backend_get_direct_book ()

EDataBookDirect *   e_book_backend_get_direct_book      (EBookBackend *backend);

Tries to create an EDataBookDirect for backend if backend supports direct read access.

backend :

an EBookBackend

Returns :

A new EDataBookDirect object, or NULL if backend does not support direct access. [transfer full]

Since 3.8


e_book_backend_configure_direct ()

void                e_book_backend_configure_direct     (EBookBackend *backend,
                                                         const gchar *config);

This method is called on backend in direct read access mode. The config argument is the same configuration string which the same backend reported in the EDataBookDirect returned by e_book_backend_get_direct_book().

The configuration string is optional and is used to ensure that direct access backends are properly configured to interface with the same data as the running server side backend.

backend :

an EBookBackend

config :

The configuration string for the given backend

Since 3.8


e_book_backend_sync ()

void                e_book_backend_sync                 (EBookBackend *backend);

Write all pending data to disk. This is only required under special circumstances (for example before a live backup) and should not be used in normal use.

backend :

an EBookbackend

Since 1.12


e_book_backend_set_locale ()

gboolean            e_book_backend_set_locale           (EBookBackend *backend,
                                                         const gchar *locale,
                                                         GCancellable *cancellable,
                                                         GError **error);

Notify the addressbook backend that the current locale has changed, this is important for backends which support ordered result lists which are locale sensitive.

backend :

an EBookbackend

locale :

the new locale for the addressbook

cancellable :

optional GCancellable object, or NULL

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

Since 3.12


e_book_backend_dup_locale ()

gchar *             e_book_backend_dup_locale           (EBookBackend *backend);

Fetches a copy of the currently configured locale for the addressbook

backend :

an EBookbackend

Since 3.12


e_book_backend_create_cursor ()

EDataBookCursor *   e_book_backend_create_cursor        (EBookBackend *backend,
                                                         EContactField *sort_fields,
                                                         EBookCursorSortType *sort_types,
                                                         guint n_fields,
                                                         GError **error);

Creates a new EDataBookCursor for the given backend if the backend has cursor support. If the backend does not support cursors then an E_CLIENT_ERROR_NOT_SUPPORTED error will be set in error.

Backends can also refuse to create cursors for some values of sort_fields and report more specific errors.

The returned cursor belongs to backend and should be destroyed with e_book_backend_delete_cursor() when no longer needed.

backend :

an EBookBackend

sort_fields :

the EContactFields to sort by

sort_types :

the EBookCursorSortTypes for the sorted fields

n_fields :

the number of fields in the sort_fields and sort_types

error :

return location for a GError, or NULL

Returns :

A newly created cursor, the cursor belongs to the backend and should not be unreffed, or NULL. [transfer none]

Since 3.12


e_book_backend_delete_cursor ()

gboolean            e_book_backend_delete_cursor        (EBookBackend *backend,
                                                         EDataBookCursor *cursor,
                                                         GError **error);

Requests backend to release and destroy cursor, this will trigger an E_CLIENT_ERROR_INVALID_ARG error if cursor is not owned by backend.

backend :

an EBookBackend

cursor :

the EDataBookCursor to destroy

error :

return location for a GError, or NULL

Returns :

Whether cursor was successfully deleted.

Since 3.12


e_book_backend_prepare_for_completion ()

GSimpleAsyncResult * e_book_backend_prepare_for_completion
                                                        (EBookBackend *backend,
                                                         guint32 opid,
                                                         GQueue **result_queue);

Obtains the GSimpleAsyncResult for opid and sets result_queue as a place to deposit results prior to completing the GSimpleAsyncResult.

Note

This is a temporary function to serve EDataBook's "respond" functions until they can be removed. Nothing else should be calling this function.

backend :

an EBookBackend

opid :

an operation ID given to EDataBook

result_queue :

return location for a GQueue, or NULL

Returns :

a GSimpleAsyncResult. [transfer full]

Since 3.10