EBookSqlite

EBookSqlite — An SQLite storage facility for addressbooks

Synopsis

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

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

Description

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

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

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

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

Details

E_BOOK_SQLITE_ERROR

#define E_BOOK_SQLITE_ERROR (e_book_sqlite_error_quark ())

Error domain for EBookSqlite operations.

Since 3.12


enum EbSqlChangeType

typedef enum {
	EBSQL_CHANGE_CONTACT_ADDED,
	EBSQL_CHANGE_LOCALE_CHANGED,
	EBSQL_CHANGE_LAST
} EbSqlChangeType;

Indicates the type of change which occurred in a EbSqlChangeCallback

EBSQL_CHANGE_CONTACT_ADDED

Contact was modified as a result of it's addition to the addressbook

EBSQL_CHANGE_LOCALE_CHANGED

Contact was modified as a result of a locale change

EBSQL_CHANGE_LAST

A symbolic end marker for this enumeration, will not be passed in callbacks.

Since 3.12


EbSqlChangeCallback ()

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

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

Note

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

change_type :

The EbSqlChangeType which occurred

uid :

A contact UID

extra :

The extra data associated to the contact

vcard :

The vcard string for this UID

user_data :

Pointer to user provided data

Since 3.12


EbSqlVCardCallback ()

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

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

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

Note

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

uid :

A contact UID

extra :

The extra data associated to the contact

user_data :

User data previously passed to e_book_sqlite_new()

Returns :

The appropriate vcard indicated by uid. [transfer full]

Since 3.12


enum EBookSqliteError

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

Defines the types of possible errors reported by the EBookSqlite

E_BOOK_SQLITE_ERROR_ENGINE

An error was reported from the SQLite engine

E_BOOK_SQLITE_ERROR_CONSTRAINT

The error occurred due to an explicit constraint, this will happen when attempting to add two contacts with the same UID.

E_BOOK_SQLITE_ERROR_CONTACT_NOT_FOUND

A contact was not found by UID (this is different from a query that returns no results, which is not an error).

E_BOOK_SQLITE_ERROR_INVALID_QUERY

A query was invalid. This can happen if the search expression could not be parsed or if a phone number query contained non-phonenumber input.

E_BOOK_SQLITE_ERROR_UNSUPPORTED_QUERY

A query was not supported

E_BOOK_SQLITE_ERROR_UNSUPPORTED_FIELD

An unsupported EContactField was specified in the summary

E_BOOK_SQLITE_ERROR_END_OF_LIST

An attempt was made to fetch results past the end of a contact list

E_BOOK_SQLITE_ERROR_LOAD

An error occured while loading or creating the database

enum EbSqlLockType

typedef enum {
	EBSQL_LOCK_READ,
	EBSQL_LOCK_WRITE
} EbSqlLockType;

Indicates the type of lock requested in e_book_sqlite_lock()

EBSQL_LOCK_READ

Obtain a lock for reading

EBSQL_LOCK_WRITE

Obtain a lock for writing

enum EbSqlUnlockAction

typedef enum {
	EBSQL_UNLOCK_NONE,
	EBSQL_UNLOCK_COMMIT,
	EBSQL_UNLOCK_ROLLBACK
} EbSqlUnlockAction;

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

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

EBSQL_UNLOCK_NONE

Just unlock, this is appropriate for locks which were obtained with EBSQL_LOCK_READ

EBSQL_UNLOCK_COMMIT

Commit any modifications which were made while the lock was held

EBSQL_UNLOCK_ROLLBACK

Rollback any modifications which were made while the lock was held

EbSqlSearchData

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

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

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

These should be freed with e_book_sqlite_search_data_free().

gchar *uid;

The E_CONTACT_UID field of this contact

gchar *vcard;

The the vcard string

gchar *extra;

Any extra data associated to the vcard

Since 3.12


struct EBookSqlite

struct EBookSqlite {
};

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

Since 3.12


struct EBookSqliteClass

struct EBookSqliteClass {
};

Class structure for the EBookSqlite class.

Since 3.12


enum EbSqlCursorOrigin

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

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

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

EBSQL_CURSOR_ORIGIN_CURRENT

The current cursor position

EBSQL_CURSOR_ORIGIN_BEGIN

The beginning of the cursor results.

EBSQL_CURSOR_ORIGIN_END

The ending of the cursor results.

Since 3.12


enum EbSqlCursorStepFlags

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

Defines the behaviour of e_book_sqlite_cursor_step().

EBSQL_CURSOR_STEP_MOVE

