EDataBook.DataBookCursor¶

Subclasses:: EDataBook.DataBookCursorCache, EDataBook.DataBookCursorSqlite

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

	`contact_added` (contact)
	`contact_removed` (contact)
	`get_backend` ()
	`get_position` ()
	`get_total` ()
	`load_locale` (cancellable)
	`recalculate` (cancellable)
	`register_gdbus_object` (connection, object_path)
	`set_alphabetic_index` (index, locale, cancellable)
	`set_sexp` (sexp, cancellable)
	`step` (revision_guard, flags, origin, count, cancellable)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_compare_contact` (contact)
	`do_get_position` (cancellable)
	`do_load_locale` ()
	`do_set_alphabetic_index` (index, locale)
	`do_set_sexp` (sexp)
	`do_step` (revision_guard, flags, origin, count, cancellable)

Properties¶

Name	Type	Flags	Short Description
`backend`	`EDataBook.BookBackend`	r/w/co	The backend which created this cursor
`position`	`int`	r	The current position of this cursor
`total`	`int`	r	The total results for this cursor

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class EDataBook.DataBookCursor(**kwargs)¶

Bases:: GObject.Object
Abstract:: Yes
Structure:: EDataBook.DataBookCursorClass

An opaque handle for an addressbook cursor

New in version 3.12.

contact_added(contact)¶

Parameters:: contact (EBookContacts.Contact) – the EBookContacts.Contact which was added to the addressbook

Should be called by addressbook backends whenever a contact is added.

New in version 3.12.

contact_removed(contact)¶

Parameters:: contact (EBookContacts.Contact) – the EBookContacts.Contact which was removed from the addressbook

Should be called by addressbook backends whenever a contact is removed.

New in version 3.12.

get_backend()¶

Returns:: The EDataBook.BookBackend owning self.
Return type:: EDataBook.BookBackend

Gets the backend which created and owns self.

New in version 3.12.

get_position()¶

Returns:: the current position of self
Return type:: int

Fetch the current position of self in its result list.

New in version 3.12.

get_total()¶

Returns:: the total contacts for self
Return type:: int

Fetch the total number of contacts which match self's query expression.

New in version 3.12.

load_locale(cancellable)¶

Parameters:

cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

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

locale:: return location for the locale

Return type:

(bool, locale: str)

Load the current locale setting from the cursor’s underlying database.

Addressbook backends implementing cursors should call this function on all active cursor when the locale setting changes.

This will implicitly reset self's state and position.

New in version 3.12.

recalculate(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – A Gio.Cancellable
Raises:: GLib.Error
Returns:: True on success, otherwise False is returned and error is set.
Return type:: bool

Recalculates the cursor’s total and position, this is meant for cursor created in Direct Read Access mode to synchronously recalculate the position and total values when the addressbook revision has changed.

New in version 3.12.

register_gdbus_object(connection, object_path)¶

Parameters:

connection (Gio.DBusConnection) – the Gio.DBusConnection to register with
object_path (str) – the object path to place the direct access configuration data

Raises:

GLib.Error

Returns:

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

Return type:

bool

Places self on the connection at object_path

New in version 3.12.

set_alphabetic_index(index, locale, cancellable)¶

Parameters:

index (int) – the alphabetic index
locale (str) – the locale in which index is expected to be a valid alphabetic index
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

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

Return type:

bool

Sets the self position to an

‘Alphabetic Index [cursor-alphabet]’ into the alphabet active in the locale of the addressbook.

After setting the target to an alphabetic index, for example the index for letter ‘E’, then further calls to EDataBook.DataBookCursor.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 locale, if by some chance the addressbook backend has changed into a new locale after this call has been issued, an EDataServer.ClientError.OUT_OF_SYNC error will be issued indicating that there was a locale mismatch.

New in version 3.12.

set_sexp(sexp, cancellable)¶

Parameters:

sexp (str or None) – the search expression to set
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

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

Return type:

bool

Sets the search expression for the cursor

New in version 3.12.

step(revision_guard, flags, origin, count, cancellable)¶

Parameters:

revision_guard (str or None) – The expected current addressbook revision, or None
flags (EBookContacts.BookCursorStepFlags) – The EBookContacts.BookCursorStepFlags for this step
origin (EBookContacts.BookCursorOrigin) – The EBookContacts.BookCursorOrigin from whence to step
count (int) – a positive or negative amount of contacts to try and fetch
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Raises:

GLib.Error

Returns:

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

results:: A return location to store the results, or None if EBookContacts.BookCursorStepFlags.FETCH is not specified in flags

Return type:

(int, results: [str])

Steps self 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 self 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 EDataServer.ClientError.QUERY_REFUSED error.

If EBookContacts.BookCursorStepFlags.FETCH is specified in flags, a pointer to a None GLib.SList 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 GLib.free().

If a revision_guard is specified, the cursor implementation will issue an EDataServer.ClientError.OUT_OF_SYNC error if the revision_guard does not match the current addressbook revision.

An explanation of how stepping is expected to behave can be found in the ‘user facing reference documentation [cursor-iteration]’.

New in version 3.12.

do_compare_contact(contact) virtual¶

Parameters:

contact (EBookContacts.Contact) – the EBookContacts.Contact to compare with cursor

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.

matches_sexp:: return location to set whether contact matched cursor's search expression

Return type:

(int, matches_sexp: bool)

The EDataBook.DataBookCursorCompareContactFunc delegate to compare an EBookContacts.Contact with the cursor position

do_get_position(cancellable) virtual¶

Parameters:

cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Returns:

True on Success, otherwise False is returned if any error occurred and error is set to reflect the error which occurred.

total:: The total number of contacts matching cursor's query expression
position:: The current position of cursor in its result list

Return type:

(bool, total: int, position: int)

The EDataBook.DataBookCursorGetPositionFunc delegate to calculate the current total and position values

do_load_locale() virtual¶

Returns:

True on Success, otherwise False is returned if any error occurred and error is set to reflect the error which occurred.

locale:: return location to store the newly loaded locale

Return type:

(bool, locale: str)

The EDataBook.DataBookCursorLoadLocaleFunc delegate used to reload the locale setting

do_set_alphabetic_index(index, locale) virtual¶

Parameters:

index (int) – the alphabetic index
locale (str) – the locale in which index is expected to be a valid alphabetic index

Returns:

True on Success, otherwise False is returned if any error occurred and error is set to reflect the error which occurred.

Return type:

bool

The EDataBook.DataBookCursorSetAlphabetIndexFunc delegate to set the alphabetic position

do_set_sexp(sexp) virtual¶

Parameters:: sexp (str or None) – the search expression to set, or None for unfiltered results
Returns:: True on Success, otherwise False is returned if any error occurred and error is set to reflect the error which occurred.
Return type:: bool

The EDataBook.DataBookCursorSetSexpFunc delegate to set the search expression

do_step(revision_guard, flags, origin, count, cancellable) virtual¶

Parameters:

revision_guard (str or None) – The expected current addressbook revision, or None
flags (EBookContacts.BookCursorStepFlags) – The EBookContacts.BookCursorStepFlags for this step
origin (EBookContacts.BookCursorOrigin) – The EBookContacts.BookCursorOrigin from whence to step
count (int) – a positive or negative amount of contacts to try and fetch
cancellable (Gio.Cancellable or None) – A Gio.Cancellable

Returns:

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

results:: A return location to store the results, or None if EBookContacts.BookCursorStepFlags.FETCH is not specified in flags

Return type:

(int, results: [str])

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 EDataServer.ClientError.QUERY_REFUSED error.

If EBookContacts.BookCursorStepFlags.FETCH is specified in flags, a pointer to a None GLib.SList 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 GLib.free().

If a revision_guard is specified, the cursor implementation will issue an EDataServer.ClientError.OUT_OF_SYNC error if the revision_guard does not match the current addressbook revision.

An explanation of how stepping is expected to behave can be found in the ‘user facing reference documentation [cursor-iteration]’.

New in version 3.12.

Property Details¶

EDataBook.DataBookCursor.props.backend¶

Name:: backend
Type:: EDataBook.BookBackend
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The backend which created this cursor

EDataBook.DataBookCursor.props.position¶

Name:: position
Type:: int
Default Value:: 0
Flags:: READABLE

The current position of this cursor

EDataBook.DataBookCursor.props.total¶

Name:: total
Type:: int
Default Value:: 0
Flags:: READABLE

The total results for this cursor