## Addressbook related types

Addressbook related types

## Synopsis

    #define             E_BOOK_CLIENT_ERROR
    enum                EBookClientViewFlags;
    enum                EBookClientError;
    enum                EDataBookStatus;
    enum                EBookViewStatus;
    enum                EBookChangeType;
                        EBookChange;
    enum                EBookIndexType;
    enum                EBookCursorSortType;
    enum                EBookCursorOrigin;
    enum                EBookCursorStepFlags;
    GQuark              e_book_client_error_quark           (void);
    const gchar *       e_book_client_error_to_string       (EBookClientError code);
    GError *            e_book_client_error_create          (EBookClientError code,
                                                             const gchar *custom_msg);

## Description

## Details

### E_BOOK_CLIENT_ERROR

    #define E_BOOK_CLIENT_ERROR e_book_client_error_quark ()

Error domain for EBookClient errors

Since 3.2

### enum EBookClientViewFlags

    typedef enum {
    	E_BOOK_CLIENT_VIEW_FLAGS_NONE = 0,
    	E_BOOK_CLIENT_VIEW_FLAGS_NOTIFY_INITIAL = (1 << 0),
    } EBookClientViewFlags;

Flags that control the behaviour of an EBookClientView.

`E_BOOK_CLIENT_VIEW_FLAGS_NONE` | Symbolic value for no flags
`E_BOOK_CLIENT_VIEW_FLAGS_NOTIFY_INITIAL` | If this flag is set then all contacts matching the view's query will be sent as notifications when starting the view, otherwise only future changes will be reported. The default for a EBookClientView is `TRUE`.

Since 3.4

### enum EBookClientError

    typedef enum {
    	E_BOOK_CLIENT_ERROR_NO_SUCH_BOOK,
    	E_BOOK_CLIENT_ERROR_CONTACT_NOT_FOUND,
    	E_BOOK_CLIENT_ERROR_CONTACT_ID_ALREADY_EXISTS,
    	E_BOOK_CLIENT_ERROR_NO_SUCH_SOURCE,
    	E_BOOK_CLIENT_ERROR_NO_SPACE
    } EBookClientError;

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

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

    typedef enum {
    	E_DATA_BOOK_STATUS_SUCCESS,
    	E_DATA_BOOK_STATUS_BUSY,
    	E_DATA_BOOK_STATUS_REPOSITORY_OFFLINE,
    	E_DATA_BOOK_STATUS_PERMISSION_DENIED,
    	E_DATA_BOOK_STATUS_CONTACT_NOT_FOUND,
    	E_DATA_BOOK_STATUS_CONTACTID_ALREADY_EXISTS,
    	E_DATA_BOOK_STATUS_AUTHENTICATION_FAILED,
    	E_DATA_BOOK_STATUS_AUTHENTICATION_REQUIRED,
    	E_DATA_BOOK_STATUS_UNSUPPORTED_FIELD,
    	E_DATA_BOOK_STATUS_UNSUPPORTED_AUTHENTICATION_METHOD,
    	E_DATA_BOOK_STATUS_TLS_NOT_AVAILABLE,
    	E_DATA_BOOK_STATUS_NO_SUCH_BOOK,
    	E_DATA_BOOK_STATUS_BOOK_REMOVED,
    	E_DATA_BOOK_STATUS_OFFLINE_UNAVAILABLE,
    	E_DATA_BOOK_STATUS_SEARCH_SIZE_LIMIT_EXCEEDED,
    	E_DATA_BOOK_STATUS_SEARCH_TIME_LIMIT_EXCEEDED,
    	E_DATA_BOOK_STATUS_INVALID_QUERY,
    	E_DATA_BOOK_STATUS_QUERY_REFUSED,
    	E_DATA_BOOK_STATUS_COULD_NOT_CANCEL,
    	E_DATA_BOOK_STATUS_OTHER_ERROR,
    	E_DATA_BOOK_STATUS_INVALID_SERVER_VERSION,
    	E_DATA_BOOK_STATUS_NO_SPACE,
    	E_DATA_BOOK_STATUS_INVALID_ARG,
    	E_DATA_BOOK_STATUS_NOT_SUPPORTED,
    	E_DATA_BOOK_STATUS_NOT_OPENED,
    	E_DATA_BOOK_STATUS_OUT_OF_SYNC
    } EDataBookStatus;

Error codes for the E_DATA_BOOK_ERROR domain, these are used in the backend.

