EDataBook.BookSqlite¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37), EDataServer.Extensible (3)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`new` (path, source, cancellable)
class	`new_full` (path, source, setup, vcard_callback, change_callback, user_data, cancellable)
class	`search_data_free` (data)
	`add_contact` (contact, extra, replace, cancellable)
	`add_contacts` (contacts, extra, replace, cancellable)
	`count_query` (sexp, cancellable)
	`dup_query_contacts` (sexp, sort_field, sort_type, n_offset, n_limit, out_contacts, cancellable)
	`dup_query_field` (summary_field, sexp, sort_field, sort_type, n_offset, n_limit, out_uids, out_values, cancellable)
	`dup_summary_field` (summary_field, uid, cancellable)
	`exec_` (sql_stmt, cancellable)
	`get_contact` (uid, meta_contact)
	`get_contact_extra` (uid)
	`get_key_value` (key)
	`get_key_value_int` (key)
	`get_locale` ()
	`get_vcard` (uid, meta_contact)
	`has_contact` (uid)
	`lock` (lock_type, cancellable)
	`ref_collator` ()
	`ref_source` ()
	`remove_contact` (uid, cancellable)
	`remove_contacts` (uids, cancellable)
	`search` (sexp, meta_contacts, cancellable)
	`search_uids` (sexp, cancellable)
	`select` (sql_stmt, func, user_data, cancellable)
	`set_contact_extra` (uid, extra)
	`set_key_value` (key, value)
	`set_key_value_int` (key, value)
	`set_locale` (lc_collate, cancellable)
	`unlock` (action)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_before_insert_contact` (db, contact, extra, replace, cancellable)
	`do_before_remove_contact` (db, contact_uid, cancellable)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`before-insert-contact`
`before-remove-contact`

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class EDataBook.BookSqlite(**kwargs)¶

Bases:: GObject.Object, EDataServer.Extensible
Abstract:: No
Structure:: EDataBook.BookSqliteClass

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

New in version 3.12.

classmethod error_quark()¶

Return type:: int

classmethod new(path, source, cancellable)¶

Parameters:

path (str) – location to load or create the new database
source (EDataServer.Source or None) – an optional EDataServer.Source, associated with the EDataBook.BookSqlite, or None
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

A reference to an EDataBook.BookSqlite

Return type:

EDataBook.BookSqlite

Creates a new EDataBook.BookSqlite with the default summary configuration.

The fields EBookContacts.ContactField.FULL_NAME and EBookContacts.ContactField.EMAIL are configured to respond extra quickly with the EBookContacts.BookIndexType.PREFIX index flag.

The fields EBookContacts.ContactField.FILE_AS, EBookContacts.ContactField.FAMILY_NAME and EBookContacts.ContactField.GIVEN_NAME are configured to perform well with the EDataBook.bSqlCursor interface, using the EBookContacts.BookIndexType.SORT_KEY index flag.

New in version 3.12.

classmethod new_full(path, source, setup, vcard_callback, change_callback, user_data, cancellable)¶

Parameters:

path (str) – location to load or create the new database
source (EDataServer.Source or None) – an optional EDataServer.Source, associated with the EDataBook.BookSqlite, or None
setup (EBookContacts.SourceBackendSummarySetup or None) – an EBookContacts.SourceBackendSummarySetup describing how the summary should be setup, or None to use the default
vcard_callback (EDataBook.bSqlVCardCallback or None) – A function to resolve vcards
change_callback (EDataBook.bSqlChangeCallback or None) – A function to catch notifications of vcard changes
user_data (object or None) – callback user data
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

The newly created EDataBook.BookSqlite, or None if opening or creating the addressbook failed.

Return type:

EDataBook.BookSqlite

Opens or creates a new addressbook at path.

Like EDataBook.BookSqlite.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 EBookContacts.ContactField.UID and EBookContacts.ContactField.REV are not optional, they will be stored in the summary regardless of this function’s parameters. Only EBookContacts.ContactFields with the type GObject.TYPE_STRING, GObject.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 EDataBook.BookSqlite 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 None 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 EDataBook.BookSqlite addressbook if at all possible, however in some cases the vcards must be stored in some other storage.

New in version 3.12.

classmethod search_data_free(data)¶

Parameters:: data (EDataBook.bSqlSearchData) – An EDataBook.bSqlSearchData

Frees an EDataBook.bSqlSearchData

New in version 3.12.

add_contact(contact, extra, replace, cancellable)¶

Parameters:

contact (EBookContacts.Contact) –
extra (str) –
replace (bool) –
cancellable (Gio.Cancellable or None) –

Raises:

GLib.Error

Return type:

bool

add_contacts(contacts, extra, replace, cancellable)¶

Parameters:

contacts ([EBookContacts.Contact]) – A list of contacts to add to self
extra ([str] or None) – A list of extra data to store in association with this contact
replace (bool) – Whether this contact should replace another contact with the same UID.
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

Return type:

bool

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

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

New in version 3.12.

count_query(sexp, cancellable)¶

Parameters:

sexp (str or None) – search expression; use None or an empty string to consider all stored contacts
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

Whether succeeded.

out_n_total:: return location to store the count of the contacts

Return type:

(bool, out_n_total: int)

Counts how many contacts satisfy the sexp.

New in version 3.50.

dup_query_contacts(sexp, sort_field, sort_type, n_offset, n_limit, out_contacts, cancellable)¶

Parameters:

sexp (str or None) – search expression; use None or an empty string to consider all stored contacts
sort_field (EBookContacts.ContactField) – a field to sort by, which should be in the summary
sort_type (EBookContacts.BookCursorSortType) – an EBookContacts.BookCursorSortType
n_offset (int) – a 0-based offset in the sorted result to start reading from, or 0 to read from start
n_limit (int) – how many values to return only; use 0 or GObject.G_MAXUINT to read everything from the n_offset
out_contacts ([EBookContacts.Contact]) – an array of EBookContacts.Contact-s in the requested order
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Queries the self for the contacts in the given range and order. The sort_field should be in the summary, otherwise an error is returned.

Free the out_contacts with g_ptr_aray_unref(), when no longer needed.

New in version 3.50.

dup_query_field(summary_field, sexp, sort_field, sort_type, n_offset, n_limit, out_uids, out_values, cancellable)¶

Parameters:

summary_field (EBookContacts.ContactField) – a field to query, which should be in the summary
sexp (str or None) – search expression; use None or an empty string to consider all stored contacts
sort_field (EBookContacts.ContactField) – a field to sort by, which should be in the summary
sort_type (EBookContacts.BookCursorSortType) – an EBookContacts.BookCursorSortType
n_offset (int) – a 0-based offset in the sorted result to start reading from, or 0 to read from start
n_limit (int) – how many values to return only; use 0 or GObject.G_MAXUINT to read everything from the n_offset
out_uids ([str]) – contact UID-s in the requested order
out_values ([str]) – summary_field values in the requested order
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Queries the self for a summary_field value for contacts in the given range and order. To get complete contacts use EDataBook.BookSqlite.dup_query_contacts(). Note the field value may not correspond precisely to the value stored in the vCard (it can be in lower case).

Both summary_field and sort_field should be in the summary, otherwise an error is returned.

The out_uids and out_values will have the same number of elements, the indexes corresponding to each other. Free the arrays with g_ptr_aray_unref(), when no longer needed.

New in version 3.50.

dup_summary_field(summary_field, uid, cancellable)¶

Parameters:

summary_field (EBookContacts.ContactField) – a field to query, which should be in the summary
uid (str) – a contact UID to query the summary_field for
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

Whether succeeded.

out_value:: summary_field value

Return type:

(bool, out_value: str)

Queries the self for a summary_field value for contact with UID uid. Note the field value may not correspond precisely to the value stored in the vCard (it can be in lower case).

Free the out_value with GLib.free(), when no longer needed.

New in version 3.50.

exec_(sql_stmt, cancellable)¶

Parameters:

sql_stmt (str) – an SQLite statement to execute
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Executes an SQLite statement. Use EDataBook.BookSqlite.select() for SELECT statements.

New in version 3.48.

get_contact(uid, meta_contact)¶

Parameters:

uid (str) – The uid of the contact to fetch
meta_contact (bool) – Whether an entire contact is desired, or only the metadata

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

ret_contact:: Return location to store the fetched contact

Return type:

(bool, ret_contact: EBookContacts.Contact)

Fetch the EBookContacts.Contact specified by uid in self.

If meta_contact is specified, then a shallow EBookContacts.Contact will be created holding only the EBookContacts.ContactField.UID and EBookContacts.ContactField.REV fields.

New in version 3.12.

get_contact_extra(uid)¶

Parameters:

uid (str) – The uid of the contact to fetch the extra data for

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

ret_extra:: Return location to store the extra data

Return type:

(bool, ret_extra: str)

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

New in version 3.12.

get_key_value(key)¶

Parameters:

key (str) – The key to fetch a value for

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

value:: A return location to store the value for key

Return type:

(bool, value: str)

Fetches the value for key and stores it in value

New in version 3.12.

get_key_value_int(key)¶

Parameters:

key (str) – The key to fetch a value for

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

value:: A return location to store the value for key

Return type:

(bool, value: int)

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

New in version 3.12.

get_locale()¶

Raises:

GLib.Error

Returns:

Whether the locale was successfully fetched.

locale_out:: The location to return the current locale

Return type:

(bool, locale_out: str)

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.

New in version 3.12.

get_vcard(uid, meta_contact)¶

Parameters:

uid (str) – The uid of the contact to fetch
meta_contact (bool) – Whether an entire contact is desired, or only the metadata

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

ret_vcard:: Return location to store the fetched vcard string

Return type:

(bool, ret_vcard: str)

Fetch a vcard string for uid in self.

If meta_contact is specified, then a shallow vcard representation will be created holding only the EBookContacts.ContactField.UID and EBookContacts.ContactField.REV fields.

New in version 3.12.

has_contact(uid)¶

Parameters:

uid (str) – The uid of the contact to check for

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

exists:: Return location to store whether the contact exists.

Return type:

(bool, exists: bool)

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

New in version 3.12.

lock(lock_type, cancellable)¶

Parameters:

lock_type (EDataBook.bSqlLockType) – The EDataBook.bSqlLockType to acquire
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

Return type:

bool

Obtains an exclusive lock on self and starts a transaction.

This should be called if you need to access self multiple times while ensuring an atomic transaction. End this transaction with EDataBook.BookSqlite.unlock().

If cancellable is specified, then self will retain a reference to it until EDataBook.BookSqlite.unlock() is called. Any accesses to self with the lock held are expected to have the same cancellable specified, or None.

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

New in version 3.12.

ref_collator()¶

Returns:: A reference to the active collator.
Return type:: EDataServer.Collator

References the currently active EDataServer.Collator for self, use EDataServer.Collator.unref() when finished using the returned collator.

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

New in version 3.12.

ref_source()¶

Returns:: A reference to the EDataServer.Source to which self is paired, or None.
Return type:: EDataServer.Source or None

References the EDataServer.Source to which self is paired, use GObject.Object.unref() when finished using the source. It can be None in some cases, like when running tests.

New in version 3.16.

remove_contact(uid, cancellable)¶

Parameters:

uid (str) – the uid of the contact to remove
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

Return type:

bool

Removes the contact indicated by uid from self.

New in version 3.12.

remove_contacts(uids, cancellable)¶

Parameters:

uids ([str]) – a GLib.SList of uids indicating which contacts to remove
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

Return type:

bool

Removes the contacts indicated by uids from self.

New in version 3.12.

search(sexp, meta_contacts, cancellable)¶

Parameters:

sexp (str or None) – search expression; use None or an empty string to list all stored contacts.
meta_contacts (bool) – Whether entire contacts are desired, or only the metadata
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

ret_list:: Return location to store a GLib.SList of EDataBook.bSqlSearchData structures

Return type:

(bool, ret_list: [EDataBook.bSqlSearchData])

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

When sexp refers only to EBookContacts.ContactFields configured in the summary of self, the search should always be quick, when searching for other EBookContacts.ContactFields a fallback will be used, possibly invoking any EDataBook.bSqlVCardCallback which may have been passed to EDataBook.BookSqlite.new_full().

The returned ret_list list should be freed with g_slist_free() and all elements freed with EDataBook.BookSqlite.search_data_free().

If meta_contact is specified, then shallow vcard representations will be created holding only the EBookContacts.ContactField.UID and EBookContacts.ContactField.REV fields.

New in version 3.12.

search_uids(sexp, cancellable)¶

Parameters:

sexp (str or None) – search expression; use None or an empty string to get all stored contacts.
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

ret_list:: Return location to store a GLib.SList of contact uids

Return type:

(bool, ret_list: [str])

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

New in version 3.12.

select(sql_stmt, func, user_data, cancellable)¶

Parameters:

sql_stmt (str) – an SQLite SELECT statement to execute
func (EDataBook.BookSqliteSelectFunc) – an EDataBook.BookSqliteSelectFunc function to call for each row
user_data (object or None) – user data for func
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

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

New in version 3.48.

set_contact_extra(uid, extra)¶

Parameters:

uid (str) – The uid of the contact to set the extra data for
extra (str or None) – The extra data to set

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

Return type:

bool

Sets or replaces the extra data associated with uid.

New in version 3.12.

set_key_value(key, value)¶

Parameters:

key (str) – The key to fetch a value for
value (str) – The new value for key

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

Return type:

bool

Sets the value for key to be value

New in version 3.12.

set_key_value_int(key, value)¶

Parameters:

key (str) – The key to fetch a value for
value (int) – The new value for key

Raises:

GLib.Error

Returns:

True on success, otherwise False is returned and error is set appropriately.

Return type:

bool

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

New in version 3.12.

set_locale(lc_collate, cancellable)¶

Parameters:

lc_collate (str) – The new locale for the addressbook
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

Whether the new locale was successfully set.

Return type:

bool

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 EDataBook.bSqlVCardCallback provided to EDataBook.BookSqlite.new_full().

New in version 3.12.

unlock(action)¶

Parameters:: action (EDataBook.bSqlUnlockAction) – Which EDataBook.bSqlUnlockAction to take while unlocking
Raises:: GLib.Error
Returns:: True on success, otherwise False is returned and error is set appropriately.
Return type:: bool