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.

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.

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

Since: 3.12

e_book_sqlite_new ()

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

Creates a new EBookSqlite with the default summary configuration.

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

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

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

Since: 3.12

e_book_sqlite_new_full ()

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

Opens or creates a new addressbook at path .

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

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

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

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

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

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.

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

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

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.

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.

Since: 3.12

e_book_sqlite_ref_source ()

ESource *
e_book_sqlite_ref_source (EBookSqlite *ebsql);

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

Since: 3.16

e_book_sqlite_add_contact ()

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

e_book_sqlite_add_contacts ()

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

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 .

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 .

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 .

Since: 3.12

e_book_sqlite_get_contact ()

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

Fetch the EContact specified by uid in ebsql .

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

Since: 3.12

ebsql_get_contact_unlocked ()

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

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

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

Since: 3.16

e_book_sqlite_get_vcard ()

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

Fetch a vcard string for uid in ebsql .

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

Since: 3.12

ebsql_get_vcard_unlocked ()

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

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

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

Since: 3.16

e_book_sqlite_set_contact_extra ()

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

Sets or replaces the extra data associated with uid .

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.

Since: 3.12

ebsql_get_contact_extra_unlocked ()

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

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

Since: 3.16

e_book_sqlite_search ()

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

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

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

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

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

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

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

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

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.

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.

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

Since: 3.12

e_book_sqlite_cursor_free ()

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

Frees cursor .

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

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

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 .

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

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.

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 .

Since: 3.12

E_BOOK_SQLITE_ERROR

#define E_BOOK_SQLITE_ERROR (e_book_sqlite_error_quark ())

Error domain for EBookSqlite operations.

Since: 3.12

E_BOOK_SQL_SYNC_DATA_KEY

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

This key can be used with e_book_sqlite_get_key_value().

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

Since: 3.12

enum EbSqlChangeType

Indicates the type of change which occurred in a EbSqlChangeCallback

Since: 3.12

enum EBookSqliteError

Defines the types of possible errors reported by the EBookSqlite

enum EbSqlLockType

Indicates the type of lock requested in e_book_sqlite_lock()

enum EbSqlUnlockAction

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

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

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

Since: 3.12

struct EBookSqlite

struct EBookSqlite;

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

Since: 3.12

struct EBookSqliteClass

struct EBookSqliteClass {
};

Class structure for the EBookSqlite class.

Since: 3.12

enum EbSqlCursorOrigin

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

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

Since: 3.12

enum EbSqlCursorStepFlags

Defines the behaviour of e_book_sqlite_cursor_step().

Since: 3.12

EbSqlCursor

typedef struct _EbSqlCursor EbSqlCursor;

The “before-insert-contact” signal

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

Flags: Run Last

The “before-remove-contact” signal

gboolean
user_function (EBookSqlite *ebooksqlite,
               gpointer     arg1,
               gchar       *arg2,
               GObject     *arg3,
               gpointer     arg4,
               gpointer     user_data)

Flags: Run Last