EBookSqlite: Evolution-Data-Server Reference Manual

## EBookSqlite EBookSqlite — An SQLite storage facility for addressbooks |

## Functions

void | (*EbSqlChangeCallback) ()
gchar * | (*EbSqlVCardCallback) ()
GQuark | e_book_sqlite_error_quark ()
void | e_book_sqlite_search_data_free ()
EBookSqlite * | e_book_sqlite_new ()
EBookSqlite * | e_book_sqlite_new_full ()
gboolean | e_book_sqlite_lock ()
gboolean | e_book_sqlite_unlock ()
gboolean | e_book_sqlite_set_locale ()
gboolean | e_book_sqlite_get_locale ()
ECollator * | e_book_sqlite_ref_collator ()
ESource * | e_book_sqlite_ref_source ()
gboolean | e_book_sqlite_add_contact ()
gboolean | e_book_sqlite_add_contacts ()
gboolean | e_book_sqlite_remove_contact ()
gboolean | e_book_sqlite_remove_contacts ()
gboolean | e_book_sqlite_has_contact ()
gboolean | e_book_sqlite_get_contact ()
gboolean | ebsql_get_contact_unlocked ()
gboolean | e_book_sqlite_get_vcard ()
gboolean | ebsql_get_vcard_unlocked ()
gboolean | e_book_sqlite_set_contact_extra ()
gboolean | e_book_sqlite_get_contact_extra ()
gboolean | ebsql_get_contact_extra_unlocked ()
gboolean | e_book_sqlite_search ()
gboolean | e_book_sqlite_search_uids ()
gboolean | e_book_sqlite_get_key_value ()
gboolean | e_book_sqlite_set_key_value ()
gboolean | e_book_sqlite_get_key_value_int ()
gboolean | e_book_sqlite_set_key_value_int ()
EbSqlCursor * | e_book_sqlite_cursor_new ()
void | e_book_sqlite_cursor_free ()
gint | e_book_sqlite_cursor_step ()
void | e_book_sqlite_cursor_set_target_alphabetic_index ()
gboolean | e_book_sqlite_cursor_set_sexp ()
gboolean | e_book_sqlite_cursor_calculate ()
gint | e_book_sqlite_cursor_compare_contact ()
gboolean | (*EBookSqliteSelectFunc) ()
gboolean | e_book_sqlite_exec ()
gboolean | e_book_sqlite_select ()
gboolean | e_book_sqlite_count_query ()
gboolean | e_book_sqlite_dup_query_field ()
gboolean | e_book_sqlite_dup_query_contacts ()
gboolean | e_book_sqlite_dup_summary_field ()

## Signals

gboolean | before-insert-contact | Run Last
gboolean | before-remove-contact | Run Last

## Types and Values

#define | E_BOOK_SQLITE_ERROR
#define | E_BOOK_SQL_SYNC_DATA_KEY
enum | EbSqlChangeType
enum | EBookSqliteError
enum | EbSqlLockType
enum | EbSqlUnlockAction
| EbSqlSearchData
struct | EBookSqlite
struct | EBookSqliteClass
enum | EbSqlCursorOrigin
enum | EbSqlCursorStepFlags
| EbSqlCursor

## Object Hierarchy

        GObject
        ╰── EBookSqlite

## Implemented Interfaces

EBookSqlite implements

## Includes

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

## Description

The EBookSqlite is an API for storing and looking up EContact(s) 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.

## Functions

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

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

#### Parameters

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.

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

#### Parameters

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

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

#### Parameters

data | An EbSqlSearchData |

Since: 3.12

