EBookBackendSqliteDB: Evolution-Data-Server Reference Manual

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

## Functions

GQuark | e_book_backend_sqlitedb_error_quark ()
EBookBackendSqliteDB * | e_book_backend_sqlitedb_new ()
EBookBackendSqliteDB * | e_book_backend_sqlitedb_new_full ()
gboolean | e_book_backend_sqlitedb_lock_updates ()
gboolean | e_book_backend_sqlitedb_unlock_updates ()
ECollator * | e_book_backend_sqlitedb_ref_collator ()
gboolean | e_book_backend_sqlitedb_new_contact ()
gboolean | e_book_backend_sqlitedb_new_contacts ()
gboolean | e_book_backend_sqlitedb_remove_contact ()
gboolean | e_book_backend_sqlitedb_remove_contacts ()
gboolean | e_book_backend_sqlitedb_has_contact ()
EContact * | e_book_backend_sqlitedb_get_contact ()
gchar * | e_book_backend_sqlitedb_get_vcard_string ()
GSList * | e_book_backend_sqlitedb_search ()
GSList * | e_book_backend_sqlitedb_search_uids ()
GHashTable * | e_book_backend_sqlitedb_get_uids_and_rev ()
gboolean | e_book_backend_sqlitedb_get_is_populated ()
gboolean | e_book_backend_sqlitedb_set_is_populated ()
gboolean | e_book_backend_sqlitedb_get_revision ()
gboolean | e_book_backend_sqlitedb_set_revision ()
gchar * | e_book_backend_sqlitedb_get_sync_data ()
gboolean | e_book_backend_sqlitedb_set_sync_data ()
gchar * | e_book_backend_sqlitedb_get_key_value ()
gboolean | e_book_backend_sqlitedb_set_key_value ()
gchar * | e_book_backend_sqlitedb_get_contact_bdata ()
gboolean | e_book_backend_sqlitedb_set_contact_bdata ()
gboolean | e_book_backend_sqlitedb_get_has_partial_content ()
gboolean | e_book_backend_sqlitedb_set_has_partial_content ()
GSList * | e_book_backend_sqlitedb_get_partially_cached_ids ()
gboolean | e_book_backend_sqlitedb_delete_addressbook ()
gboolean | e_book_backend_sqlitedb_remove ()
void | e_book_backend_sqlitedb_search_data_free ()
gboolean | e_book_backend_sqlitedb_check_summary_query ()
gboolean | e_book_backend_sqlitedb_check_summary_fields ()
gboolean | e_book_backend_sqlitedb_set_locale ()
gboolean | e_book_backend_sqlitedb_get_locale ()
EbSdbCursor * | e_book_backend_sqlitedb_cursor_new ()
void | e_book_backend_sqlitedb_cursor_free ()
gint | e_book_backend_sqlitedb_cursor_step ()
void | e_book_backend_sqlitedb_cursor_set_target_alphabetic_index ()
gboolean | e_book_backend_sqlitedb_cursor_set_sexp ()
gboolean | e_book_backend_sqlitedb_cursor_calculate ()
gint | e_book_backend_sqlitedb_cursor_compare_contact ()
gboolean | e_book_backend_sqlitedb_is_summary_query ()
gboolean | e_book_backend_sqlitedb_is_summary_fields ()
gboolean | e_book_backend_sqlitedb_add_contact ()
gboolean | e_book_backend_sqlitedb_add_contacts ()

## Types and Values

#define | E_BOOK_SDB_ERROR
enum | EBookSDBError
struct | EBookBackendSqliteDB
struct | EBookBackendSqliteDBClass
| EbSdbSearchData
enum | EbSdbCursorOrigin
enum | EbSdbCursorStepFlags
| EbSdbCursor

## Object Hierarchy

        GObject
        ╰── EBookBackendSqliteDB

## Includes

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

## Description

The EBookBackendSqliteDB is deprecated, use EBookSqlite instead.

## Functions

### e_book_backend_sqlitedb_error_quark ()

    GQuark
    e_book_backend_sqlitedb_error_quark (void);

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

