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 ()
EBookIndices * | e_book_indices_copy ()
void | e_book_indices_free ()
EBookClientViewSortFields * | e_book_client_view_sort_fields_copy ()
void | e_book_client_view_sort_fields_free ()

## 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_BACKEND_PROPERTY_PREFER_VCARD_VERSION
#define | E_BOOK_CLIENT_ERROR
enum | EBookClientError
enum | EBookViewStatus
enum | EBookChangeType
| EBookChange

## Object Hierarchy

        GBoxed
        ├── EBookClientViewSortFields
        ╰── EBookIndices

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

### e_book_indices_copy ()

    EBookIndices *
    e_book_indices_copy (const EBookIndices *src);

Creates a copy of the `src` . If the `src` is `NULL`, the `NULL` is returned. Both the `src` and the returned array is terminated by an item, which has the chr member set to `NULL`.

Free the returned array with `e_book_indices_free()`, when no longer needed.

[skip]

#### Parameters

src | an array of EBookIndices to copy, or `NULL`. | [nullable]

#### Returns

copy of the `src` .

[transfer full]

Since: 3.50

### e_book_indices_free ()

    void
    e_book_indices_free (EBookIndices *indices);

Frees the `indices` array with each member. The array should be terminated by an item with chr member set to `NULL`.

[skip]

#### Parameters

indices | an array of EBookIndices to free. | [nullable]

### e_book_client_view_sort_fields_copy ()

    EBookClientViewSortFields *
    e_book_client_view_sort_fields_copy (const EBookClientViewSortFields *src);

Creates a copy of the `src` . If the `src` is `NULL`, the `NULL` is returned. Both the `src` and the returned array is terminated by an item, which has the field member set to `E_CONTACT_FIELD_LAST`.

Free the returned array with `e_book_client_view_sort_fields_free()`, when no longer needed.

[skip]

#### Parameters

src | an array to copy, or `NULL`. | [nullable]

#### Returns

copy of the `src` .

[transfer full]

Since: 3.50

### e_book_client_view_sort_fields_free ()

    void
    e_book_client_view_sort_fields_free (EBookClientViewSortFields *fields);

Frees the `fields` array with each member. The array should be terminated by an item with field member set to `E_CONTACT_FIELD_LAST`.

[skip]

#### Parameters

fields | an array of EBookClientViewSortFields to free. | [nullable]

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

    #define E_BOOK_BACKEND_PROPERTY_PREFER_VCARD_VERSION "prefer-vcard-version"

A book backend string property name containing a vCard version the backend prefers. Common values are "3.0" and "4.0". It is only what the backend prefers for the exchange, it can receive other vCard versions too, the same as it can return vCard data in a different version (like when the server has stored vCards in multiple versions, then they are not converted by the backend.

Since: 3.60

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