### e_book_sqlite_new ()

    EBookSqlite *
    e_book_sqlite_new (const gchar *path,
                       ESource *source,
                       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.

#### Parameters

path | location to load or create the new database |
source | an optional ESource, associated with the EBookSqlite, or `NULL`. | [nullable]
cancellable | A GCancellable |
error | A location to store any error that may have occurred. |

#### Returns

A reference to an EBookSqlite.

[transfer full]

Since: 3.12

### e_book_sqlite_new_full ()

    EBookSqlite *
    e_book_sqlite_new_full (const gchar *path,
                            ESource *source,
                            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.

#### Parameters

path | location to load or create the new database |
source | an optional ESource, associated with the EBookSqlite, or `NULL`. | [nullable]
setup | an ESourceBackendSummarySetup describing how the summary should be setup, or `NULL` to use the default. | [nullable]
vcard_callback | A function to resolve vcards. | [nullable][scope async][closure user_data]
change_callback | A function to catch notifications of vcard changes. | [nullable][scope async][closure user_data]
user_data | callback user data. | [nullable]
user_data_destroy | A function to free `user_data` automatically when the created EBookSqlite is destroyed. | [nullable]
cancellable | A GCancellable |
error | A location to store any error that may have occurred. |

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

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()`.

#### Parameters

ebsql | An EBookSqlite |
lock_type | The EbSqlLockType to acquire |
cancellable | A GCancellable |
error | A location to store any error that may have occurred. |

#### 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()`.

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

#### Parameters

ebsql | An EBookSqlite |
action | Which EbSqlUnlockAction to take while unlocking |
error | A location to store any error that may have occurred. |

#### 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()`.

#### Parameters

ebsql | An EBookSqlite |
lc_collate | The new locale for the addressbook |
cancellable | A GCancellable |
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.

#### Parameters

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.

#### Parameters

ebsql | An EBookSqlite |

#### Returns

A reference to the active collator.

[transfer full]

Since: 3.12

### e_book_sqlite_ref_source ()

    ESource *
    e_book_sqlite_ref_source (EBookSqlite *ebsql);

References the ESource to which `ebsql` is paired, use `g_object_unref()` when finished using the source. It can be `NULL` in some cases, like when running tests.

#### Parameters

ebsql | An EBookSqlite |

#### Returns

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

[transfer full][nullable]

Since: 3.16

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

Adds or replaces contacts in `ebsql` . If `replace_existing` is specified then existing contacts with the same UID will be replaced, otherwise adding an existing contact will return an error.

If `extra` is specified, it must have an equal length as the `contacts` list. Each element from the `extra` list will be stored in association with it's corresponding contact in the `contacts` list.

#### Parameters

ebsql | An EBookSqlite |
contacts | A list of contacts to add to `ebsql` . | [element-type EContact]
extra | A list of extra data to store in association with this contact. | [nullable][element-type utf8]
replace | Whether this contact should replace another contact with the same UID. |
cancellable | A GCancellable |
error | A location to store any error that may have occurred. |

#### Returns

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

Since: 3.12

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

#### Parameters

ebsql | An EBookSqlite |
uid | the uid of the contact to remove |
cancellable | A GCancellable |
error | A location to store any error that may have occurred. |

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

#### Parameters

ebsql | An EBookSqlite |
uids | a GSList of uids indicating which contacts to remove. | [element-type utf8]
cancellable | A GCancellable |
error | A location to store any error that may have occurred. |

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

#### Parameters

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

#### 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 holding only the `E_CONTACT_UID` and `E_CONTACT_REV` fields.

#### Parameters

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]
error | A location to store any error that may have occurred. |

#### Returns

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

Since: 3.12

### ebsql_get_contact_unlocked ()

    gboolean
    ebsql_get_contact_unlocked (EBookSqlite *ebsql,
                                const gchar *uid,
                                gboolean meta_contact,
                                EContact **contact,
                                GError **error);

Fetch the EContact specified by `uid` in `ebsql` without locking internal mutex.

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

#### Parameters

ebsql | An EBookSqlite |
uid | The uid of the contact to fetch |
meta_contact | Whether an entire contact is desired, or only the metadata |
contact | Return location to store the fetched contact. | [out]
error | A location to store any error that may have occurred. |

#### Returns

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

Since: 3.16

### 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 holding only the `E_CONTACT_UID` and `E_CONTACT_REV` fields.

#### Parameters

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]
error | A location to store any error that may have occurred. |