### e_book_backend_sqlitedb_new ()

    EBookBackendSqliteDB *
    e_book_backend_sqlitedb_new (const gchar *path,
                                 const gchar *emailid,
                                 const gchar *folderid,
                                 const gchar *folder_name,
                                 gboolean store_vcard,
                                 GError **error);

`e_book_backend_sqlitedb_new` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

If the path for multiple addressbooks are same, the contacts from all addressbooks would be stored in same db in different tables.

#### Parameters

path | location where the db would be created |
emailid | email id of the user |
folderid | folder id of the address-book |
folder_name | name of the address-book |
store_vcard | True if the vcard should be stored inside db, if FALSE only the summary fields would be stored inside db. |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

A reference to a EBookBackendSqliteDB.

[transfer full]

Since: 3.2

### e_book_backend_sqlitedb_new_full ()

    EBookBackendSqliteDB *
    e_book_backend_sqlitedb_new_full (const gchar *path,
                                      const gchar *emailid,
                                      const gchar *folderid,
                                      const gchar *folder_name,
                                      gboolean store_vcard,
                                      ESourceBackendSummarySetup *setup,
                                      GError **error);

`e_book_backend_sqlitedb_new_full` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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

The fields `E_CONTACT_UID` and `E_CONTACT_REV` are not optional, they will be stored in the summary regardless of this function's parameters

Only EContactFields with the type G_TYPE_STRING, G_TYPE_BOOLEAN or E_TYPE_CONTACT_ATTR_LIST are currently supported.

#### Parameters

path | location where the db would be created |
emailid | email id of the user |
folderid | folder id of the address-book |
folder_name | name of the address-book |
store_vcard | True if the vcard should be stored inside db, if FALSE only the summary fields would be stored inside db. |
setup | an ESourceBackendSummarySetup describing how the summary should be setup |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

The newly created EBookBackendSqliteDB.

[transfer full]

Since: 3.8

### e_book_backend_sqlitedb_lock_updates ()

    gboolean
    e_book_backend_sqlitedb_lock_updates (EBookBackendSqliteDB *ebsdb,
                                          GError **error);

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

### e_book_backend_sqlitedb_unlock_updates ()

    gboolean
    e_book_backend_sqlitedb_unlock_updates
                                   (EBookBackendSqliteDB *ebsdb,
                                    gboolean do_commit,
                                    GError **error);

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

### e_book_backend_sqlitedb_ref_collator ()

    ECollator *
    e_book_backend_sqlitedb_ref_collator (EBookBackendSqliteDB *ebsdb);

`e_book_backend_sqlitedb_ref_collator` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |

#### Returns

A reference to the active collator.

[transfer full]

### e_book_backend_sqlitedb_new_contact ()

    gboolean
    e_book_backend_sqlitedb_new_contact (EBookBackendSqliteDB *ebsdb,
                                         const gchar *folderid,
                                         EContact *contact,
                                         gboolean replace_existing,
                                         GError **error);

`e_book_backend_sqlitedb_new_contact` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

This is a convenience wrapper for e_book_backend_sqlitedb_new_contacts, which is the preferred means to add or modify multiple contacts when possible.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id |
contact | EContact to be added |
replace_existing | Whether this contact should replace another contact with the same UID. |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

TRUE on success.

Since: 3.8

### e_book_backend_sqlitedb_new_contacts ()

    gboolean
    e_book_backend_sqlitedb_new_contacts (EBookBackendSqliteDB *ebsdb,
                                          const gchar *folderid,
                                          GSList *contacts,
                                          gboolean replace_existing,
                                          GError **error);

`e_book_backend_sqlitedb_new_contacts` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id |
contacts | list of EContacts |
replace_existing | Whether this contact should replace another contact with the same UID. |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

TRUE on success.

Since: 3.8

### e_book_backend_sqlitedb_remove_contact ()

    gboolean
    e_book_backend_sqlitedb_remove_contact
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    const gchar *uid,
                                    GError **error);

`e_book_backend_sqlitedb_remove_contact` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Removes the contact indicated by `uid` from the folder `folderid` in `ebsdb` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id |
uid | the uid of the contact to remove |
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.2