`E_DATA_BOOK_STATUS_SUCCESS` | No error
`E_DATA_BOOK_STATUS_BUSY` | Backend was busy
`E_DATA_BOOK_STATUS_REPOSITORY_OFFLINE` | Offsite repository was not online
`E_DATA_BOOK_STATUS_PERMISSION_DENIED` | Permission denied
`E_DATA_BOOK_STATUS_CONTACT_NOT_FOUND` | Contact referred to was not found
`E_DATA_BOOK_STATUS_CONTACTID_ALREADY_EXISTS` | Tried to add a contact which already exists
`E_DATA_BOOK_STATUS_AUTHENTICATION_FAILED` | Authentication failure
`E_DATA_BOOK_STATUS_AUTHENTICATION_REQUIRED` | Authentication required for this operation
`E_DATA_BOOK_STATUS_UNSUPPORTED_FIELD` | An unsupported EContactField was specified for a given operation
`E_DATA_BOOK_STATUS_UNSUPPORTED_AUTHENTICATION_METHOD` | The authentication method is unsupported
`E_DATA_BOOK_STATUS_TLS_NOT_AVAILABLE` | TLS was not available
`E_DATA_BOOK_STATUS_NO_SUCH_BOOK` | Book did not exist
`E_DATA_BOOK_STATUS_BOOK_REMOVED` | Book was removed
`E_DATA_BOOK_STATUS_OFFLINE_UNAVAILABLE` | XXX Document me
`E_DATA_BOOK_STATUS_SEARCH_SIZE_LIMIT_EXCEEDED` | Exceeded limit of seach size
`E_DATA_BOOK_STATUS_SEARCH_TIME_LIMIT_EXCEEDED` | Exceeded time limit for seach
`E_DATA_BOOK_STATUS_INVALID_QUERY` | Given search espression is invalid
`E_DATA_BOOK_STATUS_QUERY_REFUSED` | Given search espression was refused
`E_DATA_BOOK_STATUS_COULD_NOT_CANCEL` | Unable to cancel an operation
`E_DATA_BOOK_STATUS_OTHER_ERROR` | An other error occurred
`E_DATA_BOOK_STATUS_INVALID_SERVER_VERSION` | Invalid server version
`E_DATA_BOOK_STATUS_NO_SPACE` | Disk space insufficient
`E_DATA_BOOK_STATUS_INVALID_ARG` | Invalid argument
`E_DATA_BOOK_STATUS_NOT_SUPPORTED` | Unsupported operation
`E_DATA_BOOK_STATUS_NOT_OPENED` | Tried to access a book which is not yet open
`E_DATA_BOOK_STATUS_OUT_OF_SYNC` | Out of sync state

Since 3.6

### enum EBookViewStatus

    typedef enum {
    	E_BOOK_VIEW_STATUS_OK,
    	E_BOOK_VIEW_STATUS_TIME_LIMIT_EXCEEDED,
    	E_BOOK_VIEW_STATUS_SIZE_LIMIT_EXCEEDED,
    	E_BOOK_VIEW_ERROR_INVALID_QUERY,
    	E_BOOK_VIEW_ERROR_QUERY_REFUSED,
    	E_BOOK_VIEW_ERROR_OTHER_ERROR
    } EBookViewStatus;

### Warning

`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

`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

    typedef enum {
    	E_BOOK_CHANGE_CARD_ADDED,
    	E_BOOK_CHANGE_CARD_DELETED,
    	E_BOOK_CHANGE_CARD_MODIFIED
    } EBookChangeType;

### Warning

`EBookChangeType` is deprecated and should not be used in newly-written code. 3.2

The type of change in an EBookChange

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

### Warning

`EBookChange` is deprecated and should not be used in newly-written code. 3.2

This is a part of the deprecated EBook API.

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

### enum EBookIndexType

    typedef enum {
    	E_BOOK_INDEX_PREFIX = 0,
    	E_BOOK_INDEX_SUFFIX,
    	E_BOOK_INDEX_PHONE,
    	E_BOOK_INDEX_SORT_KEY
    } EBookIndexType;

The type of index defined by `e_source_backend_summary_setup_set_indexed_fields()`

`E_BOOK_INDEX_PREFIX` | An index suitable for searching contacts with a prefix pattern
`E_BOOK_INDEX_SUFFIX` | An index suitable for searching contacts with a suffix pattern

`E_BOOK_INDEX_PHONE`

An index suitable for searching contacts for phone numbers.

### Note

Phone numbers must be convertible into FQTN according to E.164 to be stored in this index. The number "+9999999" for instance won't be stored because the country calling code "+999" currently is not assigned.

`E_BOOK_INDEX_SORT_KEY` | Indicates that a given EContactField should be usable as a sort key.

### enum EBookCursorSortType

    typedef enum {
    	E_BOOK_CURSOR_SORT_ASCENDING = 0,
    	E_BOOK_CURSOR_SORT_DESCENDING
    } EBookCursorSortType;

Specifies the sort order of an ordered query

`E_BOOK_CURSOR_SORT_ASCENDING` | Sort results in ascending order
`E_BOOK_CURSOR_SORT_DESCENDING` | Sort results in descending order

Since 3.12

### enum EBookCursorOrigin

    typedef enum {
    	E_BOOK_CURSOR_ORIGIN_CURRENT,
    	E_BOOK_CURSOR_ORIGIN_BEGIN,
    	E_BOOK_CURSOR_ORIGIN_END
    } EBookCursorOrigin;

Specifies the start position to in the list of traversed contacts in calls to `e_book_client_cursor_step()`.

When an EBookClientCursor is created, the current position implied by `E_BOOK_CURSOR_ORIGIN_CURRENT` is the same as `E_BOOK_CURSOR_ORIGIN_BEGIN`.

`E_BOOK_CURSOR_ORIGIN_CURRENT` | The current cursor position
`E_BOOK_CURSOR_ORIGIN_BEGIN` | The beginning of the cursor results.
`E_BOOK_CURSOR_ORIGIN_END` | The ending of the cursor results.

Since 3.12

### enum EBookCursorStepFlags

    typedef enum {
    	E_BOOK_CURSOR_STEP_MOVE = (1 << 0),
    	E_BOOK_CURSOR_STEP_FETCH = (1 << 1)
    } EBookCursorStepFlags;

Defines the behaviour of `e_book_client_cursor_step()`.

`E_BOOK_CURSOR_STEP_MOVE` | The cursor position should be modified while stepping
`E_BOOK_CURSOR_STEP_FETCH` | Traversed contacts should be listed and returned while stepping.

Since 3.12

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

FIXME: Document me.

`code` : | an EBookClientError code

Since 3.2

### e_book_client_error_create ()

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

### Warning

`e_book_client_error_create` has been deprecated since version 3.8 and should not be used in newly-written code. Just use the GError API directly.

`code` : | an EBookClientError code to create
`custom_msg` : | custom message to use for the error; can be `NULL`
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