EBookBackendSqliteDB

EBookBackendSqliteDB

Synopsis

struct              EBookBackendSqliteDB;
#define             E_BOOK_SDB_ERROR
enum                EBookSDBError;
                    EbSdbSearchData;
EBookBackendSqliteDB * e_book_backend_sqlitedb_new      (const gchar *path,
                                                         const gchar *emailid,
                                                         const gchar *folderid,
                                                         const gchar *folder_name,
                                                         gboolean store_vcard,
                                                         GError **error);
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);
gboolean            e_book_backend_sqlitedb_lock_updates
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_unlock_updates
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         gboolean do_commit,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_new_contact (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         EContact *contact,
                                                         gboolean replace_existing,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_new_contacts
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GSList *contacts,
                                                         gboolean replace_existing,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_remove_contact
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *uid,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_remove_contacts
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GSList *uids,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_has_contact (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *uid,
                                                         gboolean *partial_content,
                                                         GError **error);
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);
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);
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);
GSList *            e_book_backend_sqlitedb_search_uids (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *sexp,
                                                         gboolean *searched,
                                                         GError **error);
GHashTable *        e_book_backend_sqlitedb_get_uids_and_rev
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_get_is_populated
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_set_is_populated
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         gboolean populated,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_get_revision
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         gchar **revision_out,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_set_revision
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *revision,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_get_locale  (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         gchar **locale_out,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_set_locale  (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *lc_collate,
                                                         GError **error);
ECollator *         e_book_backend_sqlitedb_ref_collator
                                                        (EBookBackendSqliteDB *ebsdb);
gchar *             e_book_backend_sqlitedb_get_sync_data
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_set_sync_data
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *sync_data,
                                                         GError **error);
gchar *             e_book_backend_sqlitedb_get_key_value
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *key,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_set_key_value
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *key,
                                                         const gchar *value,
                                                         GError **error);
gchar *             e_book_backend_sqlitedb_get_contact_bdata
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *uid,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_set_contact_bdata
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *uid,
                                                         const gchar *value,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_get_has_partial_content
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_set_has_partial_content
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         gboolean partial_content,
                                                         GError **error);
GSList *            e_book_backend_sqlitedb_get_partially_cached_ids
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_delete_addressbook
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_remove      (EBookBackendSqliteDB *ebsdb,
                                                         GError **error);
void                e_book_backend_sqlitedb_search_data_free
                                                        (EbSdbSearchData *s_data);
gboolean            e_book_backend_sqlitedb_check_summary_query
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *query,
                                                         gboolean *with_list_attrs);
gboolean            e_book_backend_sqlitedb_check_summary_fields
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         GHashTable *fields_of_interest);
                    EbSdbCursor;
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);
void                e_book_backend_sqlitedb_cursor_free (EBookBackendSqliteDB *ebsdb,
                                                         EbSdbCursor *cursor);
enum                EbSdbCursorOrigin;
enum                EbSdbCursorStepFlags;
gint                e_book_backend_sqlitedb_cursor_step (EBookBackendSqliteDB *ebsdb,
                                                         EbSdbCursor *cursor,
                                                         EbSdbCursorStepFlags flags,
                                                         EbSdbCursorOrigin origin,
                                                         gint count,
                                                         GSList **results,
                                                         GError **error);
void                e_book_backend_sqlitedb_cursor_set_target_alphabetic_index
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         EbSdbCursor *cursor,
                                                         gint index);
gboolean            e_book_backend_sqlitedb_cursor_set_sexp
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         EbSdbCursor *cursor,
                                                         const gchar *sexp,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_cursor_calculate
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         EbSdbCursor *cursor,
                                                         gint *total,
                                                         gint *position,
                                                         GError **error);
gint                e_book_backend_sqlitedb_cursor_compare_contact
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         EbSdbCursor *cursor,
                                                         EContact *contact,
                                                         gboolean *matches_sexp);

gboolean            e_book_backend_sqlitedb_is_summary_query
                                                        (const gchar *query);
gboolean            e_book_backend_sqlitedb_is_summary_fields
                                                        (GHashTable *fields_of_interest);
gboolean            e_book_backend_sqlitedb_add_contact (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         EContact *contact,
                                                         gboolean partial_content,
                                                         GError **error);
gboolean            e_book_backend_sqlitedb_add_contacts
                                                        (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         GSList *contacts,
                                                         gboolean partial_content,
                                                         GError **error);

Object Hierarchy

  GObject
   +----EBookBackendSqliteDB

Description

Details

struct EBookBackendSqliteDB

struct EBookBackendSqliteDB;

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

Since 3.2


E_BOOK_SDB_ERROR

#define E_BOOK_SDB_ERROR (e_book_backend_sqlitedb_error_quark ())

Error domain for EBookBackendSqliteDB operations.

Since 3.8


enum EBookSDBError

typedef enum {
	E_BOOK_SDB_ERROR_CONSTRAINT,
	E_BOOK_SDB_ERROR_CONTACT_NOT_FOUND,
	E_BOOK_SDB_ERROR_OTHER,
	E_BOOK_SDB_ERROR_NOT_SUPPORTED,
	E_BOOK_SDB_ERROR_INVALID_QUERY,
	E_BOOK_SDB_ERROR_END_OF_LIST
} EBookSDBError;

Defines the types of possible errors reported by the EBookBackendSqliteDB

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

EbSdbSearchData

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

FIXME: Document me.

Since 3.2


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

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

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.

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

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

Note

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

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

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_unlock_updates ()

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

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

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.

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.

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

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.

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.

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

FIXME: Document me.

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

FIXME: Document me.

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

FIXME: Document me.

Note: The partial_content is unused here.

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