### e_book_backend_sqlitedb_remove_contacts ()

    gboolean
    e_book_backend_sqlitedb_remove_contacts
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    GSList *uids,
                                    GError **error);

`e_book_backend_sqlitedb_remove_contacts` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Removes the contacts indicated by `uids` from the folder `folderid` in `ebsdb` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id |
uids | a GSList of uids indicating which contacts to remove |
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.2

### e_book_backend_sqlitedb_has_contact ()

    gboolean
    e_book_backend_sqlitedb_has_contact (EBookBackendSqliteDB *ebsdb,
                                         const gchar *folderid,
                                         const gchar *uid,
                                         gboolean *partial_content,
                                         GError **error);

`e_book_backend_sqlitedb_has_contact` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Checks if a contact bearing the UID indicated by `uid` is stored in `folderid` of `ebsdb` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id |
uid | The uid of the contact to check for |
partial_content | This parameter is deprecated and unused. |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

`TRUE` if the the contact exists and there was no error, otherwise `FALSE`.

In order to differentiate an error from a contact which simply is not stored in `ebsdb`, you must pass the `error` parameter and check whether it was set by this function.

Since: 3.2

### e_book_backend_sqlitedb_get_contact ()

    EContact *
    e_book_backend_sqlitedb_get_contact (EBookBackendSqliteDB *ebsdb,
                                         const gchar *folderid,
                                         const gchar *uid,
                                         GHashTable *fields_of_interest,
                                         gboolean *with_all_required_fields,
                                         GError **error);

`e_book_backend_sqlitedb_get_contact` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Fetch the EContact specified by `uid` in `folderid` of `ebsdb` .

The `fields_of_interest` parameter is a legacy parameter which can be used to specify that EContacts with only the `E_CONTACT_UID` and `E_CONTACT_REV` fields. The hash table must use `g_str_hash()` and `g_str_equal()` and the keys 'uid' and 'rev' must be present.

In order to differentiate an error from a contact which simply is not stored in `ebsdb`, you must pass the `error` parameter and check whether it was set by this function.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id |
uid | The uid of the contact to fetch |
fields_of_interest | A GHashTable indicating which fields should be included in returned contacts. | [allow-none]
with_all_required_fields | Whether all of the fields of interest were available. | [out][allow-none]
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

On success the EContact corresponding to `uid` is returned, otherwise `NULL` is returned if there was an error or if no contact was found for `uid` .

Since: 3.2

### e_book_backend_sqlitedb_get_vcard_string ()

    gchar *
    e_book_backend_sqlitedb_get_vcard_string
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    const gchar *uid,
                                    GHashTable *fields_of_interest,
                                    gboolean *with_all_required_fields,
                                    GError **error);

`e_book_backend_sqlitedb_get_vcard_string` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Searches `ebsdb` in the context of `folderid` for `uid` .

If `ebsdb` is configured to store the whole vcards, the whole vcard will be returned. Otherwise the summary cache will be searched and the virtual vcard will be built from the summary cache.

In either case, `with_all_required_fields` if specified, will be updated to reflect whether the returned vcard string satisfies the passed 'fields_of_interest' parameter.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | The folder id |
uid | The uid to fetch a vcard for |
fields_of_interest | The required fields for this vcard, or `NULL` to require all fields. |
with_all_required_fields | Whether all the required fields are present in the returned vcard. | [allow-none][out]
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

The vcard string for `uid` or `NULL` if `uid` was not found.

[transfer full]

Since: 3.2

### e_book_backend_sqlitedb_search ()

    GSList *
    e_book_backend_sqlitedb_search (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    const gchar *sexp,
                                    GHashTable *fields_of_interest,
                                    gboolean *searched,
                                    gboolean *with_all_required_fields,
                                    GError **error);

`e_book_backend_sqlitedb_search` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Searching with summary fields is always supported. Search expressions containing any other field is supported only if backend chooses to store the vcard inside the db.

If not configured otherwise, the default summary fields include: uid, rev, file_as, nickname, full_name, given_name, family_name, email, is_list, list_show_addresses, wants_html.

Summary fields can be configured at addressbook creation time using the ESourceBackendSummarySetup source extension.

