EDataBook.BookCache

g EBackend.Cache EBackend.Cache EDataBook.BookCache EDataBook.BookCache EBackend.Cache->EDataBook.BookCache EDataServer.Extensible EDataServer.Extensible EDataServer.Extensible->EDataBook.BookCache GObject.GInterface GObject.GInterface GObject.GInterface->EDataServer.Extensible GObject.Object GObject.Object GObject.Object->EBackend.Cache

Subclasses:

None

Methods

Inherited:

EBackend.Cache (39), GObject.Object (37), EDataServer.Extensible (3)

Structs:

GObject.ObjectClass (5)

class

new (filename, source, cancellable)

class

new_full (filename, source, setup, cancellable)

contains_email (email_address, cancellable)

count_query (sexp, 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_categories ()

dup_contact_revision (contact)

dup_locale ()

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)

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_categories_changed (categories)

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

categories-changed

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

contains_email(email_address, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True when found the email_address, False on failure

Return type:

bool

Checks whether contains an email_address. When the email_address contains multiple addresses, then returns True when at least one address exists in the cache.

If an error occurs, the function will set error and return False.

New in version 3.44.

count_query(sexp, cancellable)
Parameters:
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.

cursor_calculate(cursor, cancellable)
Parameters:
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:
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:
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:

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:
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_categories()
Returns:

a comma-separated list of categories used by the contacts stored in the self, or None, when no category is used by any contact.

Return type:

str or None

Returns a comma-separated list of categories used by the contacts stored in the self. Free the returned string with GLib.free(), when no longer needed.

New in version 3.48.

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.

dup_query_contacts(sexp, sort_field, sort_type, n_offset, n_limit, out_contacts, cancellable)
Parameters:
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:
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.BookCache.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:
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.

get_contact(uid, meta_contact, cancellable)
Parameters:
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:
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:
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:
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:
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:
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:
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 or None

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:
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:
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:
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:
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:
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:
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:
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_categories_changed(categories) virtual
Parameters:

categories (str) –

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:

Signal Details

EDataBook.BookCache.signals.categories_changed(book_cache, object)
Signal Name:

categories-changed

Flags:

RUN_LAST, ACTION

Parameters:
EDataBook.BookCache.signals.dup_contact_revision(book_cache, object)
Signal Name:

dup-contact-revision

Flags:

RUN_LAST, ACTION

Parameters:
Return type:

str

EDataBook.BookCache.signals.e164_changed(book_cache, object, p0)
Signal Name:

e164-changed

Flags:

RUN_LAST

Parameters:

Property Details

EDataBook.BookCache.props.locale
Name:

locale

Type:

str

Default Value:

None

Flags:

READABLE

The locale currently being used