FIXME: Document me.

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

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.

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.

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

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.

Summary fields - uid, rev, nickname, given_name, family_name, file_as email_1, email_2, email_3, email_4, is_list, list_show_addresses, wants_html

If ebsdb was incapable of returning vcards with results that satisfy fields_of_interest, then with_all_required_fields will be updated to FALSE and only uid fields will be present in the returned vcards. This can be useful when a summary query succeeds and the returned list can be used to iterate and fetch for full required data from another persistance.

sexp :

search expression; use NULL or an empty string to get all stored contacts.

fields_of_interest :

a GHashTable containing the names of fields to return, or NULL for all. At the moment if this is non-null, the vcard will be populated with summary fields, else it would return the whole vcard if its stored in the db. [not implemented fully]

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]

Returns :

List of EbSdbSearchData.

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

FIXME: Document me.

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

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.

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

FIXME: Document me.

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

FIXME: Document me.

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

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

Upon success, revision_out will hold the returned revision, otherwise FALSE will be returned and error will be updated accordingly.

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

Returns :

Whether the revision was successfully fetched.

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

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

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

Returns :

Whether the revision was successfully set.

Since 3.8


e_book_backend_sqlitedb_get_locale ()

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

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.

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

Returns :

Whether the locale was successfully fetched.

Since 3.12


e_book_backend_sqlitedb_set_locale ()

gboolean            e_book_backend_sqlitedb_set_locale  (EBookBackendSqliteDB *ebsdb,
                                                         const gchar *folderid,
                                                         const gchar *lc_collate,
                                                         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.

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

Returns :

Whether the new locale was successfully set.

Since 3.12


e_book_backend_sqlitedb_ref_collator ()

ECollator *         e_book_backend_sqlitedb_ref_collator
                                                        (EBookBackendSqliteDB *ebsdb);

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.

ebsdb :

An EBookBackendSqliteDB

Returns :

A reference to the active collator. [transfer full]

e_book_backend_sqlitedb_get_sync_data ()

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

FIXME: Document me.

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

FIXME: Document me.

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

FIXME: Document me.

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

FIXME: Document me.

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

FIXME: Document me.

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

FIXME: Document me.

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

Returns :

TRUE if the vcards stored in the db were downloaded partially. It is to indicate the stored vcards does not contain the full data.

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

FIXME: Document me.

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

FIXME: Document me.

Note: Obsolete, do not use, it always ends with an error

Since 3.2


e_book_backend_sqlitedb_delete_addressbook ()

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

FIXME: Document me.

Since 3.2


e_book_backend_sqlitedb_remove ()

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

FIXME: Document me.

Since 3.2


e_book_backend_sqlitedb_search_data_free ()

void                e_book_backend_sqlitedb_search_data_free
                                                        (EbSdbSearchData *s_data);

FIXME: Document me.

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

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

ebsdb :

an EBookBackendSqliteDB

query :

the query to check

with_list_attrs :

Return location to store whether the query touches upon list attributes

Since 3.8


e_book_backend_sqlitedb_check_summary_fields ()

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

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

ebsdb :

An EBookBackendSqliteDB

fields_of_interest :

A hash table containing the fields of interest

Since 3.8


EbSdbCursor

typedef struct _EbSdbCursor EbSdbCursor;

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

Creates a new EbSdbCursor.

The cursor should be freed with e_book_backend_sqlitedb_cursor_free().

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 return location to store any error that might be reported.

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

Frees cursor.

ebsdb :

An EBookBackendSqliteDB

cursor :

The EbSdbCursor to free

Since 3.12


enum EbSdbCursorOrigin

typedef enum {
	EBSDB_CURSOR_ORIGIN_CURRENT = 0,
	EBSDB_CURSOR_ORIGIN_BEGIN,
	EBSDB_CURSOR_ORIGIN_END
} EbSdbCursorOrigin;

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.

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

typedef enum {
	EBSDB_CURSOR_STEP_MOVE  = (1 << 0),
	EBSDB_CURSOR_STEP_FETCH = (1 << 1)
} EbSdbCursorStepFlags;

Defines the behaviour of e_book_backend_sqlitedb_cursor_step().

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


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

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

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 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_backend_sqlitedb_cursor_set_target_alphabetic_index ()

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

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.

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

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

ebsdb :

An EBookBackendSqliteDB

cursor :

The EbSdbCursor

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

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.

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 return location to store any error that might be reported. [allow-none]

Returns :

Whether total and position were successfully calculated.

Since 3.12


e_book_backend_sqlitedb_cursor_compare_contact ()

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

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

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

Warning

e_book_backend_sqlitedb_is_summary_query has been deprecated since version 3.8 and should not be used in newly-written code. Use e_book_backend_sqlitedb_check_summary_query() instead

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

Since 3.2


e_book_backend_sqlitedb_is_summary_fields ()

gboolean            e_book_backend_sqlitedb_is_summary_fields
                                                        (GHashTable *fields_of_interest);

Warning

e_book_backend_sqlitedb_is_summary_fields has been deprecated since version 3.8 and should not be used in newly-written code. Use e_book_backend_sqlitedb_check_summary_fields() instead.

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

fields_of_interest :

A hash table containing the fields of interest

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

Warning

e_book_backend_sqlitedb_add_contact has been deprecated since version 3.8 and should not be used in newly-written code. Use e_book_backend_sqlitedb_new_contact() instead.

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

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.

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

Warning

e_book_backend_sqlitedb_add_contacts has been deprecated since version 3.8 and should not be used in newly-written code. Use e_book_backend_sqlitedb_new_contacts() instead.

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.

Returns :

TRUE on success.

Since 3.2