e-book-contacts-utils: Evolution-Data-Server Reference Manual

## e-book-contacts-utils e-book-contacts-utils |

## Functions

GQuark | e_book_client_error_quark ()
const gchar * | e_book_client_error_to_string ()
GError * | e_book_client_error_create ()
GError * | e_book_client_error_create_fmt ()
EConflictResolution | e_book_util_operation_flags_to_conflict_resolution ()
void | e_book_util_foreach_address ()
void | e_book_util_diff_categories ()

## Types and Values

#define | E_BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS
#define | E_BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS
#define | E_BOOK_BACKEND_PROPERTY_REVISION
#define | E_BOOK_BACKEND_PROPERTY_CATEGORIES
#define | E_BOOK_CLIENT_ERROR
enum | EBookClientError
enum | EBookViewStatus
enum | EBookChangeType
| EBookChange

## Description

## Functions

### e_book_client_error_quark ()

    GQuark
    e_book_client_error_quark (void);

### e_book_client_error_to_string ()

    const gchar *
    e_book_client_error_to_string (EBookClientError code);

Get localized human readable description of the given error code.

#### Parameters

code | an EBookClientError code |

#### Returns

Localized human readable description of the given error code

Since: 3.2

### e_book_client_error_create ()

    GError *
    e_book_client_error_create (EBookClientError code,
                                const gchar *custom_msg);

#### Parameters

code | an EBookClientError code to create |
custom_msg | custom message to use for the error; can be `NULL`. | [nullable]

#### Returns

a new GError containing an E_BOOK_CLIENT_ERROR of the given `code` . If the `custom_msg` is NULL, then the error message is the one returned from `e_book_client_error_to_string()` for the `code` , otherwise the given message is used.

Returned pointer should be freed with `g_error_free()`.

Since: 3.2

### e_book_client_error_create_fmt ()

    GError *
    e_book_client_error_create_fmt (EBookClientError code,
                                    const gchar *format,
                                    ...);

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

#### Parameters

code | an EBookClientError |
format | message format, or `NULL` to use the default message for the `code` . | [nullable]
... | arguments for the format |

#### Returns

a newly allocated GError, which should be freed with `g_error_free()`, when no longer needed. The GError has set the custom message, or the default message for `code` , when `format` is `NULL`.

[transfer full]

Since: 3.34

### e_book_util_operation_flags_to_conflict_resolution ()

    EConflictResolution
    e_book_util_operation_flags_to_conflict_resolution
                                   (guint32 flags);

Decodes the EConflictResolution from the bit-or of EBookOperationFlags.

#### Parameters

flags | bit-or of EBookOperationFlags |

#### Returns

an EConflictResolution as stored in the `flags`

Since: 3.34

### e_book_util_foreach_address ()

    void
    e_book_util_foreach_address (const gchar *email_address,
                                 GHRFunc func,
                                 gpointer user_data);

Parses the `email_address` and calls `func` for each found address. The first parameter of the `func` is the name, the second parameter of the `func` is the email, the third parameters of the `func` is the `user_data` . The `func` returns `TRUE`, to continue processing.

#### Parameters

email_address | one or more email addresses as string |
func | a function to call for each email. | [scope call]
user_data (closure func) | user data passed to `func` |

Since: 3.44

### e_book_util_diff_categories ()

    void
    e_book_util_diff_categories (EContact *old_contact,
                                 EContact *new_contact,
                                 GHashTable **out_added,
                                 GHashTable **out_removed);

Compares list of categories on the `old_contact` with the list of categories on the `new_contact` and fills `out_added` categories and `out_removed` categories accordingly, as if the `old_contact` is replaced with the `new_contact` . When either of the contacts is `NULL`, it's considered as having no categories set. Rather than returning empty GHashTable, the return argument is set to `NULL` when there are no added/removed categories.

The key of the hash table is the category string, the value is an integer (1). There is used the hash table only for speed.

The returned GHashTable-s should be freed with `g_hash_table_unref()`, when no longer needed.

