## EDataBook

EDataBook — Server side D-Bus layer to communicate with addressbooks

## Synopsis

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

    struct              EDataBook;
    struct              EDataBookClass;
    GQuark              e_data_book_error_quark             (void);
    #define             E_DATA_BOOK_ERROR
    GError *            e_data_book_create_error            (EDataBookStatus status,
                                                             const gchar *custom_msg);
    GError *            e_data_book_create_error_fmt        (EDataBookStatus status,
                                                             const gchar *custom_msg_fmt,
                                                             ...);
    const gchar *       e_data_book_status_to_string        (EDataBookStatus status);
    EDataBook *         e_data_book_new                     (struct _EBookBackend *backend,
                                                             GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GError **error);
    struct _EBookBackend * e_data_book_ref_backend          (EDataBook *book);
    GDBusConnection *   e_data_book_get_connection          (EDataBook *book);
    const gchar *       e_data_book_get_object_path         (EDataBook *book);
    gboolean            e_data_book_set_locale              (EDataBook *book,
                                                             const gchar *locale,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_data_book_respond_open            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_book_respond_refresh         (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_book_respond_create_contacts (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *contacts);
    void                e_data_book_respond_remove_contacts (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *ids);
    void                e_data_book_respond_modify_contacts (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *contacts);
    void                e_data_book_respond_get_contact     (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const gchar *vcard);
    void                e_data_book_respond_get_contact_list
                                                            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *cards);
    void                e_data_book_respond_get_contact_list_uids
                                                            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *uids);
    void                e_data_book_report_error            (EDataBook *book,
                                                             const gchar *message);
    void                e_data_book_report_backend_property_changed
                                                            (EDataBook *book,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);
    gchar *             e_data_book_string_slist_to_comma_string
                                                            (const GSList *strings);

## Description

This class communicates with EBookClients over the bus and accesses an EBookBackend to satisfy client requests.

## Details

### struct EDataBook

    struct EDataBook {
    	GObject parent;
    	EDataBookPrivate *priv;
    };

### struct EDataBookClass

    struct EDataBookClass {
    	GObjectClass parent_class;
    };

### e_data_book_error_quark ()

    GQuark              e_data_book_error_quark             (void);

### E_DATA_BOOK_ERROR

    #define E_DATA_BOOK_ERROR e_data_book_error_quark ()

Since 2.30

### e_data_book_create_error ()

    GError *            e_data_book_create_error            (EDataBookStatus status,
                                                             const gchar *custom_msg);

`status` : | EDataBookStatus code
`custom_msg` : | Custom message to use for the error. When NULL, then uses a default message based on the `status` code.
Returns : | NULL, when the `status` is E_DATA_BOOK_STATUS_SUCCESS, or a newly allocated GError, which should be freed with `g_error_free()` call.

Since 2.32

### e_data_book_create_error_fmt ()

    GError *            e_data_book_create_error_fmt        (EDataBookStatus status,
                                                             const gchar *custom_msg_fmt,
                                                             ...);

Similar as `e_data_book_create_error()`, only here, instead of custom_msg, is used a `printf()` format to create a custom_msg for the error.

Since 2.32

### e_data_book_status_to_string ()

    const gchar *       e_data_book_status_to_string        (EDataBookStatus status);

Since 2.32

### e_data_book_new ()

    EDataBook *         e_data_book_new                     (struct _EBookBackend *backend,
                                                             GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GError **error);

Creates a new EDataBook and exports the AddressBook D-Bus interface on `connection` at `object_path`. The EDataBook handles incoming remote method invocations and forwards them to the `backend`. If the AddressBook interface fails to export, the function sets `error` and returns `NULL`.

`backend` : | an EBookBackend
`connection` : | a GDBusConnection
`object_path` : | object path for the D-Bus interface
`error` : | return location for a GError, or `NULL`
Returns : | an EDataBook, or `NULL` on error

### e_data_book_ref_backend ()

    struct _EBookBackend * e_data_book_ref_backend          (EDataBook *book);

Returns the EBookBackend to which incoming remote method invocations are being forwarded.

The returned EBookBackend is referenced for thread-safety and should be unreferenced with `g_object_unref()` when finished with it.

`book` : | an EDataBook
Returns : | an EBookBackend

Since 3.10

### e_data_book_get_connection ()

    GDBusConnection *   e_data_book_get_connection          (EDataBook *book);

Returns the GDBusConnection on which the AddressBook D-Bus interface is exported.

`book` : | an EDataBook
Returns : | the GDBusConnection

Since 3.8

### e_data_book_get_object_path ()

    const gchar *       e_data_book_get_object_path         (EDataBook *book);

Returns the object path at which the AddressBook D-Bus interface is exported.

`book` : | an EDataBook
Returns : | the object path

Since 3.8

### e_data_book_set_locale ()

    gboolean            e_data_book_set_locale              (EDataBook *book,
                                                             const gchar *locale,
                                                             GCancellable *cancellable,
                                                             GError **error);

Set's the locale for this addressbook, this can result in renormalization of locale sensitive data.

`book` : | an EDataBook
`locale` : | the new locale to set for this book
`cancellable` : | a GCancellable. [allow-none]
`error` : | a location to store any error which might occur. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_data_book_respond_open ()

    void                e_data_book_respond_open            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error);

### e_data_book_respond_refresh ()

    void                e_data_book_respond_refresh         (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error);

Notifies listeners of the completion of the refresh method call.

`book` : | An addressbook client interface.
`error` : | Operation error, if any, automatically freed if passed it.

Since 3.2

### e_data_book_respond_create_contacts ()

    void                e_data_book_respond_create_contacts (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *contacts);

FIXME: Document me!

Since 3.4

### e_data_book_respond_remove_contacts ()

    void                e_data_book_respond_remove_contacts (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *ids);

### e_data_book_respond_modify_contacts ()

    void                e_data_book_respond_modify_contacts (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *contacts);

FIXME: Document me!

Since 3.4

### e_data_book_respond_get_contact ()

    void                e_data_book_respond_get_contact     (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const gchar *vcard);

### e_data_book_respond_get_contact_list ()

    void                e_data_book_respond_get_contact_list
                                                            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *cards);

### e_data_book_respond_get_contact_list_uids ()

    void                e_data_book_respond_get_contact_list_uids
                                                            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const GSList *uids);

FIXME: Document me.

Since 3.2

### e_data_book_report_error ()

    void                e_data_book_report_error            (EDataBook *book,
                                                             const gchar *message);

FIXME: Document me.

Since 3.2

### e_data_book_report_backend_property_changed ()

    void                e_data_book_report_backend_property_changed
                                                            (EDataBook *book,
                                                             const gchar *prop_name,
                                                             const gchar *prop_value);

FIXME: Document me.

Since 3.2

### e_data_book_string_slist_to_comma_string ()

    gchar *             e_data_book_string_slist_to_comma_string
                                                            (const GSList *strings);

Takes a list of strings and converts it to a comma-separated string of values; free returned pointer with `g_free()`

Since 3.2