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) – 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 it’s 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)

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 it’s result list

Return type: (bool, total: int, position: int)

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)

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`

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`

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 it’s 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