EBookCache: Evolution-Data-Server Reference Manual

## EBookCache EBookCache — An ECache descendant for addressbooks |

## Functions

EBookCacheSearchData * | e_book_cache_search_data_new ()
EBookCacheSearchData * | e_book_cache_search_data_copy ()
void | e_book_cache_search_data_free ()
gboolean | (*EBookCacheSearchFunc) ()
EBookCache * | e_book_cache_new ()
EBookCache * | e_book_cache_new_full ()
ESource * | e_book_cache_ref_source ()
gchar * | e_book_cache_dup_contact_revision ()
gboolean | e_book_cache_set_locale ()
gchar * | e_book_cache_dup_locale ()
ECollator * | e_book_cache_ref_collator ()
gchar * | e_book_cache_dup_categories ()
gboolean | e_book_cache_put_contact ()
gboolean | e_book_cache_put_contacts ()
gboolean | e_book_cache_remove_contact ()
gboolean | e_book_cache_remove_contacts ()
gboolean | e_book_cache_get_contact ()
gboolean | e_book_cache_get_vcard ()
gboolean | e_book_cache_set_contact_custom_flags ()
gboolean | e_book_cache_get_contact_custom_flags ()
gboolean | e_book_cache_set_contact_extra ()
gboolean | e_book_cache_get_contact_extra ()
gboolean | e_book_cache_get_uids_with_extra ()
gboolean | e_book_cache_search ()
gboolean | e_book_cache_search_uids ()
gboolean | e_book_cache_search_with_callback ()
gboolean | e_book_cache_contains_email ()
EBookCacheCursor * | e_book_cache_cursor_new ()
void | e_book_cache_cursor_free ()
gint | e_book_cache_cursor_step ()
void | e_book_cache_cursor_set_target_alphabetic_index ()
gboolean | e_book_cache_cursor_set_sexp ()
gboolean | e_book_cache_cursor_calculate ()
gint | e_book_cache_cursor_compare_contact ()
gboolean | e_book_cache_count_query ()
gboolean | e_book_cache_dup_query_field ()
gboolean | e_book_cache_dup_query_contacts ()
gboolean | e_book_cache_dup_summary_field ()

## Properties

char * | locale | Read

## Signals

void | categories-changed | Action
char* | dup-contact-revision | Action
void | e164-changed | Run Last

## Types and Values

| EBookCacheSearchData
struct | EBookCache
struct | EBookCacheClass
enum | EBookCacheCursorOrigin
enum | EBookCacheCursorStepFlags
| EBookCacheCursor

## Object Hierarchy

        GBoxed
        ├── EBookCacheCursor
        ╰── EBookCacheSearchData
        GObject
        ╰── ECache
            ╰── EBookCache

## Implemented Interfaces

EBookCache implements

## Includes

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

## Description

The EBookCache is an API for storing and looking up EContact(s) in an ECache. It also supports cursors.

The API is thread safe, in the similar way as the ECache is.

Any operations which can take a lot of time to complete (depending on the size of your addressbook) can be cancelled using a GCancellable.

Depending on your summary configuration, your mileage will vary. Refer to the ESourceBackendSummarySetup for configuring your addressbook for the type of usage you mean to make of it.

## Functions

### e_book_cache_search_data_new ()

    EBookCacheSearchData *
    e_book_cache_search_data_new (const gchar *uid,
                                  const gchar *vcard,
                                  const gchar *extra);

Creates a new EBookCacheSearchData prefilled with the given values.

#### Parameters

uid | a contact UID; cannot be `NULL` |
vcard | the contact as a vCard string; cannot be `NULL` |
extra | any extra data stored with the contact, or `NULL`. | [nullable]

#### Returns

A new EBookCacheSearchData. Free it with `e_book_cache_search_data_free()` when no longer needed.

[transfer full]

Since: 3.26

### e_book_cache_search_data_copy ()

    EBookCacheSearchData *
    e_book_cache_search_data_copy (const EBookCacheSearchData *data);

#### Parameters

data | a source EBookCacheSearchData to copy, or `NULL`. | [nullable]

#### Returns

Copy of the given `data` . Free it with `e_book_cache_search_data_free()` when no longer needed. If the `data` is `NULL`, then returns `NULL` as well.

[transfer full][nullable]

Since: 3.26