The cursor position should be modified while stepping

EBSQL_CURSOR_STEP_FETCH

Traversed contacts should be listed and returned while stepping.

Since 3.12


e_book_sqlite_error_quark ()

GQuark              e_book_sqlite_error_quark           (void);

e_book_sqlite_search_data_free ()

void                e_book_sqlite_search_data_free      (EbSqlSearchData *data);

Frees an EbSqlSearchData

data :

An EbSqlSearchData

Since 3.12


e_book_sqlite_new ()

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

Creates a new EBookSqlite with the default summary configuration.

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

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

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

path :

location to load or create the new database

cancellable :

A GCancellable. [allow-none]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

A reference to a EBookSqlite. [transfer full]

Since 3.12


e_book_sqlite_new_full ()

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

Opens or creates a new addressbook at path.

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

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

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

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

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

path :

location to load or create the new database

setup :

an ESourceBackendSummarySetup describing how the summary should be setup, or NULL to use the default. [allow-none]

vcard_callback :

A function to resolve vcards. [allow-none][scope async][closure user_data]

change_callback :

A function to catch notifications of vcard changes. [allow-none][scope async][closure user_data]

user_data :

callback user data. [allow-none]

user_data_destroy :

A function to free user_data automatically when the created EBookSqlite is destroyed. [allow-none]

cancellable :

A GCancellable. [allow-none]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

The newly created EBookSqlite, or NULL if opening or creating the addressbook failed. [transfer full]

Since 3.12


e_book_sqlite_lock ()

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

Obtains an exclusive lock on ebsql and starts a transaction.

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

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

Note

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

ebsql :

An EBookSqlite

lock_type :

The EbSqlLockType to acquire

cancellable :

A GCancellable. [allow-none]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_unlock ()

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

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

Note

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

ebsql :

An EBookSqlite

action :

Which EbSqlUnlockAction to take while unlocking

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_set_locale ()

gboolean            e_book_sqlite_set_locale            (EBookSqlite *ebsql,
                                                         const gchar *lc_collate,
                                                         GCancellable *cancellable,
                                                         GError **error);

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

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

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

ebsql :

An EBookSqlite

lc_collate :

The new locale for the addressbook

cancellable :

A GCancellable. [allow-none]

error :

A location to store any error that may have occurred

Returns :

Whether the new locale was successfully set.

Since 3.12


e_book_sqlite_get_locale ()

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

Fetches the current locale setting for the address-book.

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

ebsql :

An EBookSqlite

locale_out :

The location to return the current locale. [out][transfer full]

error :

A location to store any error that may have occurred

Returns :

Whether the locale was successfully fetched.

Since 3.12


e_book_sqlite_ref_collator ()

ECollator *         e_book_sqlite_ref_collator          (EBookSqlite *ebsql);

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

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

ebsql :

An EBookSqlite

Returns :

A reference to the active collator. [transfer full]

Since 3.12


e_book_sqlite_add_contact ()

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

e_book_sqlite_add_contacts ()

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

e_book_sqlite_remove_contact ()

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

Removes the contact indicated by uid from ebsql.

ebsql :

An EBookSqlite

uid :

the uid of the contact to remove

cancellable :

A GCancellable. [allow-none]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_remove_contacts ()

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

Removes the contacts indicated by uids from ebsql.

ebsql :

An EBookSqlite

uids :

a GSList of uids indicating which contacts to remove

cancellable :

A GCancellable. [allow-none]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_has_contact ()

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

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

ebsql :

An EBookSqlite

uid :

The uid of the contact to check for

exists :

Return location to store whether the contact exists. [out]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_get_contact ()

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

Fetch the EContact specified by uid in ebsql.

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

ebsql :

An EBookSqlite

uid :

The uid of the contact to fetch

meta_contact :

Whether an entire contact is desired, or only the metadata

ret_contact :

Return location to store the fetched contact. [out][transfer full]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_get_vcard ()

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

Fetch a vcard string for uid in ebsql.

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

ebsql :

An EBookSqlite

uid :

The uid of the contact to fetch

meta_contact :

Whether an entire contact is desired, or only the metadata

ret_vcard :

Return location to store the fetched vcard string. [out][transfer full]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_set_contact_extra ()

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

Sets or replaces the extra data associated with uid.

ebsql :

An EBookSqlite

uid :

The uid of the contact to set the extra data for

extra :

The extra data to set. [allow-none]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_get_contact_extra ()

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

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

ebsql :

An EBookSqlite

uid :

The uid of the contact to fetch the extra data for

ret_extra :