The `fields_of_interest` parameter is a legacy parameter which can be used to specify that EContacts with only the `E_CONTACT_UID` and `E_CONTACT_REV` fields. The hash table must use `g_str_hash()` and `g_str_equal()` and the keys 'uid' and 'rev' must be present.

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
sexp | search expression; use `NULL` or an empty string to get all stored contacts. | [allow-none]
fields_of_interest | A GHashTable indicating which fields should be included in the returned contacts. | [allow-none]
searched | Whether `ebsdb` was capable of searching for the provided query `sexp` . | [allow-none][out]
with_all_required_fields | Whether all the required fields are present in the returned vcards. | [allow-none][out]
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

A GSList of EbSdbSearchData structures.

[transfer full]

Since: 3.2

### e_book_backend_sqlitedb_search_uids ()

    GSList *
    e_book_backend_sqlitedb_search_uids (EBookBackendSqliteDB *ebsdb,
                                         const gchar *folderid,
                                         const gchar *sexp,
                                         gboolean *searched,
                                         GError **error);

`e_book_backend_sqlitedb_search_uids` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Similar to `e_book_backend_sqlitedb_search()`, but returns only a list of contact UIDs.

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
sexp | search expression; use `NULL` or an empty string to get all stored contacts. | [allow-none]
searched | Whether `ebsdb` was capable of searching for the provided query `sexp` . | [allow-none][out]
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

A GSList of allocated contact UID strings.

[transfer full]

Since: 3.2

### e_book_backend_sqlitedb_get_uids_and_rev ()

    GHashTable *
    e_book_backend_sqlitedb_get_uids_and_rev
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    GError **error);

`e_book_backend_sqlitedb_get_uids_and_rev` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Gets hash table of all uids (key) and rev (value) pairs stored for each contact in the cache. The hash table should be freed with `g_hash_table_destroy()`, if not needed anymore. Each key and value is a newly allocated string.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

A GHashTable of all contact revisions by UID.

[transfer full]

Since: 3.4

### e_book_backend_sqlitedb_get_is_populated ()

    gboolean
    e_book_backend_sqlitedb_get_is_populated
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    GError **error);

`e_book_backend_sqlitedb_get_is_populated` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Checks whether the 'is populated' flag is set for `folderid` in `ebsdb` .

In order to differentiate an error from the flag simply being `FALSE` for `ebsdb`, you must pass the `error` parameter and check whether it was set by this function.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

Whether the 'is populated' flag is set.

Since: 3.2

### e_book_backend_sqlitedb_set_is_populated ()

    gboolean
    e_book_backend_sqlitedb_set_is_populated
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    gboolean populated,
                                    GError **error);

`e_book_backend_sqlitedb_set_is_populated` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Sets the value of the 'is populated' flag for `folderid` in `ebsdb` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
populated | The new value for the 'is populated' flag. |
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.2

### e_book_backend_sqlitedb_get_revision ()

    gboolean
    e_book_backend_sqlitedb_get_revision (EBookBackendSqliteDB *ebsdb,
                                          const gchar *folderid,
                                          gchar **revision_out,
                                          GError **error);