### e_book_cache_search_data_free ()

    void
    e_book_cache_search_data_free (gpointer data);

Frees the `data` structure, previously allocated with `e_book_cache_search_data_new()` or `e_book_cache_search_data_copy()`.

#### Parameters

data | an EBookCacheSearchData. | [nullable]

Since: 3.26

### EBookCacheSearchFunc ()

    gboolean
    (*EBookCacheSearchFunc) (EBookCache *book_cache,
                             const gchar *uid,
                             const gchar *revision,
                             const gchar *object,
                             const gchar *extra,
                             guint32 custom_flags,
                             EOfflineState offline_state,
                             gpointer user_data);

A callback called for each object row when using `e_book_cache_search_with_callback()` function.

#### Parameters

book_cache | an EBookCache |
uid | a unique object identifier |
revision | the object revision |
object | the object itself |
extra | extra data stored with the object |
custom_flags | object's custom flags |
offline_state | object's offline state, one of EOfflineState |
user_data | user data, as used in `e_book_cache_search_with_callback()` |

#### Returns

`TRUE` to continue, `FALSE` to stop walk through.

Since: 3.26

### e_book_cache_new ()

    EBookCache *
    e_book_cache_new (const gchar *filename,
                      ESource *source,
                      GCancellable *cancellable,
                      GError **error);

Creates a new EBookCache with the default summary configuration.

Aside from the mandatory fields `E_CONTACT_UID`, `E_CONTACT_REV`, the default configuration stores the following fields for quick performance of searches: `E_CONTACT_FILE_AS`, `E_CONTACT_NICKNAME`, `E_CONTACT_FULL_NAME`, `E_CONTACT_GIVEN_NAME`, `E_CONTACT_FAMILY_NAME`, `E_CONTACT_EMAIL`, `E_CONTACT_TEL`, `E_CONTACT_IS_LIST`, `E_CONTACT_LIST_SHOW_ADDRESSES`, and `E_CONTACT_WANTS_HTML`.

The fields `E_CONTACT_FULL_NAME` and `E_CONTACT_EMAIL` are configured to respond extra quickly with the `E_BOOK_INDEX_PREFIX` index flag.

The fields `E_CONTACT_FILE_AS`, `E_CONTACT_FAMILY_NAME` and `E_CONTACT_GIVEN_NAME` are configured to perform well with the EBookCacheCursor, using the `E_BOOK_INDEX_SORT_KEY` index flag.

#### Parameters

