EBookBackendSync: Evolution-Data-Server Reference Manual

## EBookBackendSync EBookBackendSync — An abstract class for implementing synchronous addressbook backends |

## Functions

gboolean | e_book_backend_sync_open ()
gboolean | e_book_backend_sync_refresh ()
gboolean | e_book_backend_sync_create_contacts ()
gboolean | e_book_backend_sync_modify_contacts ()
gboolean | e_book_backend_sync_remove_contacts ()
EContact * | e_book_backend_sync_get_contact ()
gboolean | e_book_backend_sync_get_contact_list ()
gboolean | e_book_backend_sync_get_contact_list_uids ()
gboolean | e_book_backend_sync_contains_email ()

## Types and Values

struct | EBookBackendSync
struct | EBookBackendSyncClass

## 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]; |  |