#### Returns

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

Since: 3.12

### ebsql_get_vcard_unlocked ()

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

Fetch a vcard string for `uid` in `ebsql` without locking internal mutex.

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

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]
error | A location to store any error that may have occurred. |

#### Returns

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

Since: 3.16

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

#### Parameters

ebsql | An EBookSqlite |
uid | The uid of the contact to set the extra data for |
extra | The extra data to set. | [nullable]
error | A location to store any error that may have occurred. |

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

#### Parameters

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]
error | A location to store any error that may have occurred. |

#### Returns

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

Since: 3.12

### ebsql_get_contact_extra_unlocked ()

    gboolean
    ebsql_get_contact_extra_unlocked (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, without locking internal mutex.

#### Parameters

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]
error | A location to store any error that may have occurred. |

#### Returns

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

Since: 3.16

### 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 holding only the `E_CONTACT_UID` and `E_CONTACT_REV` fields.

#### Parameters

ebsql | An EBookSqlite |
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 |
ret_list | Return location to store a GSList of EbSqlSearchData structures. | [out][transfer full][element-type EbSqlSearchData]
cancellable | A GCancellable |
error | A location to store any error that may have occurred. |

#### 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()`.

#### Parameters

ebsql | An EBookSqlite |
sexp | search expression; use `NULL` or an empty string to get all stored contacts. | [nullable]
ret_list | Return location to store a GSList of contact uids. | [out][transfer full][element-type utf8]
cancellable | A GCancellable |
error | A location to store any error that may have occurred. |

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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

#### 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()`.

[skip]

#### Parameters

ebsql | An EBookSqlite |
sexp | search expression; use `NULL` or an empty string to get all stored contacts. | [nullable]
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` .

[skip]

#### Parameters

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 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_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()`.

[skip]

#### Parameters

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][nullable][element-type EbSqlSearchData][transfer full]
cancellable | A GCancellable |
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` .

[skip]

#### Parameters

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()`.

[skip]

#### Parameters

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.

[skip]

#### Parameters

ebsql | An EBookSqlite |
cursor | The EbSqlCursor |
total | A return location to store the total result set for this cursor. | [out][optional]
position | A return location to store the total results before the cursor value. | [out][optional]
cancellable | A GCancellable |
error | A return location to store any error that might be reported. |

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

[skip]

#### Parameters

ebsql | An EBookSqlite |
cursor | The EbSqlCursor |
contact | The EContact to compare |
matches_sexp | Whether the contact matches the cursor's search expression. | [out][optional]

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

### EBookSqliteSelectFunc ()

    gboolean
    (*EBookSqliteSelectFunc) (EBookSqlite *ebsql,
                              gint ncols,
                              const gchar *column_names[],
                              const gchar *column_values[],
                              gpointer user_data);

A callback called for each row of a SELECT statement executed with `e_book_sqlite_select()` function.

#### Parameters

ebsql | an EBookSqlite |
ncols | count of columns, items in column_names and column_values |
column_names | column names. | [array length=ncols][element-type utf8]
column_values | column values. | [array length=ncols][element-type utf8]
user_data | user data, as used in `e_book_sqlite_select()` |

#### Returns

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

Since: 3.48

### e_book_sqlite_exec ()

    gboolean
    e_book_sqlite_exec (EBookSqlite *ebsql,
                        const gchar *sql_stmt,
                        GCancellable *cancellable,
                        GError **error);

Executes an SQLite statement. Use `e_book_sqlite_select()` for SELECT statements.

#### Parameters

ebsql | an EBookSqlite |
sql_stmt | an SQLite statement to execute |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.48

### e_book_sqlite_select ()

    gboolean
    e_book_sqlite_select (EBookSqlite *ebsql,
                          const gchar *sql_stmt,
                          EBookSqliteSelectFunc func,
                          gpointer user_data,
                          GCancellable *cancellable,
                          GError **error);