`e_book_backend_sqlitedb_get_revision` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Fetches the current revision for the address-book indicated by `folderid` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
revision_out | The location to return the current revision. | [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.8

### e_book_backend_sqlitedb_set_revision ()

    gboolean
    e_book_backend_sqlitedb_set_revision (EBookBackendSqliteDB *ebsdb,
                                          const gchar *folderid,
                                          const gchar *revision,
                                          GError **error);

`e_book_backend_sqlitedb_set_revision` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Sets the current revision for the address-book indicated by `folderid` to be `revision` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
revision | The new revision |
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.8

### e_book_backend_sqlitedb_get_sync_data ()

    gchar *
    e_book_backend_sqlitedb_get_sync_data (EBookBackendSqliteDB *ebsdb,
                                           const gchar *folderid,
                                           GError **error);

`e_book_backend_sqlitedb_get_sync_data` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Fetches data previously set with `e_book_backend_sqlitedb_set_sync_data()` for the given `folderid` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

The data previously set with `e_book_backend_sqlitedb_set_sync_data()`.

[transfer full]

Since: 3.2

### e_book_backend_sqlitedb_set_sync_data ()

    gboolean
    e_book_backend_sqlitedb_set_sync_data (EBookBackendSqliteDB *ebsdb,
                                           const gchar *folderid,
                                           const gchar *sync_data,
                                           GError **error);

`e_book_backend_sqlitedb_set_sync_data` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Sets some auxiliary data for the given `folderid` in `ebsdb` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
sync_data | The data to set. |
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.2

### e_book_backend_sqlitedb_get_key_value ()

    gchar *
    e_book_backend_sqlitedb_get_key_value (EBookBackendSqliteDB *ebsdb,
                                           const gchar *folderid,
                                           const gchar *key,
                                           GError **error);

`e_book_backend_sqlitedb_get_key_value` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Fetches data previously set with `e_book_backend_sqlitedb_set_key_value()` for the given `key` in `folderid` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
key | the key to fetch a value for |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

The data previously set with `e_book_backend_sqlitedb_set_key_value()`.

[transfer full]

Since: 3.2

### e_book_backend_sqlitedb_set_key_value ()

    gboolean
    e_book_backend_sqlitedb_set_key_value (EBookBackendSqliteDB *ebsdb,
                                           const gchar *folderid,
                                           const gchar *key,
                                           const gchar *value,
                                           GError **error);

`e_book_backend_sqlitedb_set_key_value` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Sets the auxiliary data `value` to be stored in relation to `key` in `folderid` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
key | the key to fetch a value for |
value | the value to story for `key` in `folderid` |
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.2

### e_book_backend_sqlitedb_get_contact_bdata ()

    gchar *
    e_book_backend_sqlitedb_get_contact_bdata
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    const gchar *uid,
                                    GError **error);

`e_book_backend_sqlitedb_get_contact_bdata` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Fetches extra auxiliary data previously set for `uid` .

In order to differentiate an error from the `uid` simply not being present in `ebsdb`, you must pass the `error` parameter and check whether it was set by this function.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
uid | The UID of the contact to fetch extra data for. |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

The extra data previously set for `uid` , or `NULL`.

[transfer full]

Since: 3.2

### e_book_backend_sqlitedb_set_contact_bdata ()

    gboolean
    e_book_backend_sqlitedb_set_contact_bdata
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    const gchar *uid,
                                    const gchar *value,
                                    GError **error);

`e_book_backend_sqlitedb_set_contact_bdata` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Sets the extra auxiliary data for the contact indicated by `uid` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
uid | The UID of the contact to fetch extra data for. |
value | The auxiliary data to set for `uid` in `folderid` . |
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.2

### e_book_backend_sqlitedb_get_has_partial_content ()

    gboolean
    e_book_backend_sqlitedb_get_has_partial_content
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    GError **error);

`e_book_backend_sqlitedb_get_has_partial_content` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Fetches the 'partial content' flag from `folderid` in `ebsdb` .

This flag is intended to indicate whether the stored vcards contain the full data or whether they were downloaded only partially.

In order to differentiate an error from the flag simply being `FALSE` for `ebsdb`, you must pass the `error` parameter and check whether it was set by this function.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

`TRUE` if the vcards stored in the db were downloaded partially.

Since: 3.2

### e_book_backend_sqlitedb_set_has_partial_content ()

    gboolean
    e_book_backend_sqlitedb_set_has_partial_content
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    gboolean partial_content,
                                    GError **error);

`e_book_backend_sqlitedb_set_has_partial_content` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Sets the value of the 'partial content' flag in `folderid` of `ebsdb` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
partial_content | new value for the 'partial content' flag |
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.2

### e_book_backend_sqlitedb_get_partially_cached_ids ()

    GSList *
    e_book_backend_sqlitedb_get_partially_cached_ids
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    GError **error);

`e_book_backend_sqlitedb_get_partially_cached_ids` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Obsolete, do not use, this always ends with an error.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

`NULL`

Since: 3.2

### e_book_backend_sqlitedb_delete_addressbook ()

    gboolean
    e_book_backend_sqlitedb_delete_addressbook
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *folderid,
                                    GError **error);

