EBookBackendSync

EBookBackendSync — An abstract class for implementing synchronous addressbook backends

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── EBackend
        ╰── EBookBackend
            ╰── EBookBackendSync
                ╰── EBookMetaBackend

Includes

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

Description

This is a descendant of the EBookBackend, providing synchronous variants of the main methods.

Functions

e_book_backend_sync_open ()

gboolean
e_book_backend_sync_open (EBookBackendSync *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.

Parameters

backend

an EBookBackendSync

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.34


e_book_backend_sync_refresh ()

gboolean
e_book_backend_sync_refresh (EBookBackendSync *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.

Parameters

backend

an EBookBackendSync

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.34


e_book_backend_sync_create_contacts ()

gboolean
e_book_backend_sync_create_contacts (EBookBackendSync *backend,
                                     const gchar * const *vcards,
                                     guint32 opflags,
                                     GSList **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.

Parameters

backend

an EBookBackendSync

 

vcards

a NULL-terminated array of vCard strings

 

opflags

bit-or of EBookOperationFlags

 

out_contacts

a GSList in which to deposit results.

[out][element-type EContact]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.34


e_book_backend_sync_modify_contacts ()

gboolean
e_book_backend_sync_modify_contacts (EBookBackendSync *backend,
                                     const gchar * const *vcards,
                                     guint32 opflags,
                                     GSList **out_contacts,
                                     GCancellable *cancellable,
                                     GError **error);

Modifies one or more contacts according to vcards .

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

Parameters

backend

an EBookBackendSync

 

vcards

a NULL-terminated array of vCard strings

 

opflags

bit-or of EBookOperationFlags

 

out_contacts

a GSList to deposit the modified contacts to.

[out][element-type EContact]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.34


e_book_backend_sync_remove_contacts ()

gboolean
e_book_backend_sync_remove_contacts (EBookBackendSync *backend,
                                     const gchar * const *uids,
                                     guint32 opflags,
                                     GSList **out_removed_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.

Parameters

backend

an EBookBackendSync

 

uids

a NULL-terminated array of contact ID strings

 

opflags

bit-or of EBookOperationFlags

 

out_removed_uids

a GSList of removed UIDs.

[out][element-type utf8]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.34


e_book_backend_sync_get_contact ()

EContact *
e_book_backend_sync_get_contact (EBookBackendSync *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.

Parameters

backend

an EBookBackendSync

 

uid

a contact ID

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

an EContact, or NULL on error.

[transfer full]

Since: 3.34


e_book_backend_sync_get_contact_list ()

gboolean
e_book_backend_sync_get_contact_list (EBookBackendSync *backend,
                                      const gchar *query,
                                      GSList **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.

Parameters

backend

an EBookBackendSync

 

query

a search query in S-expression format

 

out_contacts

a GSList in which to deposit results.

[out][element-type EContact]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.34


e_book_backend_sync_get_contact_list_uids ()

gboolean
e_book_backend_sync_get_contact_list_uids
                               (EBookBackendSync *backend,
                                const gchar *query,
                                GSList **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.

Parameters

backend

an EBookBackendSync

 

query

a search query in S-expression format

 

out_uids

a GSList in which to deposit results.

[out][element-type utf8]

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure

Since: 3.34


e_book_backend_sync_contains_email ()

gboolean
e_book_backend_sync_contains_email (EBookBackendSync *backend,
                                    const gchar *email_address,
                                    GCancellable *cancellable,
                                    GError **error);

Checks whether contains an email_address . When the email_address contains multiple addresses, then returns TRUE when at least one address exists in the address book.

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

Parameters

backend

an EBookBackendSync

 

email_address

an email address

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

TRUE when found the email_address , FALSE on failure

Since: 3.44

Types and Values

struct EBookBackendSync

struct EBookBackendSync;

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


struct EBookBackendSyncClass

struct EBookBackendSyncClass {
	gboolean (*open_sync)		(EBookBackendSync *backend,
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*refresh_sync)		(EBookBackendSync *backend,
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*create_contacts_sync) (EBookBackendSync *backend,
						 const gchar * const *vcards,
						 guint32 opflags, /* bit-or of EBookOperationFlags */
						 GSList **out_contacts, /* EContact * */
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*modify_contacts_sync) (EBookBackendSync *backend,
						 const gchar * const *vcards,
						 guint32 opflags, /* bit-or of EBookOperationFlags */
						 GSList **out_contacts, /* EContact * */
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*remove_contacts_sync) (EBookBackendSync *backend,
						 const gchar * const *uids,
						 guint32 opflags, /* bit-or of EBookOperationFlags */
						 GSList **out_removed_uids, /* gchar * */
						 GCancellable *cancellable,
						 GError **error);
	EContact * (*get_contact_sync) (EBookBackendSync *backend,
						 const gchar *uid,
						 GCancellable *cancellable,
						 GError **error);
	gboolean (*get_contact_list_sync)
						(EBookBackendSync *backend,
						 const gchar *query,
						 GSList **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)
						(EBookBackendSync *backend,
						 const gchar *query,
						 GSList **out_uids,
						 GCancellable *cancellable,
						 GError **error);

	gboolean (*contains_email_sync) (EBookBackendSync *backend,
						 const gchar *email_address,
						 GCancellable *cancellable,
						 GError **error);

	/* Padding for future expansion */
	gpointer reserved_padding[19];
};

Class structure for the EBookBackendSync class.

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

Members

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)

 

contains_email_sync ()

   

gpointer reserved_padding[19];