Executes a SELECT statement `sql_stmt` and calls `func` for each row of the result. Use `e_book_sqlite_exec()` for statements which do not return row sets.

#### Parameters

ebsql | an EBookSqlite |
sql_stmt | an SQLite SELECT statement to execute |
func | an EBookSqliteSelectFunc function to call for each row. | [scope call]
user_data | user data for `func` |
cancellable | optional GCancellable object, or `NULL` |
error | return location for a GError, or `NULL` |

#### Returns

Whether succeeded.

Since: 3.48

### e_book_sqlite_count_query ()

    gboolean
    e_book_sqlite_count_query (EBookSqlite *ebsql,
                               const gchar *sexp,
                               guint *out_n_total,
                               GCancellable *cancellable,
                               GError **error);

Counts how many contacts satisfy the `sexp` .

#### Parameters

ebsql | an EBookSqlite |
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_sqlite_dup_query_field ()

    gboolean
    e_book_sqlite_dup_query_field (EBookSqlite *ebsql,
                                   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 `ebsql` for a `summary_field` value for contacts in the given range and order. To get complete contacts use `e_book_sqlite_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

ebsql | an EBookSqlite |
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_sqlite_dup_query_contacts ()

    gboolean
    e_book_sqlite_dup_query_contacts (EBookSqlite *ebsql,
                                      const gchar *sexp,
                                      EContactField sort_field,
                                      EBookCursorSortType sort_type,
                                      guint n_offset,
                                      guint n_limit,
                                      GPtrArray **out_contacts,
                                      GCancellable *cancellable,
                                      GError **error);

Queries the `ebsql` 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

ebsql | an EBookSqlite |
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_sqlite_dup_summary_field ()

    gboolean
    e_book_sqlite_dup_summary_field (EBookSqlite *ebsql,
                                     EContactField summary_field,
                                     const gchar *uid,
                                     gchar **out_value,
                                     GCancellable *cancellable,
                                     GError **error);

Queries the `ebsql` 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

ebsql | an EBookSqlite |
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

### E_BOOK_SQLITE_ERROR

    #define E_BOOK_SQLITE_ERROR (e_book_sqlite_error_quark ())

Error domain for EBookSqlite operations.

Since: 3.12

### E_BOOK_SQL_SYNC_DATA_KEY

    #define E_BOOK_SQL_SYNC_DATA_KEY "eds-reserved-namespace-sync-data"

This key can be used with `e_book_sqlite_get_key_value()`.

In the case of a migration from an older SQLite, any value which was previously stored with `e_book_backend_sqlitedb_set_sync_data()` can be retrieved with this key.

Since: 3.12

### enum EbSqlChangeType

Indicates the type of change which occurred in an EbSqlChangeCallback

#### Members

EBSQL_CHANGE_CONTACT_ADDED | Contact was modified as a result of its 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

### enum EBookSqliteError

Defines the types of possible errors reported by the EBookSqlite

#### Members

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

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

#### Members

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

### enum 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`.

#### Members

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()`.

#### Members

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

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

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

#### Members

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

Defines the behaviour of `e_book_sqlite_cursor_step()`.

#### Members

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

### EbSqlCursor

    typedef struct _EbSqlCursor EbSqlCursor;

An opaque cursor pointer

Since: 3.12

## Signal Details

### The `“before-insert-contact”` signal

    gboolean
    user_function (EBookSqlite *ebooksqlite,
                   gpointer     arg1,
                   EContact    *arg2,
                   char        *arg3,
                   gboolean     arg4,
                   GObject     *arg5,
                   gpointer     arg6,
                   gpointer     user_data)

Flags: Run Last

### The `“before-remove-contact”` signal

    gboolean
    user_function (EBookSqlite  *ebooksqlite,
                   gpointer      arg1,
                   char         *arg2,
                   GCancellable *arg3,
                   gpointer      arg4,
                   gpointer      user_data)

Flags: Run Last