Callbacks

BookBackendCustomOpFunc (book_backend, user_data, cancellable)

BookBackendForeachViewFunc (backend, view, *user_data)

BookCacheSearchFunc (book_cache, uid, revision, object, extra, custom_flags, offline_state, *user_data)

BookSqliteSelectFunc (ebsql, column_names, column_values, *user_data)

DataBookCursorCompareContactFunc (cursor, contact)

DataBookCursorGetPositionFunc (cursor, cancellable)

DataBookCursorLoadLocaleFunc (cursor)

DataBookCursorSetAlphabetIndexFunc (cursor, index, locale)

DataBookCursorSetSexpFunc (cursor, sexp)

DataBookCursorStepFunc (cursor, revision_guard, flags, origin, count, cancellable)

bSqlChangeCallback (change_type, uid, extra, vcard, *user_data)

bSqlVCardCallback (uid, extra, *user_data)

Details

EDataBook.BookBackendCustomOpFunc(book_backend, user_data, cancellable)
Parameters:

A callback prototype being called in a dedicated thread, scheduled by EDataBook.BookBackend.schedule_custom_operation().

New in version 3.26.

EDataBook.BookBackendForeachViewFunc(backend, view, *user_data)
Parameters:
Returns:

True, to continue, False to stop further processing.

Return type:

bool

Callback function used by EDataBook.BookBackend.foreach_view().

New in version 3.34.

EDataBook.BookCacheSearchFunc(book_cache, uid, revision, object, extra, custom_flags, offline_state, *user_data)
Parameters:
Returns:

True to continue, False to stop walk through.

Return type:

bool

A callback called for each object row when using EDataBook.BookCache.search_with_callback() function.

New in version 3.26.

EDataBook.BookSqliteSelectFunc(ebsql, column_names, column_values, *user_data)
Parameters:
Returns:

True to continue, False to stop walk through.

Return type:

bool

A callback called for each row of a SELECT statement executed with EDataBook.BookSqlite.select() function.

New in version 3.48.

EDataBook.DataBookCursorCompareContactFunc(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.

matches_sexp:

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

Return type:

(int, matches_sexp: bool)

Method type for EDataBook.DataBookCursor.do_compare_contact()

Cursor implementations must implement this in order to compare a contact with the current cursor state.

This is called when the addressbook backends notify active cursors that the addressbook has been modified with EDataBook.DataBookCursor.contact_added() and EDataBook.DataBookCursor.contact_removed().

New in version 3.12.

EDataBook.DataBookCursorGetPositionFunc(cursor, cancellable)
Parameters:
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)

Method type for EDataBook.DataBookCursor.do_get_position()

Cursor implementations must implement this to count the total results matching cursor's query expression and to calculate the amount of contacts leading up to the current cursor state (cursor inclusive).

A cursor position is defined as an integer which is inclusive of the current contact to which it points (if the cursor points to an exact contact). A position of 0 indicates that the cursor is situated in a position that is before and after the entire result set. The cursor position should be 0 at creation time, and should start again from the symbolic 0 position whenever EBookContacts.BookCursorOrigin.BEGIN is specified in the EDataBook.DataBookCursor.do_step() method (or whenever moving the cursor beyond the end of the result set).

If the cursor is positioned beyond the end of the list, then the position should be the total amount of contacts available in the list (as returned through the total argument) plus one.

This method is called by EDataBook.DataBookCursor.recalculate() and in some other cases where cursor's current position and total must be recalculated from scratch.

New in version 3.12.

EDataBook.DataBookCursorLoadLocaleFunc(cursor)
Parameters:

cursor (EDataBook.DataBookCursor) – an EDataBook.DataBookCursor

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)

Method type for EDataBook.DataBookCursor.do_load_locale()

Fetches the locale setting from cursor's addressbook

If the locale setting has changed, the cursor must reload any internal locale specific data and ensure that comparisons of sort keys will function properly in the new locale.

Upon locale changes, the implementation need not worry about updating it’s current cursor state, the cursor state will be reset automatically for you.

New in version 3.12.

EDataBook.DataBookCursorSetAlphabetIndexFunc(cursor, index, locale)
Parameters:
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

Method type for EDataBook.DataBookCursor.do_set_alphabetic_index()

Sets the cursor state to point to an

‘index into the active alphabet [cursor-alphabet]’. The implementing class must check that locale matches the current locale setting of the underlying database and report an EDataServer.ClientError.OUT_OF_SYNC error in the case that the locales do not match.

New in version 3.12.

EDataBook.DataBookCursorSetSexpFunc(cursor, sexp)
Parameters:
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

Method type for EDataBook.DataBookCursor.do_set_sexp()

A cursor implementation must implement this in order to modify the search expression for cursor. After this is called, the position and total will be recalculated.

If the cursor implementation is unable to deal with the EBookContacts.ContactFields referred to in sexp, then an EDataServer.ClientError.INVALID_QUERY error should be set to indicate this.

New in version 3.12.

EDataBook.DataBookCursorStepFunc(cursor, revision_guard, flags, origin, count, cancellable)
Parameters:
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])

Method type for EDataBook.DataBookCursor.do_step()

As all cursor methods may be called either by the addressbook service or directly by a client in Direct Read Access mode, it is important that the operation be an atomic transaction with the underlying database.

The revision_guard, if specified, will be set to the EDataServer.CLIENT_BACKEND_PROPERTY_REVISION value at the time which the given client issued the call to move the cursor. If the revision_guard provided by the client does not match the stored addressbook revision, then an EDataServer.ClientError.OUT_OF_SYNC error should be set to indicate that the revision was out of sync while attempting to move the cursor.

If the addressbook backend supports direct read access, then the revision comparison and reading of the data store must be coupled into a single atomic operation (the data read back from the store must be the correct data for the given addressbook revision).

See EDataBook.DataBookCursor.step() for more details on the expected behaviour of this method.

New in version 3.12.

EDataBook.bSqlChangeCallback(change_type, uid, extra, vcard, *user_data)
Parameters:

A function which may be called in response to a change in contact data.

This user callback is called inside a lock, you must not call the EDataBook.BookSqlite API from this callback.

New in version 3.12.

EDataBook.bSqlVCardCallback(uid, extra, *user_data)
Parameters:
Returns:

The appropriate vcard indicated by uid

Return type:

str

If this callback is passed to EDataBook.BookSqlite.new(), then vcards are not stored in the SQLite and instead this callback is invoked to fetch the vcard.

This callback will be called to fetch results for fully indexed and optimized queries, and it will also be called while performing fallback queries against EBookContacts.ContactFields which are not configured in the EBookContacts.SourceBackendSummarySetup or default summary fields.

This user callback is called inside a lock, you must not call the EDataBook.BookSqlite API from this callback.

New in version 3.12.