EDataBook: Evolution-Data-Server Reference Manual

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

## Functions

GQuark | e_data_book_error_quark ()
GError * | e_data_book_create_error ()
GError * | e_data_book_create_error_fmt ()
const gchar * | e_data_book_status_to_string ()
EDataBook * | e_data_book_new ()
struct _EBookBackend * | e_data_book_ref_backend ()
GDBusConnection * | e_data_book_get_connection ()
const gchar * | e_data_book_get_object_path ()
gboolean | e_data_book_set_locale ()
void | e_data_book_respond_open ()
void | e_data_book_respond_refresh ()
void | e_data_book_respond_create_contacts ()
void | e_data_book_respond_remove_contacts ()
void | e_data_book_respond_modify_contacts ()
void | e_data_book_respond_get_contact ()
void | e_data_book_respond_get_contact_list ()
void | e_data_book_respond_get_contact_list_uids ()
void | e_data_book_report_error ()
void | e_data_book_report_backend_property_changed ()
gchar * | e_data_book_string_slist_to_comma_string ()

## Types and Values

#define | E_DATA_BOOK_ERROR

## Includes

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

## Description

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

## Functions

### e_data_book_error_quark ()

    GQuark
    e_data_book_error_quark (void);

### e_data_book_create_error ()

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

#### Parameters

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.

#### Parameters

status | an EDataBookStatus |
custom_msg_fmt | Custom message to use for the error. When NULL, then uses a default message based on the `status` code. |
... | arguments for the `custom_msg_fmt` |

#### Returns

a new GError populated with the values from the parameters.

[transfer full]

Since: 2.32

### e_data_book_status_to_string ()

    const gchar *
    e_data_book_status_to_string (EDataBookStatus status);

Get localized human readable description of the given status code.

#### Parameters

status | an EDataBookStatus |

#### Returns

Localized human readable description of the given status code

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`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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);

Notifies listeners of the completion of the open method call.

#### Parameters

book | An EDataBook |
opid | An operation ID |
error | Operation error, if any, automatically freed if passed it |

### 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.

#### Parameters

book | An EDataBook |
opid | An operation ID |
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);

Finishes a call to create a list contacts.

#### Parameters

book | An EDataBook |
opid | An operation ID |
error | Operation error, if any, automatically freed if passed it |
contacts | A list of created EContact(s), or `NULL` on error. | [allow-none][element-type EContact]

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);

Finishes a call to remove a list of contacts.

#### Parameters

book | An EDataBook |
opid | An operation ID |
error | Operation error, if any, automatically freed if passed it |
ids | A list of removed contact UID-s, or `NULL` on error. | [allow-none][element-type gchar *]

Since: 3.4

### e_data_book_respond_modify_contacts ()

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

Finishes a call to modify a list of contacts.

#### Parameters

book | An EDataBook |
opid | An operation ID |
error | Operation error, if any, automatically freed if passed it |
contacts | A list of modified EContact(s), or `NULL` on error. | [allow-none][element-type EContact]

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);

Notifies listeners of the completion of the get_contact method call. Only one of `error` and `vcard` can be set.

#### Parameters

book | An EDataBook |
opid | An operation ID |
error | Operation error, if any, automatically freed if passed it. | [nullable][transfer full]
vcard | the found vCard, as string, or `NULL`, if it could not be found. | [nullable]

### e_data_book_respond_get_contact_list ()

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

Finishes a call to get list of vCards which satisfy certain criteria.

#### Parameters

book | An EDataBook |
opid | An operation ID |
error | Operation error, if any, automatically freed if passed it |
cards | A list of vCard strings, or `NULL` on error. | [allow-none][element-type gchar *]

Since: 3.2

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

Finishes a call to get list of UIDs which satisfy certain criteria.

#### Parameters

book | An EDataBook |
opid | An operation ID |
error | Operation error, if any, automatically freed if passed it |
uids | A list of picked UIDs, or `NULL` on error. | [allow-none][element-type gchar *]

Since: 3.2

### e_data_book_report_error ()

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

Notifies the clients about an error, which happened out of any client-initiate operation.

#### Parameters

book | An EDataBook |
message | An error message |

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);

Notifies the clients about a property change.

#### Parameters

book | An EDataBook |
prop_name | Property name which changed |
prop_value | The new property value |

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()`

#### Parameters

strings | a list of gchar *. | [element-type gchar *]

#### Returns

comma-separated newly allocated text of `strings` .

[transfer full]

Since: 3.2

## Types and Values

### E_DATA_BOOK_ERROR

    #define E_DATA_BOOK_ERROR e_data_book_error_quark ()

Since: 2.30