#### Parameters

old_contact | an old EContact, or `NULL`. | [nullable]
new_contact | a new EContact, or `NULL`. | [nullable]
out_added | a GHashTable with added categories. | [out][transfer container][element-type utf8 int]
out_removed | a GHashTable with removed categories. | [out][transfer container][element-type utf8 int]

Since: 3.48

## Types and Values

### E_BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS

    #define E_BOOK_BACKEND_PROPERTY_REQUIRED_FIELDS		"required-fields"

Provides comma-separated list of required fields by the book backend. All of these attributes should be set, otherwise the backend will reject saving the contact.

The `e_contact_field_id()` can be used to transform the field name into an EContactField.

Since: 3.2

### E_BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS

    #define E_BOOK_BACKEND_PROPERTY_SUPPORTED_FIELDS "supported-fields"

Provides comma-separated list of supported fields by the book backend. Attributes other than those listed here can be discarded. This can be used to enable/show only supported elements in GUI.

The `e_contact_field_id()` can be used to transform the field name into an EContactField.

Since: 3.2

### E_BOOK_BACKEND_PROPERTY_REVISION

    #define E_BOOK_BACKEND_PROPERTY_REVISION		"revision"

The current overall revision string, this can be used as a quick check to see if data has changed at all since the last time the addressbook revision was observed.

Since: 3.4

### E_BOOK_BACKEND_PROPERTY_CATEGORIES

    #define E_BOOK_BACKEND_PROPERTY_CATEGORIES		"categories"

Provides comma-separated list of all known categories used by the contacts stored in the book backend.

Since: 3.48

### E_BOOK_CLIENT_ERROR

    #define E_BOOK_CLIENT_ERROR e_book_client_error_quark ()

Error domain for EBookClient errors

Since: 3.2

### enum EBookClientError

Error codes returned by EBookClient APIs, if an EClientError was not available.

#### Members

E_BOOK_CLIENT_ERROR_NO_SUCH_BOOK | Requested book did not exist |
E_BOOK_CLIENT_ERROR_CONTACT_NOT_FOUND | Contact referred to was not found |
E_BOOK_CLIENT_ERROR_CONTACT_ID_ALREADY_EXISTS | Tried to add a contact which already exists |
E_BOOK_CLIENT_ERROR_NO_SUCH_SOURCE | Referred ESource does not exist |
E_BOOK_CLIENT_ERROR_NO_SPACE | Out of disk space |

Since: 3.2

### enum EBookViewStatus

`EBookViewStatus` has been deprecated since version 3.2 and should not be used in newly-written code.

Use EBookClientView instead.

Status messages used in notifications in the deprecated EBookView class

#### Members

E_BOOK_VIEW_STATUS_OK | Ok |
E_BOOK_VIEW_STATUS_TIME_LIMIT_EXCEEDED | Time limit exceeded |
E_BOOK_VIEW_STATUS_SIZE_LIMIT_EXCEEDED | Size limit exceeded |
E_BOOK_VIEW_ERROR_INVALID_QUERY | Invalid search expression |
E_BOOK_VIEW_ERROR_QUERY_REFUSED | Search expression refused |
E_BOOK_VIEW_ERROR_OTHER_ERROR | Another error occurred |

### enum EBookChangeType

`EBookChangeType` has been deprecated since version 3.2 and should not be used in newly-written code.

The type of change in an EBookChange

#### Members

E_BOOK_CHANGE_CARD_ADDED | A vCard was added |
E_BOOK_CHANGE_CARD_DELETED | A vCard was deleted |
E_BOOK_CHANGE_CARD_MODIFIED | A vCard was modified |

### EBookChange

    typedef struct {
    	EBookChangeType  change_type;
    	EContact        *contact;
    } EBookChange;

`EBookChange` has been deprecated since version 3.2 and should not be used in newly-written code.

This is a part of the deprecated EBook API.

#### Members

EBookChangeType `change_type`; | The EBookChangeType |
EContact *`contact`; | The EContact which changed |