filename | file name to load or create the new cache |
source | an optional ESource, associated with the EBookCache, or `NULL`. | [nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

A new EBookCache or `NULL` on error.

[transfer full][nullable]

Since: 3.26

### e_book_cache_new_full ()

    EBookCache *
    e_book_cache_new_full (const gchar *filename,
                           ESource *source,
                           ESourceBackendSummarySetup *setup,
                           GCancellable *cancellable,
                           GError **error);

Creates a new EBookCache with the given or the default summary configuration.

Like `e_book_sqlite_new()`, but allows configuration of which contact fields will be stored for quick reference in the summary. The configuration indicated by `setup` will only be taken into account when initially creating the underlying table, further configurations will be ignored.

The fields `E_CONTACT_UID` and `E_CONTACT_REV` are not optional, they will be stored in the summary regardless of this function's parameters. Only EContactFields with the type `G_TYPE_STRING`, `G_TYPE_BOOLEAN` or `E_TYPE_CONTACT_ATTR_LIST` are currently supported.

#### Parameters

filename | file name to load or create the new cache |
source | an optional ESource, associated with the EBookCache, or `NULL`. | [nullable]
setup | an ESourceBackendSummarySetup describing how the summary should be setup, or `NULL` to use the default. | [nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

A new EBookCache or `NULL` on error.

[transfer full][nullable]

Since: 3.26

### e_book_cache_ref_source ()

    ESource *
    e_book_cache_ref_source (EBookCache *book_cache);

References the ESource to which `book_cache` is paired, use `g_object_unref()` when no longer needed. It can be `NULL` in some cases, like when running tests.

#### Parameters

book_cache | An EBookCache |

#### Returns

A reference to the ESource to which `book_cache` is paired, or `NULL`.

[transfer full][nullable]

Since: 3.26

### e_book_cache_dup_contact_revision ()

    gchar *
    e_book_cache_dup_contact_revision (EBookCache *book_cache,
                                       EContact *contact);

Returns the `contact` revision, used to detect changes. The returned string should be freed with `g_free()`, when no longer needed.

#### Parameters

book_cache | an EBookCache |
contact | an EContact |

#### Returns

A newly allocated string containing revision of the `contact` .

[transfer full]

Since: 3.26

### e_book_cache_set_locale ()

    gboolean
    e_book_cache_set_locale (EBookCache *book_cache,
                             const gchar *lc_collate,
                             GCancellable *cancellable,
                             GError **error);

Relocalizes any locale specific data in the specified new `lc_collate` locale.

The `lc_collate` locale setting is stored and remembered on subsequent accesses of the cache, changing the locale will store the new locale and will modify sort keys and any locale specific data in the cache.

As a side effect, it's possible that changing the locale will cause stored vCard-s to change.

#### Parameters

book_cache | An EBookCache |
lc_collate | The new locale for the cache |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether the new locale was successfully set.

Since: 3.26

### e_book_cache_dup_locale ()

    gchar *
    e_book_cache_dup_locale (EBookCache *book_cache);

#### Parameters

book_cache | An EBookCache |

#### Returns

A new string containing the current local being used by the `book_cache` . Free it with `g_free()`, when no longer needed.

[transfer full]

Since: 3.26

### e_book_cache_ref_collator ()

    ECollator *
    e_book_cache_ref_collator (EBookCache *book_cache);

References the currently active ECollator for `book_cache` , use `e_collator_unref()` when finished using the returned collator.

Note that the active collator will change with the active locale setting.

#### Parameters

book_cache | An EBookCache |

#### Returns

A reference to the active collator.

[transfer full]

Since: 3.26

### e_book_cache_dup_categories ()

    gchar *
    e_book_cache_dup_categories (EBookCache *book_cache);

Returns a comma-separated list of categories used by the contacts stored in the `book_cache` . Free the returned string with `g_free()`, when no longer needed.

#### Parameters

book_cache | An EBookCache |

#### Returns

a comma-separated list of categories used by the contacts stored in the `book_cache` , or `NULL`, when no category is used by any contact.

[transfer full][nullable]

Since: 3.48

### e_book_cache_put_contact ()

    gboolean
    e_book_cache_put_contact (EBookCache *book_cache,
                              EContact *contact,
                              const gchar *extra,
                              guint32 custom_flags,
                              ECacheOfflineFlag offline_flag,
                              GCancellable *cancellable,
                              GError **error);

This is a convenience wrapper for `e_book_cache_put_contacts()`, which is the preferred way to add or modify multiple contacts when possible.

#### Parameters

book_cache | An EBookCache |
contact | an EContact to be added |
extra | extra data to store in association with this `contact` . | [nullable]
custom_flags | custom flags for the `contact` , not interpreted by the `book_cache` |
offline_flag | one of ECacheOfflineFlag, whether putting this contact in offline |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_put_contacts ()

    gboolean
    e_book_cache_put_contacts (EBookCache *book_cache,
                               const GSList *contacts,
                               const GSList *extras,
                               const GSList *custom_flags,
                               ECacheOfflineFlag offline_flag,
                               GCancellable *cancellable,
                               GError **error);

Adds or replaces contacts in `book_cache` .

If `extras` is specified, it must have an equal length as the `contacts` list. Similarly the non-NULL `custom_flags` length should be the same as the length of the `contacts` . Each element from the `extras` list and `custom_flags` list will be stored in association with its corresponding contact in the `contacts` list.

#### Parameters

book_cache | An EBookCache |
contacts | A list of contacts to add to `book_cache` . | [element-type EContact]
extras | A list of extra data to store in association with the `contacts` . | [nullable][element-type utf8]
custom_flags | optional custom flags to use for the `contacts` . | [nullable][element-type guint32]
offline_flag | one of ECacheOfflineFlag, whether putting these contacts in offline |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_remove_contact ()

    gboolean
    e_book_cache_remove_contact (EBookCache *book_cache,
                                 const gchar *uid,
                                 guint32 custom_flags,
                                 ECacheOfflineFlag offline_flag,
                                 GCancellable *cancellable,
                                 GError **error);

Removes the contact identified by `uid` from `book_cache` .

#### Parameters

book_cache | An EBookCache |
uid | the uid of the contact to remove |
custom_flags | custom flags for the contact with the given `uid` , not interpreted by the `book_cache` |
offline_flag | one of ECacheOfflineFlag, whether removing this contact in offline |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_remove_contacts ()

    gboolean
    e_book_cache_remove_contacts (EBookCache *book_cache,
                                  const GSList *uids,
                                  const GSList *custom_flags,
                                  ECacheOfflineFlag offline_flag,
                                  GCancellable *cancellable,
                                  GError **error);

Removes the contacts indicated by `uids` from `book_cache` . The `custom_flags` is used, if not `NULL`, only if the `offline_flag` is `E_CACHE_IS_OFFLINE`. Otherwise it's ignored. The length of the `custom_flags` should match the length of `uids` , when not `NULL`.

#### Parameters

book_cache | An EBookCache |
uids | a GSList of uids indicating which contacts to remove. | [element-type utf8]
custom_flags | an optional GSList of custom flags for the `ids` . | [element-type guint32][nullable]
offline_flag | one of ECacheOfflineFlag, whether removing these contacts in offline |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_get_contact ()

    gboolean
    e_book_cache_get_contact (EBookCache *book_cache,
                              const gchar *uid,
                              gboolean meta_contact,
                              EContact **out_contact,
                              GCancellable *cancellable,
                              GError **error);

Fetch the EContact specified by `uid` in `book_cache` .

If `meta_contact` is specified, then a shallow EContact will be created holding only the `E_CONTACT_UID` and `E_CONTACT_REV` fields.

#### Parameters

book_cache | An EBookCache |
uid | The uid of the contact to fetch |
meta_contact | Whether an entire contact is desired, or only the metadata |
out_contact | Return location to store the fetched contact. | [out][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_get_vcard ()

    gboolean
    e_book_cache_get_vcard (EBookCache *book_cache,
                            const gchar *uid,
                            gboolean meta_contact,
                            gchar **out_vcard,
                            GCancellable *cancellable,
                            GError **error);

Fetch a vCard string for `uid` in `book_cache` .

If `meta_contact` is specified, then a shallow vCard representation will be created holding only the `E_CONTACT_UID` and `E_CONTACT_REV` fields.

#### Parameters

book_cache | An EBookCache |
uid | The uid of the contact to fetch |
meta_contact | Whether an entire contact is desired, or only the metadata |
out_vcard | Return location to store the fetched vCard string. | [out][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_set_contact_custom_flags ()

    gboolean
    e_book_cache_set_contact_custom_flags (EBookCache *book_cache,
                                           const gchar *uid,
                                           guint32 custom_flags,
                                           GCancellable *cancellable,
                                           GError **error);

Sets or replaces the custom flags associated with a contact identified by the `uid` .

#### Parameters

book_cache | an EBookCache |
uid | The uid of the contact to set the extra data for |
custom_flags | the custom flags to set for the contact |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.34

### e_book_cache_get_contact_custom_flags ()

    gboolean
    e_book_cache_get_contact_custom_flags (EBookCache *book_cache,
                                           const gchar *uid,
                                           guint32 *out_custom_flags,
                                           GCancellable *cancellable,
                                           GError **error);

Gets the custom flags previously set for the `uid` , either with `e_book_cache_set_contact_custom_flags()`, when adding contacts or when removing contacts in offline.

#### Parameters

book_cache | an EBookCache |
uid | The uid of the contact to set the extra data for |
out_custom_flags | return location to store the custom flags. | [out]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.34

### e_book_cache_set_contact_extra ()

    gboolean
    e_book_cache_set_contact_extra (EBookCache *book_cache,
                                    const gchar *uid,
                                    const gchar *extra,
                                    GCancellable *cancellable,
                                    GError **error);

Sets or replaces the extra data associated with `uid` .

#### Parameters

book_cache | An EBookCache |
uid | The uid of the contact to set the extra data for |
extra | The extra data to set. | [nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_get_contact_extra ()

    gboolean
    e_book_cache_get_contact_extra (EBookCache *book_cache,
                                    const gchar *uid,
                                    gchar **out_extra,
                                    GCancellable *cancellable,
                                    GError **error);

Fetches the extra data previously set for `uid` , either with `e_book_cache_set_contact_extra()` or when adding contacts.

#### Parameters

book_cache | An EBookCache |
uid | The uid of the contact to fetch the extra data for |
out_extra | Return location to store the extra data. | [out][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_get_uids_with_extra ()

    gboolean
    e_book_cache_get_uids_with_extra (EBookCache *book_cache,
                                      const gchar *extra,
                                      GSList **out_uids,
                                      GCancellable *cancellable,
                                      GError **error);

Gets all the UID-s the `extra` data is set for.

The `out_uids` should be freed with g_slist_free_full (uids, g_free); when no longer needed.

#### Parameters

book_cache | an EBookCache |
extra | an extra column value to search for |
out_uids | return location to store the UIDs to. | [out][transfer full][element-type utf8]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.26

### e_book_cache_search ()

    gboolean
    e_book_cache_search (EBookCache *book_cache,
                         const gchar *sexp,
                         gboolean meta_contacts,
                         GSList **out_list,
                         GCancellable *cancellable,
                         GError **error);

Searches `book_cache` for contacts matching the search expression `sexp` .

When `sexp` refers only to EContactFields configured in the summary of `book_cache` , the search should always be quick, when searching for other EContactFields a fallback will be used.

The returned `out_list` list should be freed with g_slist_free_full (list, e_book_cache_search_data_free) when no longer needed.

If `meta_contact` is specified, then shallow vCard representations will be created holding only the `E_CONTACT_UID` and `E_CONTACT_REV` fields.

#### Parameters

book_cache | An EBookCache |
sexp | search expression; use `NULL` or an empty string to list all stored contacts. | [nullable]
meta_contacts | Whether entire contacts are desired, or only the metadata |
out_list | Return location to store a GSList of EBookCacheSearchData structures. | [out][transfer full][element-type EBookCacheSearchData]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_search_uids ()

    gboolean
    e_book_cache_search_uids (EBookCache *book_cache,
                              const gchar *sexp,
                              GSList **out_list,
                              GCancellable *cancellable,
                              GError **error);

Similar to `e_book_cache_search()`, but fetches only a list of contact UIDs.

The returned `out_list` list should be freed with g_slist_free_full(list, g_free) when no longer needed.

#### Parameters

book_cache | An EBookCache |
sexp | search expression; use `NULL` or an empty string to get all stored contacts. | [nullable]
out_list | Return location to store a GSList of contact uids. | [out][transfer full][element-type utf8]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_search_with_callback ()

    gboolean
    e_book_cache_search_with_callback (EBookCache *book_cache,
                                       const gchar *sexp,
                                       EBookCacheSearchFunc func,
                                       gpointer user_data,
                                       GCancellable *cancellable,
                                       GError **error);

Similar to `e_book_cache_search()`, but calls the `func` for each found contact.

#### Parameters

book_cache | An EBookCache |
sexp | search expression; use `NULL` or an empty string to get all stored contacts. | [nullable]
func | an EBookCacheSearchFunc callback to call for each found row. | [scope call][closure user_data]
user_data | user data for `func` |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since: 3.26

### e_book_cache_contains_email ()

    gboolean
    e_book_cache_contains_email (EBookCache *book_cache,
                                 const gchar *email_address,
                                 GCancellable *cancellable,
                                 GError **error);

Checks whether contains an `email_address` . When the `email_address` contains multiple addresses, then returns `TRUE` when at least one address exists in the cache.

If an error occurs, the function will set `error` and return `FALSE`.

#### Parameters

book_cache | an EBookCache |
email_address | an email address to check for |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` when found the `email_address` , `FALSE` on failure

Since: 3.44

### e_book_cache_cursor_new ()

    EBookCacheCursor *
    e_book_cache_cursor_new (EBookCache *book_cache,
                             const gchar *sexp,
                             const EContactField *sort_fields,
                             const EBookCursorSortType *sort_types,
                             guint n_sort_fields,
                             GError **error);

Creates a new EBookCacheCursor.

The cursor should be freed with `e_book_cache_cursor_free()` when no longer needed.

#### Parameters

book_cache | An EBookCache |
sexp | search expression; use `NULL` or an empty string to get all stored contacts. | [nullable]
sort_fields | An array of EContactField(s) as sort keys in order of priority. | [array length=n_sort_fields]
sort_types | An array of EBookCursorSortTypes, one for each field in `sort_fields` . | [array length=n_sort_fields]
n_sort_fields | The number of fields to sort results by |
error | return location for a GError, or `NULL` |

#### Returns

A newly created EBookCacheCursor.

[transfer full]

Since: 3.26

### e_book_cache_cursor_free ()

    void
    e_book_cache_cursor_free (EBookCache *book_cache,
                              EBookCacheCursor *cursor);

Frees the `cursor` , previously allocated with `e_book_cache_cursor_new()`.

#### Parameters

book_cache | An EBookCache |
cursor | The EBookCacheCursor to free |

Since: 3.26

### e_book_cache_cursor_step ()

    gint
    e_book_cache_cursor_step (EBookCache *book_cache,
                              EBookCacheCursor *cursor,
                              EBookCacheCursorStepFlags flags,
                              EBookCacheCursorOrigin origin,
                              gint count,
                              GSList **out_results,
                              GCancellable *cancellable,
                              GError **error);

Steps `cursor` through its sorted query by a maximum of `count` contacts starting from `origin` .

If `count` is negative, then the cursor will move through the list in reverse.

If `cursor` reaches the beginning or end of the query results, then the returned list might not contain the amount of desired contacts, or might return no results if the cursor currently points to the last contact. Reaching the end of the list is not considered an error condition. Attempts to step beyond the end of the list after having reached the end of the list will however trigger an `E_CACHE_ERROR_END_OF_LIST` error.

If `E_BOOK_CACHE_CURSOR_STEP_FETCH` is specified in `flags` , a pointer to a `NULL` GSList pointer should be provided for the `out_results` parameter.

The result list will be stored to `out_results` and should be freed with g_slist_free_full (results, e_book_cache_search_data_free); when no longer needed.

#### Parameters

book_cache | An EBookCache |
cursor | The EBookCacheCursor to use |
flags | The EBookCacheCursorStepFlags for this step |
origin | The EBookCacheCursorOrigin from whence to step |
count | A positive or negative amount of contacts to try and fetch |
out_results | A return location to store the results, or `NULL` if `E_BOOK_CACHE_CURSOR_STEP_FETCH` is not specified in `flags` . | [out][nullable][element-type EBookCacheSearchData][transfer full]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

The number of contacts traversed if successful, otherwise -1 is returned and the `error` is set.

Since: 3.26

### e_book_cache_cursor_set_target_alphabetic_index ()

    void
    e_book_cache_cursor_set_target_alphabetic_index
                                   (EBookCache *book_cache,
                                    EBookCacheCursor *cursor,
                                    gint idx);

Sets the `cursor` position to an

Alphabetic Index

into the alphabet active in `book_cache` 's locale.

After setting the target to an alphabetic index, for example the index for letter 'E', then further calls to `e_book_cache_cursor_step()` will return results starting with the letter 'E' (or results starting with the last result in 'D', if moving in a negative direction).

The passed index must be a valid index in the active locale, knowledge on the currently active alphabet index must be obtained using ECollator APIs.

Use `e_book_cache_ref_collator()` to obtain the active collator for `book_cache` .

#### Parameters

book_cache | An EBookCache |
cursor | The EBookCacheCursor to modify |
idx | The alphabetic index |

Since: 3.26

### e_book_cache_cursor_set_sexp ()

    gboolean
    e_book_cache_cursor_set_sexp (EBookCache *book_cache,
                                  EBookCacheCursor *cursor,
                                  const gchar *sexp,
                                  GError **error);

Modifies the current query expression for `cursor` . This will not modify `cursor` 's state, but will change the outcome of any further calls to `e_book_cache_cursor_step()` or `e_book_cache_cursor_calculate()`.

#### Parameters

book_cache | An EBookCache |
cursor | The EBookCacheCursor to modify |
sexp | The new query expression for `cursor` |
error | return location for a GError, or `NULL` |

#### Returns

`TRUE` if the expression was valid and accepted by `cursor`

Since: 3.26

### e_book_cache_cursor_calculate ()

    gboolean
    e_book_cache_cursor_calculate (EBookCache *book_cache,
                                   EBookCacheCursor *cursor,
                                   gint *out_total,
                                   gint *out_position,
                                   GCancellable *cancellable,
                                   GError **error);

Calculates the `out_total` amount of results for the `cursor` 's query expression, as well as the current `out_position` of `cursor` in the results. The `out_position` is represented as the amount of results which lead up to the current value of `cursor` , if `cursor` currently points to an exact contact, the position also includes the cursor contact.

#### Parameters

book_cache | An EBookCache |
cursor | The EBookCacheCursor |
out_total | A return location to store the total result set for this cursor. | [out][nullable]
out_position | A return location to store the cursor position. | [out][nullable]
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether `out_total` and `out_position` were successfully calculated.

Since: 3.26

### e_book_cache_cursor_compare_contact ()

    gint
    e_book_cache_cursor_compare_contact (EBookCache *book_cache,
                                         EBookCacheCursor *cursor,
                                         EContact *contact,
                                         gboolean *out_matches_sexp);

Compares `contact` with `cursor` and returns whether `contact` is less than, equal to, or greater than `cursor` .

#### Parameters

book_cache | An EBookCache |
cursor | The EBookCacheCursor |
contact | The EContact to compare |
out_matches_sexp | Whether the contact matches the cursor's search expression. | [out][nullable]

#### Returns

A value that is less than, equal to, or greater than zero if `contact` is found, respectively, to be less than, to match, or be greater than the current value of `cursor` .

Since: 3.26

### e_book_cache_count_query ()

    gboolean
    e_book_cache_count_query (EBookCache *book_cache,
                              const gchar *sexp,
                              guint *out_n_total,
                              GCancellable *cancellable,
                              GError **error);

Counts how many contacts satisfy the `sexp` .

#### Parameters

book_cache | an EBookCache |
sexp | search expression; use `NULL` or an empty string to consider all stored contacts. | [nullable]
out_n_total | return location to store the count of the contacts. | [out]
cancellable | A GCancellable |
error | A location to store any error that may have occurred |

#### Returns

Whether succeeded.

Since: 3.50

### e_book_cache_dup_query_field ()

    gboolean
    e_book_cache_dup_query_field (EBookCache *book_cache,
                                  EContactField summary_field,
                                  const gchar *sexp,
                                  EContactField sort_field,
                                  EBookCursorSortType sort_type,
                                  guint n_offset,
                                  guint n_limit,
                                  GPtrArray **out_uids,
                                  GPtrArray **out_values,
                                  GCancellable *cancellable,
                                  GError **error);

Queries the `book_cache` for a `summary_field` value for contacts in the given range and order. To get complete contacts use `e_book_cache_dup_query_contacts()`. Note the field value may not correspond precisely to the value stored in the vCard (it can be in lower case).

Both `summary_field` and `sort_field` should be in the summary, otherwise an error is returned.

The `out_uids` and `out_values` will have the same number of elements, the indexes corresponding to each other. Free the arrays with `g_ptr_aray_unref()`, when no longer needed.

#### Parameters

book_cache | an EBookCache |
summary_field | a field to query, which should be in the summary |
sexp | search expression; use `NULL` or an empty string to consider all stored contacts. | [nullable]
sort_field | a field to sort by, which should be in the summary |
sort_type | an EBookCursorSortType |
n_offset | a 0-based offset in the sorted result to start reading from, or 0 to read from start |
n_limit | how many values to return only; use 0 or G_MAXUINT to read everything from the `n_offset` |
out_uids | contact UID-s in the requested order. | [transfer container][element-type utf8]
out_values | `summary_field` values in the requested order. | [transfer container][element-type utf8]
cancellable | A GCancellable |
error | A location to store any error that may have occurred |

#### Returns

Whether succeeded.

Since: 3.50

### e_book_cache_dup_query_contacts ()

    gboolean
    e_book_cache_dup_query_contacts (EBookCache *book_cache,
                                     const gchar *sexp,
                                     EContactField sort_field,
                                     EBookCursorSortType sort_type,
                                     guint n_offset,
                                     guint n_limit,
                                     GPtrArray **out_contacts,
                                     GCancellable *cancellable,
                                     GError **error);

Queries the `book_cache` for the contacts in the given range and order. The `sort_field` should be in the summary, otherwise an error is returned.

Free the `out_contacts` with `g_ptr_aray_unref()`, when no longer needed.

#### Parameters

book_cache | an EBookCache |
sexp | search expression; use `NULL` or an empty string to consider all stored contacts. | [nullable]
sort_field | a field to sort by, which should be in the summary |
sort_type | an EBookCursorSortType |
n_offset | a 0-based offset in the sorted result to start reading from, or 0 to read from start |
n_limit | how many values to return only; use 0 or G_MAXUINT to read everything from the `n_offset` |
out_contacts | an array of EContact-s in the requested order. | [transfer container][element-type EContact]
cancellable | A GCancellable |
error | A location to store any error that may have occurred |

#### Returns

Whether succeeded.

Since: 3.50

### e_book_cache_dup_summary_field ()

    gboolean
    e_book_cache_dup_summary_field (EBookCache *book_cache,
                                    EContactField summary_field,
                                    const gchar *uid,
                                    gchar **out_value,
                                    GCancellable *cancellable,
                                    GError **error);

Queries the `book_cache` for a `summary_field` value for contact with UID `uid` . Note the field value may not correspond precisely to the value stored in the vCard (it can be in lower case).

Free the `out_value` with `g_free()`, when no longer needed.

#### Parameters

book_cache | an EBookCache |
summary_field | a field to query, which should be in the summary |
uid | a contact UID to query the `summary_field` for |
out_value | `summary_field` value. | [out callee-allocates][transfer full]
cancellable | A GCancellable |
error | A location to store any error that may have occurred |

#### Returns

Whether succeeded.

Since: 3.50

## Types and Values

### EBookCacheSearchData

    typedef struct {
    	gchar *uid;
    	gchar *vcard;
    	gchar *extra;
    } EBookCacheSearchData;

This structure is used to represent contacts returned by the EBookCache from various functions such as `e_book_cache_search()`.

The `extra` parameter will contain any data which was previously passed for this contact in `e_book_cache_put_contact()` or set with `e_book_cache_set_contact_extra()`.

These should be freed with `e_book_cache_search_data_free()`.

#### Members

gchar *`uid`; | The `E_CONTACT_UID` field of this contact |
gchar *`vcard`; | The vcard string |
gchar *`extra`; | Any extra data associated with the vcard |

Since: 3.26

### struct EBookCache

    struct EBookCache;

Contains only private data that should be read and manipulated using the functions below.

Since: 3.26

### struct EBookCacheClass

    struct EBookCacheClass {
    };

Class structure for the EBookCache class.

Since: 3.26

### enum EBookCacheCursorOrigin

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

When an EBookCacheCursor is created, the current position implied by `E_BOOK_CACHE_CURSOR_ORIGIN_CURRENT` is the same as `E_BOOK_CACHE_CURSOR_ORIGIN_BEGIN`.

#### Members

E_BOOK_CACHE_CURSOR_ORIGIN_CURRENT | The current cursor position. |
E_BOOK_CACHE_CURSOR_ORIGIN_BEGIN | The beginning of the cursor results. |
E_BOOK_CACHE_CURSOR_ORIGIN_END | The end of the cursor results. |

Since: 3.26

### enum EBookCacheCursorStepFlags

Defines the behaviour of `e_book_cache_cursor_step()`.

#### Members

E_BOOK_CACHE_CURSOR_STEP_MOVE | The cursor position should be modified while stepping. |
E_BOOK_CACHE_CURSOR_STEP_FETCH | Traversed contacts should be listed and returned while stepping. |

Since: 3.26

### EBookCacheCursor

    typedef struct _EBookCacheCursor EBookCacheCursor;

An opaque cursor pointer

Since: 3.26

## Property Details

### The `“locale”` property

      “locale”                   char *

The locale currently being used

Owner: EBookCache

Flags: Read

Default value: NULL

## Signal Details

### The `“categories-changed”` signal

    void
    user_function (EBookCache *ebookcache,
                   char       *arg1,
                   gpointer    user_data)

Flags: Action

### The `“dup-contact-revision”` signal

    char*
    user_function (EBookCache *ebookcache,
                   EContact   *arg1,
                   gpointer    user_data)

Flags: Action

### The `“e164-changed”` signal

    void
    user_function (EBookCache *ebookcache,
                   EContact   *arg1,
                   gboolean    arg2,
                   gpointer    user_data)

Flags: Run Last