`e_book_backend_sqlitedb_delete_addressbook` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Deletes the addressbook indicated by `folderid` in `ebsdb` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
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.2

### e_book_backend_sqlitedb_remove ()

    gboolean
    e_book_backend_sqlitedb_remove (EBookBackendSqliteDB *ebsdb,
                                    GError **error);

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

Removes the entire `ebsdb` from storage on disk.

FIXME: it is unclear when it is safe to call this function, it should probably be deprecated.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
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.2

### e_book_backend_sqlitedb_search_data_free ()

    void
    e_book_backend_sqlitedb_search_data_free
                                   (EbSdbSearchData *s_data);

`e_book_backend_sqlitedb_search_data_free` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Frees an EbSdbSearchData

#### Parameters

s_data | An EbSdbSearchData |

Since: 3.2

### e_book_backend_sqlitedb_check_summary_query ()

    gboolean
    e_book_backend_sqlitedb_check_summary_query
                                   (EBookBackendSqliteDB *ebsdb,
                                    const gchar *query,
                                    gboolean *with_list_attrs);

`e_book_backend_sqlitedb_check_summary_query` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Checks whether `query` contains only checks for the summary fields configured in `ebsdb`

#### Parameters

ebsdb | An EBookBackendSqliteDB |
query | the query to check |
with_list_attrs | Return location to store whether the query touches upon list attributes |

#### Returns

`TRUE` if `query` contains only fields configured in the summary.

Since: 3.8

### e_book_backend_sqlitedb_check_summary_fields ()

    gboolean
    e_book_backend_sqlitedb_check_summary_fields
                                   (EBookBackendSqliteDB *ebsdb,
                                    GHashTable *fields_of_interest);

`e_book_backend_sqlitedb_check_summary_fields` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Checks if all the specified fields are part of the configured summary fields for `ebsdb`

The `fields_of_interest` parameter must use `g_str_hash()` and `g_str_equal()` and the keys in the hash table, specifying contact fields, should be derived using `e_contact_field_name()`.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
fields_of_interest | A GHashTable containing the fields of interest |

#### Returns

`TRUE` if the fields specified in `fields_of_interest` are configured in the summary.

Since: 3.8

### e_book_backend_sqlitedb_set_locale ()

    gboolean
    e_book_backend_sqlitedb_set_locale (EBookBackendSqliteDB *ebsdb,
                                        const gchar *folderid,
                                        const gchar *lc_collate,
                                        GError **error);

`e_book_backend_sqlitedb_set_locale` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
lc_collate | The new locale for the addressbook |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

Whether the new locale was successfully set.

Since: 3.12

### e_book_backend_sqlitedb_get_locale ()

    gboolean
    e_book_backend_sqlitedb_get_locale (EBookBackendSqliteDB *ebsdb,
                                        const gchar *folderid,
                                        gchar **locale_out,
                                        GError **error);

`e_book_backend_sqlitedb_get_locale` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Fetches the current locale setting for the address-book indicated by `folderid` .

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
locale_out | The location to return the current locale. | [out][transfer full]
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

Whether the locale was successfully fetched.

Since: 3.12

### e_book_backend_sqlitedb_cursor_new ()

    EbSdbCursor *
    e_book_backend_sqlitedb_cursor_new (EBookBackendSqliteDB *ebsdb,
                                        const gchar *folderid,
                                        const gchar *sexp,
                                        EContactField *sort_fields,
                                        EBookCursorSortType *sort_types,
                                        guint n_sort_fields,
                                        GError **error);

`e_book_backend_sqlitedb_cursor_new` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Creates a new EbSdbCursor.

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id of the address-book |
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 location to store any error that may have occurred. | [allow-none]

#### Returns

A newly created EbSdbCursor.

[transfer full]

Since: 3.12

### e_book_backend_sqlitedb_cursor_free ()

    void
    e_book_backend_sqlitedb_cursor_free (EBookBackendSqliteDB *ebsdb,
                                         EbSdbCursor *cursor);

`e_book_backend_sqlitedb_cursor_free` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Frees `cursor` .

#### Parameters

ebsdb | An EBookBackendSqliteDB |
cursor | The EbSdbCursor to free |

