EDataBook.BookSqlite¶

Subclasses:	None

Methods¶

Inherited:	GObject.Object (37), EDataServer.Extensible (2)
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)
	`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)
	`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`) – 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 a `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`) – 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.

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`

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.

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`

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

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

New in version 3.12.

do_before_insert_contact(db, contact, extra, replace, cancellable) virtual¶

Parameters:	db (`object` or `None`) – contact (`EBookContacts.Contact`) – extra (`str`) – replace (`bool`) – cancellable (`Gio.Cancellable` or `None`) –
Return type:	`bool`

do_before_remove_contact(db, contact_uid, cancellable) virtual¶

Parameters:	db (`object` or `None`) – contact_uid (`str`) – cancellable (`Gio.Cancellable` or `None`) –
Return type:	`bool`

Signal Details¶

EDataBook.BookSqlite.signals.before_insert_contact(book_sqlite, object, p0, p1, p2, p3, p4)¶

Signal Name:	`before-insert-contact`
Flags:	`RUN_LAST`
Parameters:	book_sqlite (`EDataBook.BookSqlite`) – The object which received the signal object (`object` or `None`) – p0 (`EBookContacts.Contact`) – p1 (`str`) – p2 (`bool`) – p3 (`GObject.Object`) – p4 (`object` or `None`) –
Return type:	`bool`

EDataBook.BookSqlite.signals.before_remove_contact(book_sqlite, object, p0, p1, p2)¶

Signal Name:	`before-remove-contact`
Flags:	`RUN_LAST`
Parameters:	book_sqlite (`EDataBook.BookSqlite`) – The object which received the signal object (`object` or `None`) – p0 (`str`) – p1 (`Gio.Cancellable` or `None`) – p2 (`object` or `None`) –
Return type:	`bool`