EDataBook.BookCache

Subclasses:None

Methods

Inherited:EBackend.Cache (39), GObject.Object (37), EDataServer.Extensible (2) Structs:GObject.ObjectClass (5)

class	new (filename, source, cancellable)
class	new_full (filename, source, setup, cancellable)
	cursor_calculate (cursor, cancellable)
	cursor_compare_contact (cursor, contact)
	cursor_free (cursor)
	cursor_set_sexp (cursor, sexp)
	cursor_set_target_alphabetic_index (cursor, idx)
	cursor_step (cursor, flags, origin, count, cancellable)
	dup_contact_revision (contact)
	dup_locale ()
	get_contact (uid, meta_contact, cancellable)
	get_contact_custom_flags (uid, cancellable)
	get_contact_extra (uid, cancellable)
	get_uids_with_extra (extra, cancellable)
	get_vcard (uid, meta_contact, cancellable)
	put_contact (contact, extra, custom_flags, offline_flag, cancellable)
	put_contacts (contacts, extras, custom_flags, offline_flag, cancellable)
	ref_collator ()
	ref_source ()
	remove_contact (uid, custom_flags, offline_flag, cancellable)
	remove_contacts (uids, custom_flags, offline_flag, cancellable)
	search (sexp, meta_contacts, cancellable)
	search_uids (sexp, cancellable)
	search_with_callback (sexp, func, user_data, cancellable)
	set_contact_custom_flags (uid, custom_flags, cancellable)
	set_contact_extra (uid, extra, cancellable)
	set_locale (lc_collate, cancellable)

Virtual Methods

Inherited:EBackend.Cache (7), GObject.Object (7)

	do_dup_contact_revision (contact)
	do_e164_changed (contact, is_replace)

Properties

Name	Type	Flags	Short Description
locale	str	r	The locale currently being used

Signals

Inherited:EBackend.Cache (3), GObject.Object (1)

Name	Short Description
dup-contact-revision
e164-changed

Fields

Inherited:EBackend.Cache (3), GObject.Object (1)

Name	Type	Access	Description
parent	EBackend.Cache	r

Class Details

class EDataBook.BookCache(**kwargs)

Bases:EBackend.Cache, EDataServer.Extensible Abstract:No Structure:EDataBook.BookCacheClass

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

New in version 3.26.

classmethod new(filename, source, cancellable)

Parameters:

• filename (str) – file name to load or create the new cache
• source (EDataServer.Source or None) – an optional EDataServer.Source, associated with the EDataBook.BookCache, or None
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

A new EDataBook.BookCache or None on error

Return type:

EDataBook.BookCache or None

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

Aside from the mandatory fields EBookContacts.ContactField.UID, EBookContacts.ContactField.REV, the default configuration stores the following fields for quick performance of searches: EBookContacts.ContactField.FILE_AS, EBookContacts.ContactField.NICKNAME, EBookContacts.ContactField.FULL_NAME, EBookContacts.ContactField.GIVEN_NAME, EBookContacts.ContactField.FAMILY_NAME, EBookContacts.ContactField.EMAIL, EBookContacts.ContactField.TEL, EBookContacts.ContactField.IS_LIST, EBookContacts.ContactField.LIST_SHOW_ADDRESSES, and EBookContacts.ContactField.WANTS_HTML.

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.BookCacheCursor, using the EBookContacts.BookIndexType.SORT_KEY index flag.

New in version 3.26.

classmethod new_full(filename, source, setup, cancellable)

Parameters:

• filename (str) – file name to load or create the new cache
• source (EDataServer.Source or None) – an optional EDataServer.Source, associated with the EDataBook.BookCache, or None
• setup (EBookContacts.SourceBackendSummarySetup or None) – an EBookContacts.SourceBackendSummarySetup describing how the summary should be setup, or None to use the default
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

A new EDataBook.BookCache or None on error

Return type:

EDataBook.BookCache or None

Creates a new EDataBook.BookCache with the given or the default summary configuration.

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.

New in version 3.26.

cursor_calculate(cursor, cancellable)

Parameters:

• cursor (EDataBook.BookCacheCursor) – The EDataBook.BookCacheCursor
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether out_total and out_position were successfully calculated.

out_total:A return location to store the total result set for this cursor out_position:A return location to store the cursor position

Return type:

(bool, out_total: int, out_position: int)

Calculates the out_total amount of results for the cursor’s query expression, as well as the current out_position of cursor in the results. The out_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.

New in version 3.26.

cursor_compare_contact(cursor, contact)

Parameters:

• cursor (EDataBook.BookCacheCursor) – The EDataBook.BookCacheCursor
• contact (EBookContacts.Contact) – The EBookContacts.Contact to compare

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.

out_matches_sexp:  Whether the contact matches the cursor’s search expression

Return type:

(int, out_matches_sexp: bool)

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

New in version 3.26.

cursor_free(cursor)

Parameters:cursor (EDataBook.BookCacheCursor) – The EDataBook.BookCacheCursor to free

Frees the cursor, previously allocated with EDataBook.BookCacheCursor.new().

New in version 3.26.

cursor_set_sexp(cursor, sexp)

Parameters:

• cursor (EDataBook.BookCacheCursor) – The EDataBook.BookCacheCursor to modify
• sexp (str) – The new query expression for cursor

Raises:

GLib.Error

Returns:

True if the expression was valid and accepted by cursor

Return type:

bool

Modifies the current query expression for cursor. This will not modify cursor’s state, but will change the outcome of any further calls to EDataBook.BookCache.cursor_step() or EDataBook.BookCache.cursor_calculate().

New in version 3.26.

cursor_set_target_alphabetic_index(cursor, idx)

Parameters:

• cursor (EDataBook.BookCacheCursor) – The EDataBook.BookCacheCursor to modify
• idx (int) – The alphabetic index

Sets the cursor position to an

‘Alphabetic Index [cursor-alphabet]’ into the alphabet active in self’s locale.

After setting the target to an alphabetic index, for example the index for letter ‘E’, then further calls to EDataBook.BookCache.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 EDataServer.Collator APIs.

Use EDataBook.BookCache.ref_collator() to obtain the active collator for self.

New in version 3.26.

cursor_step(cursor, flags, origin, count, cancellable)

Parameters:

• cursor (EDataBook.BookCacheCursor) – The EDataBook.BookCacheCursor to use
• flags (EDataBook.BookCacheCursorStepFlags) – The EDataBook.BookCacheCursorStepFlags for this step
• origin (EDataBook.BookCacheCursorOrigin) – The EDataBook.BookCacheCursorOrigin from whence to step
• count (int) – A positive or negative amount of contacts to try and fetch
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

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

out_results:A return location to store the results, or None if EDataBook.BookCacheCursorStepFlags.FETCH is not specified in flags.

Return type:

(int, out_results: [EDataBook.BookCacheSearchData])

Steps cursor through its 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 EBackend.CacheError.END_OF_LIST error.

If EDataBook.BookCacheCursorStepFlags.FETCH is specified in flags, a pointer to a None GLib.SList pointer should be provided for the out_results parameter.

The result list will be stored to out_results and should be freed with g_slist_free_full (results, EDataBook.BookCacheSearchData.free); when no longer needed.

New in version 3.26.

dup_contact_revision(contact)

Parameters:contact (EBookContacts.Contact) – an EBookContacts.Contact Returns:A newly allocated string containing revision of the contact. Return type:str

Returns the contact revision, used to detect changes. The returned string should be freed with GLib.free(), when no longer needed.

New in version 3.26.

dup_locale()

Returns:A new string containing the current local being used by the self. Free it with GLib.free(), when no longer needed. Return type:str

New in version 3.26.

get_contact(uid, meta_contact, cancellable)

Parameters:

• uid (str) – The uid of the contact to fetch
• meta_contact (bool) – Whether an entire contact is desired, or only the metadata
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

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

out_contact:Return location to store the fetched contact

Return type:

