## EDataBook

EDataBook

## Synopsis

    struct              EDataBook;
    #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);
    #define             e_return_data_book_error_if_fail    (expr,
                                                             _code)
    #define             e_return_data_book_error_val_if_fail(expr,
                                                             _code)
    EDataBook *         e_data_book_new                     (struct _EBookBackend *backend,
                                                             GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GError **error);
    struct _EBookBackend * e_data_book_get_backend          (EDataBook *book);
    GDBusConnection *   e_data_book_get_connection          (EDataBook *book);
    const gchar *       e_data_book_get_object_path         (EDataBook *book);
    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_get_backend_property
                                                            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const gchar *prop_value);
    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);
    EDataBook *         e_data_book_new_direct              (ESourceRegistry *registry,
                                                             ESource *source,
                                                             const gchar *backend_path,
                                                             const gchar *backend_name,
                                                             const gchar *config,
                                                             GError **error);
    gboolean            e_data_book_open_sync               (EDataBook *book,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_data_book_close                   (EDataBook *book,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_data_book_close_finish            (EDataBook *book,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            e_data_book_close_sync              (EDataBook *book,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_data_book_get_contact             (EDataBook *book,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_data_book_get_contact_finish      (EDataBook *book,
                                                             GAsyncResult *result,
                                                             EContact **contact,
                                                             GError **error);
    gboolean            e_data_book_get_contact_sync        (EDataBook *book,
                                                             const gchar *uid,
                                                             EContact **contact,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_data_book_get_contacts            (EDataBook *book,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_data_book_get_contacts_finish     (EDataBook *book,
                                                             GAsyncResult *result,
                                                             GSList **contacts,
                                                             GError **error);
    gboolean            e_data_book_get_contacts_sync       (EDataBook *book,
                                                             const gchar *sexp,
                                                             GSList **contacts,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_data_book_get_contacts_uids       (EDataBook *book,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            e_data_book_get_contacts_uids_finish
                                                            (EDataBook *book,
                                                             GAsyncResult *result,
                                                             GSList **contacts_uids,
                                                             GError **error);
    gboolean            e_data_book_get_contacts_uids_sync  (EDataBook *book,
                                                             const gchar *sexp,
                                                             GSList **contacts_uids,
                                                             GCancellable *cancellable,
                                                             GError **error);

    void                e_data_book_respond_set_backend_property
                                                            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error);
    void                e_data_book_report_opened           (EDataBook *book,
                                                             const GError *error);
    void                e_data_book_report_readonly         (EDataBook *book,
                                                             gboolean readonly);
    void                e_data_book_report_online           (EDataBook *book,
                                                             gboolean is_online);

## Object Hierarchy

      GObject
       +----EDataBook

## Implemented Interfaces

EDataBook implements GInitable.

## Properties

      "backend"                  EBookBackend*         : Read / Write / Construct Only
      "connection"               GDBusConnection*      : Read / Write / Construct Only
      "object-path"              gchar*                : Read / Write / Construct Only

## Description

## Details

### struct EDataBook

    struct EDataBook;

### 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_return_data_book_error_if_fail()

    #define             e_return_data_book_error_if_fail(expr, _code)

Since 2.32

### e_return_data_book_error_val_if_fail()

    #define             e_return_data_book_error_val_if_fail(expr, _code)

Same as `e_return_data_book_error_if_fail()`, only returns FALSE on a failure

Since 3.2

### 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_get_backend ()

    struct _EBookBackend * e_data_book_get_backend          (EDataBook *book);

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

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

### 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_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_get_backend_property ()

    void                e_data_book_respond_get_backend_property
                                                            (EDataBook *book,
                                                             guint32 opid,
                                                             GError *error,
                                                             const gchar *prop_value);

FIXME: Document me.

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

### e_data_book_new_direct ()

    EDataBook *         e_data_book_new_direct              (ESourceRegistry *registry,
                                                             ESource *source,
                                                             const gchar *backend_path,
                                                             const gchar *backend_name,
                                                             const gchar *config,
                                                             GError **error);

Creates an EDataBook for Direct Read Access, the `backend_path`, `backend_name` and `config` parameters are fetched from an EDataBookDirect reported over D-Bus from the server side counter part of a given backend.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`registry` : | The ESourceRegistry
`source` : | The ESource to create a book for
`backend_path` : | The full path to the backend module to use
`backend_name` : | The EDataFactory type name to use from the module specified by `backend_path`
`config` : | The backend specific configuration string specified by the EDataBookDirect
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | A newly created EDataBook for direct read access, otherwise `NULL` is returned and `error` is set. [transfer full]

Since 3.8

### e_data_book_open_sync ()

    gboolean            e_data_book_open_sync               (EDataBook *book,
                                                             GCancellable *cancellable,
                                                             GError **error);

Opens the EDataBook and it's backend.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success. If `FALSE` is returned, `error` will be set

Since 3.8

### e_data_book_close ()

    void                e_data_book_close                   (EDataBook *book,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Closes the `book` and its backend.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to `callback`. [closure]

Since 3.8

### e_data_book_close_finish ()

    gboolean            e_data_book_close_finish            (EDataBook *book,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes the operation started with `e_data_book_close()`. If an error occurs, then this function sets `error` and returns `FALSE`.

`book` : | an EDataBook
`result` : | a GAsyncResult
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success

Since 3.8

### e_data_book_close_sync ()

    gboolean            e_data_book_close_sync              (EDataBook *book,
                                                             GCancellable *cancellable,
                                                             GError **error);

Closes the `book` and its backend.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success. If `FALSE` is returned, `error` will be set

Since 3.8

### e_data_book_get_contact ()

    void                e_data_book_get_contact             (EDataBook *book,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieves EContact from the `book` for the gived `uid`. The call is finished by `e_data_book_get_contact_finish()` from the `callback`.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`uid` : | a unique string ID specifying the contact
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to `callback`. [closure]

Since 3.8

### e_data_book_get_contact_finish ()

    gboolean            e_data_book_get_contact_finish      (EDataBook *book,
                                                             GAsyncResult *result,
                                                             EContact **contact,
                                                             GError **error);

Finishes the operation started with `e_data_book_get_contact()`. If an error occurs, then this function sets `error` and returns `FALSE`.

`book` : | an EDataBook
`result` : | a GAsyncResult
`contact` : | return location for the fetched EContact
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success

Since 3.8

### e_data_book_get_contact_sync ()

    gboolean            e_data_book_get_contact_sync        (EDataBook *book,
                                                             const gchar *uid,
                                                             EContact **contact,
                                                             GCancellable *cancellable,
                                                             GError **error);

Retrieves an EContact from the `book` for the gived `uid`.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`uid` : | a unique string ID specifying the contact
`contact` : | return location for the fetched EContact
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success. If `FALSE` is returned, `error` will be set

Since 3.8

### e_data_book_get_contacts ()

    void                e_data_book_get_contacts            (EDataBook *book,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Query `book` with `sexp`, receiving a list of contacts which matched. The call is finished by `e_data_book_get_contacts_finish()` from the `callback`.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`sexp` : | an S-expression representing the query
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to `callback`. [closure]

Since 3.8

### e_data_book_get_contacts_finish ()

    gboolean            e_data_book_get_contacts_finish     (EDataBook *book,
                                                             GAsyncResult *result,
                                                             GSList **contacts,
                                                             GError **error);

Finishes the operation started with `e_data_book_get_contacts()`. If an error occurs, then this function sets `error` and returns `FALSE`.

`book` : | an EDataBook
`result` : | a GAsyncResult
`contacts` : | a GSList of matched EContacts. [element-type EContact][out]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success

Since 3.8

### e_data_book_get_contacts_sync ()

    gboolean            e_data_book_get_contacts_sync       (EDataBook *book,
                                                             const gchar *sexp,
                                                             GSList **contacts,
                                                             GCancellable *cancellable,
                                                             GError **error);

Query `book` with `sexp`, receiving a list of contacts which matched.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`sexp` : | an S-expression representing the query
`contacts` : | a GSList of matched EContacts. [element-type EContact][out]
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success. If `FALSE` is returned, `error` will be set

Since 3.8

### e_data_book_get_contacts_uids ()

    void                e_data_book_get_contacts_uids       (EDataBook *book,
                                                             const gchar *sexp,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Query `book` with `sexp`, receiving a list of contacts UIDs which matched. The call is finished by `e_data_book_get_contacts_uids_finish()` from the `callback`.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`sexp` : | an S-expression representing the query
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the request is satisfied. [scope async]
`user_data` : | data to pass to `callback`. [closure]

Since 3.8

### e_data_book_get_contacts_uids_finish ()

    gboolean            e_data_book_get_contacts_uids_finish
                                                            (EDataBook *book,
                                                             GAsyncResult *result,
                                                             GSList **contacts_uids,
                                                             GError **error);

Finishes the operation started with `e_data_book_get_contacts_uids()`. If an error occurs, then this function sets `error` and returns `FALSE`.

`book` : | an EDataBook
`result` : | a GAsyncResult
`contacts_uids` : | a GSList of matched contact UIDs stored as strings. [element-type utf8][out]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success

Since 3.8

### e_data_book_get_contacts_uids_sync ()

    gboolean            e_data_book_get_contacts_uids_sync  (EDataBook *book,
                                                             const gchar *sexp,
                                                             GSList **contacts_uids,
                                                             GCancellable *cancellable,
                                                             GError **error);

Query `book` with `sexp`, receiving a list of contacts UIDs which matched.

### Note

This API is intended for internal use only, if you want client side direct read access then use `e_book_client_connect_direct_sync()` instead

`book` : | an EDataBook
`sexp` : | an S-expression representing the query
`contacts_uids` : | a GSList of matched contact UIDs stored as strings. [element-type utf8][out]
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | `TRUE` on success. If `FALSE` is returned, `error` will be set

Since 3.8

### e_data_book_respond_set_backend_property ()

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

### Warning

`e_data_book_respond_set_backend_property` has been deprecated since version 3.8 and should not be used in newly-written code. This function no longer does anything.

FIXME: Document me.

Since 3.2

### e_data_book_report_opened ()

    void                e_data_book_report_opened           (EDataBook *book,
                                                             const GError *error);

### Warning

`e_data_book_report_opened` has been deprecated since version 3.8 and should not be used in newly-written code. This function no longer does anything.

Reports to associated client that opening phase of the book is finished. error being NULL means successfully, otherwise reports an error which happened during opening phase. By opening phase is meant a process including successfull authentication to the server/storage.

Since 3.2

### e_data_book_report_readonly ()

    void                e_data_book_report_readonly         (EDataBook *book,
                                                             gboolean readonly);

### Warning

`e_data_book_report_readonly` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_book_backend_set_writable()` instead.

FIXME: Document me.

Since 3.2

### e_data_book_report_online ()

    void                e_data_book_report_online           (EDataBook *book,
                                                             gboolean is_online);

### Warning

`e_data_book_report_online` has been deprecated since version 3.8 and should not be used in newly-written code. Use `e_backend_set_online()` instead.

FIXME: Document me.

Since 3.2

## Property Details

### The `"backend"` property

      "backend"                  EBookBackend*         : Read / Write / Construct Only

The backend driving this connection.

### The `"connection"` property

      "connection"               GDBusConnection*      : Read / Write / Construct Only

The GDBusConnection on which to export the address book interface.

### The `"object-path"` property

      "object-path"              gchar*                : Read / Write / Construct Only

The object path at which to export the address book interface.

Default value: NULL