Return location to store the extra data. [out][transfer full]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_search ()

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

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

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

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

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

ebsql :

An EBookSqlite

sexp :

search expression; use NULL or an empty string to list all stored contacts. [allow-none]

meta_contacts :

Whether entire contacts are desired, or only the metadata

ret_list :

Return location to store a GSList of EbSqlSearchData structures. [out][transfer full][element-type EbSqlSearchData]

cancellable :

A GCancellable. [allow-none]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_search_uids ()

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

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

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

ebsql :

An EBookSqlite

sexp :

search expression; use NULL or an empty string to get all stored contacts. [allow-none]

ret_list :

Return location to store a GSList of contact uids. [out][transfer full]

cancellable :

A GCancellable. [allow-none]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_get_key_value ()

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

Fetches the value for key and stores it in value

ebsql :

An EBookSqlite

key :

The key to fetch a value for

value :

A return location to store the value for key. [out][transfer full]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_set_key_value ()

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

Sets the value for key to be value

ebsql :

An EBookSqlite

key :

The key to fetch a value for

value :

The new value for key

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_get_key_value_int ()

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

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

ebsql :

An EBookSqlite

key :

The key to fetch a value for

value :

A return location to store the value for key. [out]

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_set_key_value_int ()

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

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

ebsql :

An EBookSqlite

key :

The key to fetch a value for

value :

The new value for key

error :

A location to store any error that may have occurred. [allow-none]

Returns :

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

Since 3.12


e_book_sqlite_cursor_new ()

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

Creates a new EbSqlCursor.

The cursor should be freed with e_book_sqlite_cursor_free().

ebsql :

An EBookSqlite

sexp :

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

sort_fields :

An array of EContactFields as sort keys in order of priority. [array length=n_sort_fields]

sort_types :

An array of EBookCursorSortTypes, one for each field in sort_fields. [array length=n_sort_fields]

n_sort_fields :

The number of fields to sort results by.

error :

A return location to store any error that might be reported.

Returns :

A newly created EbSqlCursor. [transfer full]

Since 3.12


e_book_sqlite_cursor_free ()

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

Frees cursor.

ebsql :

An EBookSqlite

cursor :

The EbSqlCursor to free

Since 3.12


e_book_sqlite_cursor_step ()

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

Steps cursor through it's sorted query by a maximum of count contacts starting from origin.

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

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

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

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

ebsql :

An EBookSqlite

cursor :

The EbSqlCursor to use

flags :

The EbSqlCursorStepFlags for this step

origin :

The EbSqlCursorOrigin from whence to step

count :

A positive or negative amount of contacts to try and fetch

results :

A return location to store the results, or NULL if EBSQL_CURSOR_STEP_FETCH is not specified in flags. [out][allow-none][element-type EbSqlSearchData][transfer full]

cancellable :

A GCancellable. [allow-none]

error :

A return location to store any error that might be reported.

Returns :

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

Since 3.12


e_book_sqlite_cursor_set_target_alphabetic_index ()

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

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

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

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

Use e_book_sqlite_ref_collator() to obtain the active collator for ebsql.

ebsql :

An EBookSqlite

cursor :

The EbSqlCursor to modify

idx :

The alphabetic index

Since 3.12


e_book_sqlite_cursor_set_sexp ()

gboolean            e_book_sqlite_cursor_set_sexp       (EBookSqlite *ebsql,
                                                         EbSqlCursor *cursor,
                                                         const gchar *sexp,
                                                         GError **error);

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

ebsql :

An EBookSqlite

cursor :

The EbSqlCursor

sexp :

The new query expression for cursor

error :

A return location to store any error that might be reported.

Returns :

TRUE if the expression was valid and accepted by ebsql

Since 3.12


e_book_sqlite_cursor_calculate ()

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

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

ebsql :

An EBookSqlite

cursor :

The EbSqlCursor

total :

A return location to store the total result set for this cursor. [out][allow-none]

position :

A return location to store the total results before the cursor value. [out][allow-none]

cancellable :

A GCancellable. [allow-none]

error :

A return location to store any error that might be reported. [allow-none]

Returns :

Whether total and position were successfully calculated.

Since 3.12


e_book_sqlite_cursor_compare_contact ()

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

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

ebsql :

An EBookSqlite

cursor :

The EbSqlCursor

contact :

The EContact to compare

matches_sexp :

Whether the contact matches the cursor's search expression. [out][allow-none]

Returns :

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

Since 3.12


EbSqlCursor

typedef struct _EbSqlCursor EbSqlCursor;