(bool, out_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.26.

get_contact_custom_flags(uid, cancellable)

Parameters:

• uid (str) – The uid of the contact to set the extra data for
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_custom_flags:  return location to store the custom flags

Return type:

(bool, out_custom_flags: int)

Gets the custom flags previously set for the uid, either with EDataBook.BookCache.set_contact_custom_flags(), when adding contacts or when removing contacts in offline.

New in version 3.34.

get_contact_extra(uid, cancellable)

Parameters:

• uid (str) – The uid of the contact to fetch the extra data for
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

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

out_extra:Return location to store the extra data

Return type:

(bool, out_extra: str)

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

New in version 3.26.

get_uids_with_extra(extra, cancellable)

Parameters:

• extra (str) – an extra column value to search for
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_uids:return location to store the UIDs to

Return type:

(bool, out_uids: [str])

Gets all the UID-s the extra data is set for.

The out_uids should be freed with g_slist_free_full (uids, GLib.free); when no longer needed.

New in version 3.26.

get_vcard(uid, meta_contact, cancellable)

Parameters:

• uid (str) – The uid of the contact to fetch
• meta_contact (bool) – Whether an entire contact is desired, or only the metadata
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

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

out_vcard:Return location to store the fetched vCard string

Return type:

(bool, out_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.26.

put_contact(contact, extra, custom_flags, offline_flag, cancellable)

Parameters:

• contact (EBookContacts.Contact) – an EBookContacts.Contact to be added
• extra (str or None) – extra data to store in association with this contact
• custom_flags (int) – custom flags for the contact, not interpreted by the self
• offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether putting this contact in offline
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

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

Return type:

bool

This is a convenience wrapper for EDataBook.BookCache.put_contacts(), which is the preferred way to add or modify multiple contacts when possible.

New in version 3.26.

put_contacts(contacts, extras, custom_flags, offline_flag, cancellable)

Parameters:

• contacts ([EBookContacts.Contact]) – A list of contacts to add to self
• extras ([str] or None) – A list of extra data to store in association with the contacts
• custom_flags ([int] or None) – optional custom flags to use for the contacts
• offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether putting these contacts in offline
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

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 extras is specified, it must have an equal length as the contacts list. Similarly the non-None custom_flags length should be the same as the length of the contacts. Each element from the extras list and custom_flags list will be stored in association with its corresponding contact in the contacts list.

New in version 3.26.

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.26.

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 no longer needed. It can be None in some cases, like when running tests.

New in version 3.26.

remove_contact(uid, custom_flags, offline_flag, cancellable)

Parameters:

• uid (str) – the uid of the contact to remove
• custom_flags (int) – custom flags for the contact with the given uid, not interpreted by the self
• offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether removing this contact in offline
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

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

Return type:

bool

Removes the contact identified by uid from self.

New in version 3.26.

remove_contacts(uids, custom_flags, offline_flag, cancellable)

Parameters:

• uids ([str]) – a GLib.SList of uids indicating which contacts to remove
• custom_flags ([int] or None) – an optional GLib.SList of custom flags for the ids
• offline_flag (EBackend.CacheOfflineFlag) – one of EBackend.CacheOfflineFlag, whether removing these contacts in offline
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

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. The custom_flags is used, if not None, only if the offline_flag is EBackend.CacheOfflineFlag.IS_OFFLINE. Otherwise it’s ignored. The length of the custom_flags should match the length of uids, when not None.

New in version 3.26.

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) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

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

out_list:Return location to store a GLib.SList of EDataBook.BookCacheSearchData structures

Return type:

(bool, out_list: [EDataBook.BookCacheSearchData])

Searches self for contacts matching the search expression 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.

The returned out_list list should be freed with g_slist_free_full (list, EDataBook.BookCacheSearchData.free) when no longer needed.

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.26.

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) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

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

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

Return type:

(bool, out_list: [str])

Similar to EDataBook.BookCache.search(), but fetches only a list of contact UIDs.

The returned out_list list should be freed with g_slist_free_full(list, GLib.free) when no longer needed.

New in version 3.26.

search_with_callback(sexp, func, user_data, cancellable)

Parameters:

• sexp (str or None) – search expression; use None or an empty string to get all stored contacts
• func (EDataBook.BookCacheSearchFunc or None) – an EDataBook.BookCacheSearchFunc callback to call for each found 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:

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

Return type:

bool

Similar to EDataBook.BookCache.search(), but calls the func for each found contact.

New in version 3.26.

set_contact_custom_flags(uid, custom_flags, cancellable)

Parameters:

• uid (str) – The uid of the contact to set the extra data for
• custom_flags (int) – the custom flags to set for the contact
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Sets or replaces the custom flags associated with a contact identified by the uid.

New in version 3.34.

set_contact_extra(uid, extra, cancellable)

Parameters:

• uid (str) – The uid of the contact to set the extra data for
• extra (str or None) – The extra data to set
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

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.26.

set_locale(lc_collate, cancellable)

Parameters:

• lc_collate (str) – The new locale for the cache
• cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

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 cache, changing the locale will store the new locale and will modify sort keys and any locale specific data in the cache.

As a side effect, it’s possible that changing the locale will cause stored vCard-s to change.

New in version 3.26.

do_dup_contact_revision(contact) virtual

Parameters:contact (EBookContacts.Contact) – an EBookContacts.Contact Returns:A newly allocated string containing revision of the contact. Return type:str

Returns the contact revision, used to detect changes. The returned string should be freed with GLib.free(), when no longer needed.

New in version 3.26.

do_e164_changed(contact, is_replace) virtual

Parameters:

• contact (EBookContacts.Contact) –
• is_replace (bool) –

Signal Details

EDataBook.BookCache.signals.dup_contact_revision(book_cache, object)

Signal Name:

dup-contact-revision

Flags:

RUN_LAST, ACTION

Parameters:

• book_cache (EDataBook.BookCache) – The object which received the signal
• object (EBookContacts.Contact) –

Return type:

str

EDataBook.BookCache.signals.e164_changed(book_cache, object, p0)

Signal Name:

e164-changed

Flags:

RUN_LAST

Parameters:

• book_cache (EDataBook.BookCache) – The object which received the signal
• object (EBookContacts.Contact) –
• p0 (bool) –

Property Details

EDataBook.BookCache.props.locale

Name:locale Type:str Default Value:None Flags:READABLE

The locale currently being used