## EBookSqlite

EBookSqlite — An SQLite storage facility for addressbooks

## Synopsis

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

    #define             E_BOOK_SQLITE_ERROR
    enum                EbSqlChangeType;
    void                (*EbSqlChangeCallback)              (EbSqlChangeType change_type,
                                                             const gchar *uid,
                                                             const gchar *extra,
                                                             const gchar *vcard,
                                                             gpointer user_data);
    gchar *             (*EbSqlVCardCallback)               (const gchar *uid,
                                                             const gchar *extra,
                                                             gpointer user_data);
    enum                EBookSqliteError;
    enum                EbSqlLockType;
    enum                EbSqlUnlockAction;
                        EbSqlSearchData;
    struct              EBookSqlite;
    struct              EBookSqliteClass;
    enum                EbSqlCursorOrigin;
    enum                EbSqlCursorStepFlags;
    GQuark              e_book_sqlite_error_quark           (void);
    void                e_book_sqlite_search_data_free      (EbSqlSearchData *data);
    EBookSqlite *       e_book_sqlite_new                   (const gchar *path,
                                                             GCancellable *cancellable,
                                                             GError **error);
    EBookSqlite *       e_book_sqlite_new_full              (const gchar *path,
                                                             ESourceBackendSummarySetup *setup,
                                                             EbSqlVCardCallback vcard_callback,
                                                             EbSqlChangeCallback change_callback,
                                                             gpointer user_data,
                                                             GDestroyNotify user_data_destroy,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_lock                  (EBookSqlite *ebsql,
                                                             EbSqlLockType lock_type,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_unlock                (EBookSqlite *ebsql,
                                                             EbSqlUnlockAction action,
                                                             GError **error);
    gboolean            e_book_sqlite_set_locale            (EBookSqlite *ebsql,
                                                             const gchar *lc_collate,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_get_locale            (EBookSqlite *ebsql,
                                                             gchar **locale_out,
                                                             GError **error);
    ECollator *         e_book_sqlite_ref_collator          (EBookSqlite *ebsql);
    gboolean            e_book_sqlite_add_contact           (EBookSqlite *ebsql,
                                                             EContact *contact,
                                                             const gchar *extra,
                                                             gboolean replace,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_add_contacts          (EBookSqlite *ebsql,
                                                             GSList *contacts,
                                                             GSList *extra,
                                                             gboolean replace,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_remove_contact        (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_remove_contacts       (EBookSqlite *ebsql,
                                                             GSList *uids,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_has_contact           (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             gboolean *exists,
                                                             GError **error);
    gboolean            e_book_sqlite_get_contact           (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             gboolean meta_contact,
                                                             EContact **ret_contact,
                                                             GError **error);
    gboolean            e_book_sqlite_get_vcard             (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             gboolean meta_contact,
                                                             gchar **ret_vcard,
                                                             GError **error);
    gboolean            e_book_sqlite_set_contact_extra     (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             const gchar *extra,
                                                             GError **error);
    gboolean            e_book_sqlite_get_contact_extra     (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             gchar **ret_extra,
                                                             GError **error);
    gboolean            e_book_sqlite_search                (EBookSqlite *ebsql,
                                                             const gchar *sexp,
                                                             gboolean meta_contacts,
                                                             GSList **ret_list,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_search_uids           (EBookSqlite *ebsql,
                                                             const gchar *sexp,
                                                             GSList **ret_list,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            e_book_sqlite_get_key_value         (EBookSqlite *ebsql,
                                                             const gchar *key,
                                                             gchar **value,
                                                             GError **error);
    gboolean            e_book_sqlite_set_key_value         (EBookSqlite *ebsql,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             GError **error);
    gboolean            e_book_sqlite_get_key_value_int     (EBookSqlite *ebsql,
                                                             const gchar *key,
                                                             gint *value,
                                                             GError **error);
    gboolean            e_book_sqlite_set_key_value_int     (EBookSqlite *ebsql,
                                                             const gchar *key,
                                                             gint value,
                                                             GError **error);
    EbSqlCursor *       e_book_sqlite_cursor_new            (EBookSqlite *ebsql,
                                                             const gchar *sexp,
                                                             const EContactField *sort_fields,
                                                             const EBookCursorSortType *sort_types,
                                                             guint n_sort_fields,
                                                             GError **error);
    void                e_book_sqlite_cursor_free           (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor);
    gint                e_book_sqlite_cursor_step           (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             EbSqlCursorStepFlags flags,
                                                             EbSqlCursorOrigin origin,
                                                             gint count,
                                                             GSList **results,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                e_book_sqlite_cursor_set_target_alphabetic_index
                                                            (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             gint idx);
    gboolean            e_book_sqlite_cursor_set_sexp       (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             const gchar *sexp,
                                                             GError **error);
    gboolean            e_book_sqlite_cursor_calculate      (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             gint *total,
                                                             gint *position,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gint                e_book_sqlite_cursor_compare_contact
                                                            (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             EContact *contact,
                                                             gboolean *matches_sexp);
                        EbSqlCursor;

## Description

The EBookSqlite is an API for storing and looking up EContacts in an SQLite database. It also supports a lean index mode via the EbSqlVCardCallback, if you are in a situation where it is not convenient to store the vCards directly in the SQLite. It is however recommended to avoid storing contacts in separate storage if at all possible, as this will decrease performance of searches an also contribute to flash wear.

The API is thread safe, with special considerations to be made around `e_book_sqlite_lock()` and `e_book_sqlite_unlock()` for the sake of isolating transactions across threads.

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.

## Details

### E_BOOK_SQLITE_ERROR

    #define E_BOOK_SQLITE_ERROR (e_book_sqlite_error_quark ())

Error domain for EBookSqlite operations.

Since 3.12

### enum EbSqlChangeType

    typedef enum {
    	EBSQL_CHANGE_CONTACT_ADDED,
    	EBSQL_CHANGE_LOCALE_CHANGED,
    	EBSQL_CHANGE_LAST
    } EbSqlChangeType;

Indicates the type of change which occurred in a EbSqlChangeCallback

`EBSQL_CHANGE_CONTACT_ADDED` | Contact was modified as a result of it's addition to the addressbook
`EBSQL_CHANGE_LOCALE_CHANGED` | Contact was modified as a result of a locale change
`EBSQL_CHANGE_LAST` | A symbolic end marker for this enumeration, will not be passed in callbacks.

Since 3.12

### EbSqlChangeCallback ()

    void                (*EbSqlChangeCallback)              (EbSqlChangeType change_type,
                                                             const gchar *uid,
                                                             const gchar *extra,
                                                             const gchar *vcard,
                                                             gpointer user_data);

A function which may be called in response to a change in contact data.

### Note

This user callback is called inside a lock, you must not call the EBookSqlite API from this callback.

`change_type` : | The EbSqlChangeType which occurred
`uid` : | A contact UID
`extra` : | The extra data associated to the contact
`vcard` : | The vcard string for this UID
`user_data` : | Pointer to user provided data

Since 3.12

### EbSqlVCardCallback ()

    gchar *             (*EbSqlVCardCallback)               (const gchar *uid,
                                                             const gchar *extra,
                                                             gpointer user_data);

If this callback is passed to `e_book_sqlite_new()`, then vcards are not stored in the SQLite and instead this callback is invoked to fetch the vcard.

This callback will be called to fetch results for fully indexed and optimized queries, and it will also be called while performing fallback queries against EContactFields which are not configured in the ESourceBackendSummarySetup or default summary fields.

### Note

This user callback is called inside a lock, you must not call the EBookSqlite API from this callback.

`uid` : | A contact UID
`extra` : | The extra data associated to the contact
`user_data` : | User data previously passed to `e_book_sqlite_new()`
Returns : | The appropriate vcard indicated by `uid`. [transfer full]

Since 3.12

### enum EBookSqliteError

    typedef enum {
    	E_BOOK_SQLITE_ERROR_ENGINE,
    	E_BOOK_SQLITE_ERROR_CONSTRAINT,
    	E_BOOK_SQLITE_ERROR_CONTACT_NOT_FOUND,
    	E_BOOK_SQLITE_ERROR_INVALID_QUERY,
    	E_BOOK_SQLITE_ERROR_UNSUPPORTED_QUERY,
    	E_BOOK_SQLITE_ERROR_UNSUPPORTED_FIELD,
    	E_BOOK_SQLITE_ERROR_END_OF_LIST,
    	E_BOOK_SQLITE_ERROR_LOAD
    } EBookSqliteError;

Defines the types of possible errors reported by the EBookSqlite

`E_BOOK_SQLITE_ERROR_ENGINE` | An error was reported from the SQLite engine
`E_BOOK_SQLITE_ERROR_CONSTRAINT` | The error occurred due to an explicit constraint, this will happen when attempting to add two contacts with the same UID.
`E_BOOK_SQLITE_ERROR_CONTACT_NOT_FOUND` | A contact was not found by UID (this is different from a query that returns no results, which is not an error).
`E_BOOK_SQLITE_ERROR_INVALID_QUERY` | A query was invalid. This can happen if the search expression could not be parsed or if a phone number query contained non-phonenumber input.
`E_BOOK_SQLITE_ERROR_UNSUPPORTED_QUERY` | A query was not supported
`E_BOOK_SQLITE_ERROR_UNSUPPORTED_FIELD` | An unsupported EContactField was specified in the summary
`E_BOOK_SQLITE_ERROR_END_OF_LIST` | An attempt was made to fetch results past the end of a contact list
`E_BOOK_SQLITE_ERROR_LOAD` | An error occured while loading or creating the database

### enum EbSqlLockType

    typedef enum {
    	EBSQL_LOCK_READ,
    	EBSQL_LOCK_WRITE
    } EbSqlLockType;

Indicates the type of lock requested in `e_book_sqlite_lock()`

`EBSQL_LOCK_READ` | Obtain a lock for reading
`EBSQL_LOCK_WRITE` | Obtain a lock for writing

### enum EbSqlUnlockAction

    typedef enum {
    	EBSQL_UNLOCK_NONE,
    	EBSQL_UNLOCK_COMMIT,
    	EBSQL_UNLOCK_ROLLBACK
    } EbSqlUnlockAction;

Indicates what type of action to take while unlocking the sqlite with `e_book_sqlite_unlock()`

In the case that some addressbook modification failed while holding an `EBSQL_LOCK_WRITE` lock, then the EBookSqlite must be unlocked with `EBSQL_UNLOCK_ROLLBACK`.

`EBSQL_UNLOCK_NONE` | Just unlock, this is appropriate for locks which were obtained with `EBSQL_LOCK_READ`
`EBSQL_UNLOCK_COMMIT` | Commit any modifications which were made while the lock was held
`EBSQL_UNLOCK_ROLLBACK` | Rollback any modifications which were made while the lock was held

### EbSqlSearchData

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

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

The `extra` parameter will contain any data which was previously passed for this contact in `e_book_sqlite_add_contact()`.

These should be freed with `e_book_sqlite_search_data_free()`.

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

Since 3.12

### struct EBookSqlite

    struct EBookSqlite {
    };

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

Since 3.12

### struct EBookSqliteClass

    struct EBookSqliteClass {
    };

Class structure for the EBookSqlite class.

Since 3.12

### enum EbSqlCursorOrigin

    typedef enum {
    	EBSQL_CURSOR_ORIGIN_CURRENT = 0,
    	EBSQL_CURSOR_ORIGIN_BEGIN,
    	EBSQL_CURSOR_ORIGIN_END
    } EbSqlCursorOrigin;

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

When an EbSqlCuror is created, the current position implied by `EBSQL_CURSOR_ORIGIN_CURRENT` is the same as `EBSQL_CURSOR_ORIGIN_BEGIN`.

`EBSQL_CURSOR_ORIGIN_CURRENT` | The current cursor position
`EBSQL_CURSOR_ORIGIN_BEGIN` | The beginning of the cursor results.
`EBSQL_CURSOR_ORIGIN_END` | The ending of the cursor results.

Since 3.12

### enum EbSqlCursorStepFlags

    typedef enum {
    	EBSQL_CURSOR_STEP_MOVE = (1 << 0),
    	EBSQL_CURSOR_STEP_FETCH = (1 << 1)
    } EbSqlCursorStepFlags;

Defines the behaviour of `e_book_sqlite_cursor_step()`.

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

Since 3.12

### e_book_sqlite_error_quark ()

    GQuark              e_book_sqlite_error_quark           (void);

### e_book_sqlite_search_data_free ()

    void                e_book_sqlite_search_data_free      (EbSqlSearchData *data);

Frees an EbSqlSearchData

`data` : | An EbSqlSearchData

Since 3.12

### e_book_sqlite_new ()

    EBookSqlite *       e_book_sqlite_new                   (const gchar *path,
                                                             GCancellable *cancellable,
                                                             GError **error);

Creates a new EBookSqlite with the default summary configuration.

Aside from the manditory 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 EbSqlCursor interface, using the `E_BOOK_INDEX_SORT_KEY` index flag.

`path` : | location to load or create the new database
`cancellable` : | A GCancellable. [allow-none]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | A reference to a EBookSqlite. [transfer full]

Since 3.12

### e_book_sqlite_new_full ()

    EBookSqlite *       e_book_sqlite_new_full              (const gchar *path,
                                                             ESourceBackendSummarySetup *setup,
                                                             EbSqlVCardCallback vcard_callback,
                                                             EbSqlChangeCallback change_callback,
                                                             gpointer user_data,
                                                             GDestroyNotify user_data_destroy,
                                                             GCancellable *cancellable,
                                                             GError **error);

Opens or creates a new addressbook at `path`.

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.

If `vcard_callback` is specified, then vcards will not be stored by functions such as `e_book_sqlitedb_add_contact()`. Instead `vcard_callback` will be invoked at any time the created EBookSqlite requires a vcard, either as a fallback for querying search expressions which cannot be satisfied with the summary fields, or when reporting results from searches.

If any error occurs and `NULL` is returned, then the passed `user_data` will be automatically freed using the `user_data_destroy` function, if specified.

It is recommended to store all contact vcards in the EBookSqlite addressbook if at all possible, however in some cases the vcards must be stored in some other storage.

`path` : | location to load or create the new database
`setup` : | an ESourceBackendSummarySetup describing how the summary should be setup, or `NULL` to use the default. [allow-none]
`vcard_callback` : | A function to resolve vcards. [allow-none][scope async][closure user_data]
`change_callback` : | A function to catch notifications of vcard changes. [allow-none][scope async][closure user_data]
`user_data` : | callback user data. [allow-none]
`user_data_destroy` : | A function to free `user_data` automatically when the created EBookSqlite is destroyed. [allow-none]
`cancellable` : | A GCancellable. [allow-none]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | The newly created EBookSqlite, or `NULL` if opening or creating the addressbook failed. [transfer full]

Since 3.12

### e_book_sqlite_lock ()

    gboolean            e_book_sqlite_lock                  (EBookSqlite *ebsql,
                                                             EbSqlLockType lock_type,
                                                             GCancellable *cancellable,
                                                             GError **error);

Obtains an exclusive lock on `ebsql` and starts a transaction.

This should be called if you need to access `ebsql` multiple times while ensuring an atomic transaction. End this transaction with `e_book_sqlite_unlock()`.

If `cancellable` is specified, then `ebsql` will retain a reference to it until `e_book_sqlite_unlock()` is called. Any accesses to `ebsql` with the lock held are expected to have the same `cancellable` specified, or `NULL`.

### Note

Aside from ensuring atomicity of transactions, this function will hold a mutex which will cause further calls to `e_book_sqlite_lock()` to block. If you are accessing `ebsql` from multiple threads, then any interactions with `ebsql` should be nested in calls to `e_book_sqlite_lock()` and `e_book_sqlite_unlock()`.

`ebsql` : | An EBookSqlite
`lock_type` : | The EbSqlLockType to acquire
`cancellable` : | A GCancellable. [allow-none]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_unlock ()

    gboolean            e_book_sqlite_unlock                (EBookSqlite *ebsql,
                                                             EbSqlUnlockAction action,
                                                             GError **error);

Releases an exclusive on `ebsql` and finishes a transaction previously started with `e_book_sqlite_lock_updates()`.

### Note

If this fails, the lock on `ebsql` is still released and `error` will be set to indicate why the transaction or rollback failed.

`ebsql` : | An EBookSqlite
`action` : | Which EbSqlUnlockAction to take while unlocking
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_set_locale ()

    gboolean            e_book_sqlite_set_locale            (EBookSqlite *ebsql,
                                                             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 addressbook, changing the locale will store the new locale and will modify sort keys and any locale specific data in the addressbook.

As a side effect, it's possible that changing the locale will cause stored vcards to change. Notifications for these changes can be caught with the EbSqlVCardCallback provided to `e_book_sqlite_new_full()`.

`ebsql` : | An EBookSqlite
`lc_collate` : | The new locale for the addressbook
`cancellable` : | A GCancellable. [allow-none]
`error` : | A location to store any error that may have occurred
Returns : | Whether the new locale was successfully set.

Since 3.12

### e_book_sqlite_get_locale ()

    gboolean            e_book_sqlite_get_locale            (EBookSqlite *ebsql,
                                                             gchar **locale_out,
                                                             GError **error);

Fetches the current locale setting for the address-book.

Upon success, `lc_collate_out` will hold the returned locale setting, otherwise `FALSE` will be returned and `error` will be updated accordingly.

`ebsql` : | An EBookSqlite
`locale_out` : | The location to return the current locale. [out][transfer full]
`error` : | A location to store any error that may have occurred
Returns : | Whether the locale was successfully fetched.

Since 3.12

### e_book_sqlite_ref_collator ()

    ECollator *         e_book_sqlite_ref_collator          (EBookSqlite *ebsql);

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

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

`ebsql` : | An EBookSqlite
Returns : | A reference to the active collator. [transfer full]

Since 3.12

### e_book_sqlite_add_contact ()

    gboolean            e_book_sqlite_add_contact           (EBookSqlite *ebsql,
                                                             EContact *contact,
                                                             const gchar *extra,
                                                             gboolean replace,
                                                             GCancellable *cancellable,
                                                             GError **error);

### e_book_sqlite_add_contacts ()

    gboolean            e_book_sqlite_add_contacts          (EBookSqlite *ebsql,
                                                             GSList *contacts,
                                                             GSList *extra,
                                                             gboolean replace,
                                                             GCancellable *cancellable,
                                                             GError **error);

### e_book_sqlite_remove_contact ()

    gboolean            e_book_sqlite_remove_contact        (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             GCancellable *cancellable,
                                                             GError **error);

Removes the contact indicated by `uid` from `ebsql`.

`ebsql` : | An EBookSqlite
`uid` : | the uid of the contact to remove
`cancellable` : | A GCancellable. [allow-none]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_remove_contacts ()

    gboolean            e_book_sqlite_remove_contacts       (EBookSqlite *ebsql,
                                                             GSList *uids,
                                                             GCancellable *cancellable,
                                                             GError **error);

Removes the contacts indicated by `uids` from `ebsql`.

`ebsql` : | An EBookSqlite
`uids` : | a GSList of uids indicating which contacts to remove
`cancellable` : | A GCancellable. [allow-none]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_has_contact ()

    gboolean            e_book_sqlite_has_contact           (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             gboolean *exists,
                                                             GError **error);

Checks if a contact bearing the UID indicated by `uid` is stored in `ebsql`.

`ebsql` : | An EBookSqlite
`uid` : | The uid of the contact to check for
`exists` : | Return location to store whether the contact exists. [out]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_get_contact ()

    gboolean            e_book_sqlite_get_contact           (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             gboolean meta_contact,
                                                             EContact **ret_contact,
                                                             GError **error);

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

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

`ebsql` : | An EBookSqlite
`uid` : | The uid of the contact to fetch
`meta_contact` : | Whether an entire contact is desired, or only the metadata
`ret_contact` : | Return location to store the fetched contact. [out][transfer full]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_get_vcard ()

    gboolean            e_book_sqlite_get_vcard             (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             gboolean meta_contact,
                                                             gchar **ret_vcard,
                                                             GError **error);

Fetch a vcard string for `uid` in `ebsql`.

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

`ebsql` : | An EBookSqlite
`uid` : | The uid of the contact to fetch
`meta_contact` : | Whether an entire contact is desired, or only the metadata
`ret_vcard` : | Return location to store the fetched vcard string. [out][transfer full]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_set_contact_extra ()

    gboolean            e_book_sqlite_set_contact_extra     (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             const gchar *extra,
                                                             GError **error);

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

`ebsql` : | An EBookSqlite
`uid` : | The uid of the contact to set the extra data for
`extra` : | The extra data to set. [allow-none]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_get_contact_extra ()

    gboolean            e_book_sqlite_get_contact_extra     (EBookSqlite *ebsql,
                                                             const gchar *uid,
                                                             gchar **ret_extra,
                                                             GError **error);

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

`ebsql` : | An EBookSqlite
`uid` : | The uid of the contact to fetch the extra data for
`ret_extra` : | Return location to store the extra data. [out][transfer full]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_search ()

    gboolean            e_book_sqlite_search                (EBookSqlite *ebsql,
                                                             const gchar *sexp,
                                                             gboolean meta_contacts,
                                                             GSList **ret_list,
                                                             GCancellable *cancellable,
                                                             GError **error);

Searches `ebsql` for contacts matching the search expression indicated by `sexp`.

When `sexp` refers only to EContactFields configured in the summary of `ebsql`, the search should always be quick, when searching for other EContactFields a fallback will be used, possibly invoking any EbSqlVCardCallback which may have been passed to `e_book_sqlite_new_full()`.

The returned `ret_list` list should be freed with `g_slist_free()` and all elements freed with `e_book_sqlite_search_data_free()`.

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

`ebsql` : | An EBookSqlite
`sexp` : | search expression; use `NULL` or an empty string to list all stored contacts. [allow-none]
`meta_contacts` : | Whether entire contacts are desired, or only the metadata
`ret_list` : | Return location to store a GSList of EbSqlSearchData structures. [out][transfer full][element-type EbSqlSearchData]
`cancellable` : | A GCancellable. [allow-none]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_search_uids ()

    gboolean            e_book_sqlite_search_uids           (EBookSqlite *ebsql,
                                                             const gchar *sexp,
                                                             GSList **ret_list,
                                                             GCancellable *cancellable,
                                                             GError **error);

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

The returned `ret_list` list should be freed with `g_slist_free()` and all elements freed with `g_free()`.

`ebsql` : | An EBookSqlite
`sexp` : | search expression; use `NULL` or an empty string to get all stored contacts. [allow-none]
`ret_list` : | Return location to store a GSList of contact uids. [out][transfer full]
`cancellable` : | A GCancellable. [allow-none]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_get_key_value ()

    gboolean            e_book_sqlite_get_key_value         (EBookSqlite *ebsql,
                                                             const gchar *key,
                                                             gchar **value,
                                                             GError **error);

Fetches the value for `key` and stores it in `value`

`ebsql` : | An EBookSqlite
`key` : | The key to fetch a value for
`value` : | A return location to store the value for `key`. [out][transfer full]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_set_key_value ()

    gboolean            e_book_sqlite_set_key_value         (EBookSqlite *ebsql,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             GError **error);

Sets the value for `key` to be `value`

`ebsql` : | An EBookSqlite
`key` : | The key to fetch a value for
`value` : | The new value for `key`
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_get_key_value_int ()

    gboolean            e_book_sqlite_get_key_value_int     (EBookSqlite *ebsql,
                                                             const gchar *key,
                                                             gint *value,
                                                             GError **error);

A convenience function to fetch the value of `key` as an integer.

`ebsql` : | An EBookSqlite
`key` : | The key to fetch a value for
`value` : | A return location to store the value for `key`. [out]
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_set_key_value_int ()

    gboolean            e_book_sqlite_set_key_value_int     (EBookSqlite *ebsql,
                                                             const gchar *key,
                                                             gint value,
                                                             GError **error);

A convenience function to set the value of `key` as an integer.

`ebsql` : | An EBookSqlite
`key` : | The key to fetch a value for
`value` : | The new value for `key`
`error` : | A location to store any error that may have occurred. [allow-none]
Returns : | `TRUE` on success, otherwise `FALSE` is returned and `error` is set appropriately.

Since 3.12

### e_book_sqlite_cursor_new ()

    EbSqlCursor *       e_book_sqlite_cursor_new            (EBookSqlite *ebsql,
                                                             const gchar *sexp,
                                                             const EContactField *sort_fields,
                                                             const EBookCursorSortType *sort_types,
                                                             guint n_sort_fields,
                                                             GError **error);

Creates a new EbSqlCursor.

The cursor should be freed with `e_book_sqlite_cursor_free()`.

`ebsql` : | An EBookSqlite
`sexp` : | search expression; use NULL or an empty string to get all stored contacts.
`sort_fields` : | An array of EContactFields 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` : | A return location to store any error that might be reported.
Returns : | A newly created EbSqlCursor. [transfer full]

Since 3.12

### e_book_sqlite_cursor_free ()

    void                e_book_sqlite_cursor_free           (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor);

Frees `cursor`.

`ebsql` : | An EBookSqlite
`cursor` : | The EbSqlCursor to free

Since 3.12

### e_book_sqlite_cursor_step ()

    gint                e_book_sqlite_cursor_step           (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             EbSqlCursorStepFlags flags,
                                                             EbSqlCursorOrigin origin,
                                                             gint count,
                                                             GSList **results,
                                                             GCancellable *cancellable,
                                                             GError **error);

Steps `cursor` through it's 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_BOOK_SQLITE_ERROR_END_OF_LIST` error.

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

The result list will be stored to `results` and should be freed with `g_slist_free()` and all elements freed with `e_book_sqlite_search_data_free()`.

`ebsql` : | An EBookSqlite
`cursor` : | The EbSqlCursor to use
`flags` : | The EbSqlCursorStepFlags for this step
`origin` : | The EbSqlCursorOrigin from whence to step
`count` : | A positive or negative amount of contacts to try and fetch
`results` : | A return location to store the results, or `NULL` if `EBSQL_CURSOR_STEP_FETCH` is not specified in `flags`. [out][allow-none][element-type EbSqlSearchData][transfer full]
`cancellable` : | A GCancellable. [allow-none]
`error` : | A return location to store any error that might be reported.
Returns : | The number of contacts traversed if successful, otherwise -1 is returned and `error` is set.

Since 3.12

### e_book_sqlite_cursor_set_target_alphabetic_index ()

    void                e_book_sqlite_cursor_set_target_alphabetic_index
                                                            (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             gint idx);

Sets the `cursor` position to an Alphabetic Index into the alphabet active in `ebsql`'s locale.

After setting the target to an alphabetic index, for example the index for letter 'E', then further calls to `e_book_sqlite_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_sqlite_ref_collator()` to obtain the active collator for `ebsql`.

`ebsql` : | An EBookSqlite
`cursor` : | The EbSqlCursor to modify
`idx` : | The alphabetic index

Since 3.12

### e_book_sqlite_cursor_set_sexp ()

    gboolean            e_book_sqlite_cursor_set_sexp       (EBookSqlite *ebsql,
                                                             EbSqlCursor *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_sqlite_cursor_calculate()` or `e_book_sqlite_cursor_step()`.

`ebsql` : | An EBookSqlite
`cursor` : | The EbSqlCursor
`sexp` : | The new query expression for `cursor`
`error` : | A return location to store any error that might be reported.
Returns : | `TRUE` if the expression was valid and accepted by `ebsql`

Since 3.12

### e_book_sqlite_cursor_calculate ()

    gboolean            e_book_sqlite_cursor_calculate      (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             gint *total,
                                                             gint *position,
                                                             GCancellable *cancellable,
                                                             GError **error);

Calculates the `total` amount of results for the `cursor`'s query expression, as well as the current `position` of `cursor` in the results. `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.

`ebsql` : | An EBookSqlite
`cursor` : | The EbSqlCursor
`total` : | A return location to store the total result set for this cursor. [out][allow-none]
`position` : | A return location to store the total results before the cursor value. [out][allow-none]
`cancellable` : | A GCancellable. [allow-none]
`error` : | A return location to store any error that might be reported. [allow-none]
Returns : | Whether `total` and `position` were successfully calculated.

Since 3.12

### e_book_sqlite_cursor_compare_contact ()

    gint                e_book_sqlite_cursor_compare_contact
                                                            (EBookSqlite *ebsql,
                                                             EbSqlCursor *cursor,
                                                             EContact *contact,
                                                             gboolean *matches_sexp);

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

`ebsql` : | An EBookSqlite
`cursor` : | The EbSqlCursor
`contact` : | The EContact to compare
`matches_sexp` : | Whether the contact matches the cursor's search expression. [out][allow-none]
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.12

### EbSqlCursor

    typedef struct _EbSqlCursor EbSqlCursor;