Since: 3.12

### e_book_backend_sqlitedb_cursor_step ()

    gint
    e_book_backend_sqlitedb_cursor_step (EBookBackendSqliteDB *ebsdb,
                                         EbSdbCursor *cursor,
                                         EbSdbCursorStepFlags flags,
                                         EbSdbCursorOrigin origin,
                                         gint count,
                                         GSList **results,
                                         GError **error);

`e_book_backend_sqlitedb_cursor_step` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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_SDB_ERROR_END_OF_LIST` error.

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
cursor | The EbSdbCursor to use |
flags | The EbSdbCursorStepFlags for this step |
origin | The EbSdbCursorOrigin 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 `EBSDB_CURSOR_STEP_FETCH` is not specified in `flags`. | [out][allow-none][element-type EbSdbSearchData][transfer full]
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

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

Since: 3.12

### e_book_backend_sqlitedb_cursor_set_target_alphabetic_index ()

    void
    e_book_backend_sqlitedb_cursor_set_target_alphabetic_index
                                   (EBookBackendSqliteDB *ebsdb,
                                    EbSdbCursor *cursor,
                                    gint index);

`e_book_backend_sqlitedb_cursor_set_target_alphabetic_index` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Sets the `cursor` position to an

Alphabetic Index

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

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
cursor | The EbSdbCursor to modify |
index | The alphabetic index |

Since: 3.12

### e_book_backend_sqlitedb_cursor_set_sexp ()

    gboolean
    e_book_backend_sqlitedb_cursor_set_sexp
                                   (EBookBackendSqliteDB *ebsdb,
                                    EbSdbCursor *cursor,
                                    const gchar *sexp,
                                    GError **error);

`e_book_backend_sqlitedb_cursor_set_sexp` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
cursor | The EbSdbCursor |
sexp | The new query expression for `cursor` |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

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

Since: 3.12

### e_book_backend_sqlitedb_cursor_calculate ()

    gboolean
    e_book_backend_sqlitedb_cursor_calculate
                                   (EBookBackendSqliteDB *ebsdb,
                                    EbSdbCursor *cursor,
                                    gint *total,
                                    gint *position,
                                    GError **error);

`e_book_backend_sqlitedb_cursor_calculate` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
cursor | The EbSdbCursor |
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]
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

Whether `total` and `position` were successfully calculated.

Since: 3.12

### e_book_backend_sqlitedb_cursor_compare_contact ()

    gint
    e_book_backend_sqlitedb_cursor_compare_contact
                                   (EBookBackendSqliteDB *ebsdb,
                                    EbSdbCursor *cursor,
                                    EContact *contact,
                                    gboolean *matches_sexp);

`e_book_backend_sqlitedb_cursor_compare_contact` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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

#### Parameters

ebsdb | An EBookBackendSqliteDB |
cursor | The EbSdbCursor |
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

### e_book_backend_sqlitedb_is_summary_query ()

    gboolean
    e_book_backend_sqlitedb_is_summary_query
                                   (const gchar *query);

`e_book_backend_sqlitedb_is_summary_query` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Checks whether the query contains only checks for the default summary fields

#### Parameters

query | the query to check |

#### Returns

`TRUE` if `query` contains only fields configured in the summary.

Since: 3.2

### e_book_backend_sqlitedb_is_summary_fields ()

    gboolean
    e_book_backend_sqlitedb_is_summary_fields
                                   (GHashTable *fields_of_interest);

`e_book_backend_sqlitedb_is_summary_fields` has been deprecated since version 3.8 and should not be used in newly-written code.

Use EBookSqlite instead

This only checks if all the fields are part of the default summary fields, not part of the configured summary fields.

#### Parameters

fields_of_interest | A hash table containing the fields of interest |

#### Returns

Whether all `fields_of_interest` are part of the default summary fields

Since: 3.2

### e_book_backend_sqlitedb_add_contact ()

    gboolean
    e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb,
                                         const gchar *folderid,
                                         EContact *contact,
                                         gboolean partial_content,
                                         GError **error);

`e_book_backend_sqlitedb_add_contact` has been deprecated since version 3.8 and should not be used in newly-written code.

Use EBookSqlite instead

This is a convenience wrapper for e_book_backend_sqlitedb_add_contacts, which is the preferred means to add multiple contacts when possible.

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id |
contact | EContact to be added |
partial_content | contact does not contain full information. Used when the backend cache's partial information for auto-completion. |
error | A location to store any error that may have occurred. | [allow-none]

#### Returns

TRUE on success.

Since: 3.2

### e_book_backend_sqlitedb_add_contacts ()

    gboolean
    e_book_backend_sqlitedb_add_contacts (EBookBackendSqliteDB *ebsdb,
                                          const gchar *folderid,
                                          GSList *contacts,
                                          gboolean partial_content,
                                          GError **error);

`e_book_backend_sqlitedb_add_contacts` has been deprecated since version 3.8 and should not be used in newly-written code.

Use EBookSqlite instead

#### Parameters

ebsdb | An EBookBackendSqliteDB |
folderid | folder id |
contacts | list of EContacts |
partial_content | contact does not contain full information. Used when the backend cache's partial information for auto-completion. |
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.2

## Types and Values

### E_BOOK_SDB_ERROR

    #define E_BOOK_SDB_ERROR (e_book_backend_sqlitedb_error_quark ())

`E_BOOK_SDB_ERROR` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Error domain for EBookBackendSqliteDB operations.

Since: 3.8

### enum EBookSDBError

`EBookSDBError` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Defines the types of possible errors reported by the EBookBackendSqliteDB

#### Members

E_BOOK_SDB_ERROR_CONSTRAINT | The error occurred due to an explicit constraint |
E_BOOK_SDB_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_SDB_ERROR_OTHER | Another error occurred |
E_BOOK_SDB_ERROR_NOT_SUPPORTED | A query was not supported |
E_BOOK_SDB_ERROR_INVALID_QUERY | A query was invalid. This can happen if the sexp could not be parsed or if a phone number query contained non-phonenumber input. |
E_BOOK_SDB_ERROR_END_OF_LIST | An attempt was made to fetch results past the end of a contact list |

### struct EBookBackendSqliteDB

    struct EBookBackendSqliteDB;

`EBookBackendSqliteDB` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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

Since: 3.2

### struct EBookBackendSqliteDBClass

    struct EBookBackendSqliteDBClass {
    };

`EBookBackendSqliteDBClass` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Class structure for the EBookBackendSqlite class.

### EbSdbSearchData

    typedef struct {
    	gchar *vcard;
    	gchar *uid;
    	gchar *bdata;
    } EbSdbSearchData;

`EbSdbSearchData` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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

The `bdata` parameter will contain any data previously set for the given contact with `e_book_backend_sqlitedb_set_contact_bdata()`.

These should be freed with `e_book_backend_sqlitedb_search_data_free()`.

#### Members

gchar *`vcard`; | The the vcard string |
gchar *`uid`; | The `E_CONTACT_UID` field of this contact |
gchar *`bdata`; | Extra data set for this contact. |

Since: 3.2

### enum EbSdbCursorOrigin

`EbSdbCursorOrigin` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

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

When an EbSdbCuror is created, the current position implied by `EBSDB_CURSOR_ORIGIN_CURRENT` is the same as `EBSDB_CURSOR_ORIGIN_BEGIN`.

#### Members

EBSDB_CURSOR_ORIGIN_CURRENT | The current cursor position |
EBSDB_CURSOR_ORIGIN_BEGIN | The beginning of the cursor results. |
EBSDB_CURSOR_ORIGIN_END | The ending of the cursor results. |

Since: 3.12

### enum EbSdbCursorStepFlags

`EbSdbCursorStepFlags` has been deprecated since version 3.12 and should not be used in newly-written code.

Use EBookSqlite instead

Defines the behaviour of `e_book_backend_sqlitedb_cursor_step()`.

#### Members

EBSDB_CURSOR_STEP_MOVE | The cursor position should be modified while stepping |
EBSDB_CURSOR_STEP_FETCH | Traversed contacts should be listed and returned while stepping. |

Since: 3.12

### EbSdbCursor

    typedef struct _EbSdbCursor EbSdbCursor;

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