EDataBook.BookBackend¶

Subclasses:: EDataBook.BookBackendSync

Methods¶

Inherited:: EBackend.Backend (21), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

	`add_view` (view)
	`configure_direct` (config)
	`contains_email` (email_address, cancellable, callback, *user_data)
	`contains_email_finish` (result)
	`contains_email_sync` (email_address, cancellable)
	`create_contacts` (vcards, opflags, cancellable, callback, *user_data)
	`create_contacts_finish` (result, out_contacts)
	`create_contacts_sync` (vcards, opflags, out_contacts, cancellable)
	`create_cursor` (sort_fields, sort_types, n_fields)
	`delete_cursor` (cursor)
	`dup_cache_dir` ()
	`dup_locale` ()
	`dup_view_contacts` (view_id, range_start, range_length)
	`dup_view_indices` (view_id)
	`dup_view_sort_fields` (view_id)
	`foreach_view` (func, *user_data)
	`foreach_view_notify_progress` (only_completed_views, percent, message)
	`get_backend_property` (prop_name)
	`get_cache_dir` ()
	`get_contact` (uid, cancellable, callback, *user_data)
	`get_contact_finish` (result)
	`get_contact_list` (query, cancellable, callback, *user_data)
	`get_contact_list_finish` (result, out_contacts)
	`get_contact_list_sync` (query, out_contacts, cancellable)
	`get_contact_list_uids` (query, cancellable, callback, *user_data)
	`get_contact_list_uids_finish` (result, out_uids)
	`get_contact_list_uids_sync` (query, out_uids, cancellable)
	`get_contact_sync` (uid, cancellable)
	`get_direct_book` ()
	`get_registry` ()
	`get_view_n_total` (view_id)
	`get_writable` ()
	`is_opened` ()
	`is_readonly` ()
	`list_views` ()
	`modify_contacts` (vcards, opflags, cancellable, callback, *user_data)
	`modify_contacts_finish` (result)
	`modify_contacts_sync` (vcards, opflags, cancellable)
	`notify_complete` ()
	`notify_error` (message)
	`notify_property_changed` (prop_name, prop_value)
	`notify_remove` (id)
	`notify_update` (contact)
	`open` (cancellable, callback, *user_data)
	`open_finish` (result)
	`open_sync` (cancellable)
	`prepare_for_completion` (opid)
	`ref_data_book` ()
	`ref_proxy_resolver` ()
	`ref_view` (view_id)
	`ref_view_user_data` (view_id)
	`refresh` (cancellable, callback, *user_data)
	`refresh_finish` (result)
	`refresh_sync` (cancellable)
	`remove_contacts` (uids, opflags, cancellable, callback, *user_data)
	`remove_contacts_finish` (result)
	`remove_contacts_sync` (uids, opflags, cancellable)
	`remove_view` (view)
	`schedule_custom_operation` (use_cancellable, func, *user_data)
	`set_cache_dir` (cache_dir)
	`set_data_book` (data_book)
	`set_locale` (locale, cancellable)
	`set_view_indices` (view_id, indices)
	`set_view_n_total` (view_id, n_total)
	`set_view_sort_fields` (view_id, fields)
	`set_writable` (writable)
	`start_view` (view)
	`stop_view` (view)
	`sync` ()
	`take_view_user_data` (view_id, user_data)

Virtual Methods¶

Inherited:: EBackend.Backend (3), GObject.Object (7)

	`do_closed` (sender)
	`do_impl_configure_direct` (config)
	`do_impl_contains_email` (book, opid, cancellable, email_address)
	`do_impl_create_contacts` (book, opid, cancellable, vcards, opflags)
	`do_impl_delete_cursor` (cursor)
	`do_impl_dup_locale` ()
	`do_impl_dup_view_indices` (view_id)
	`do_impl_get_backend_property` (prop_name)
	`do_impl_get_contact` (book, opid, cancellable, id)
	`do_impl_get_contact_list` (book, opid, cancellable, query)
	`do_impl_get_contact_list_uids` (book, opid, cancellable, query)
	`do_impl_get_view_n_total` (view_id)
	`do_impl_modify_contacts` (book, opid, cancellable, vcards, opflags)
	`do_impl_notify_update` (contact)
	`do_impl_open` (book, opid, cancellable)
	`do_impl_refresh` (book, opid, cancellable)
	`do_impl_remove_contacts` (book, opid, cancellable, uids, opflags)
	`do_impl_set_locale` (locale, cancellable)
	`do_impl_set_view_sort_fields` (view_id, fields)
	`do_impl_start_view` (view)
	`do_impl_stop_view` (view)
	`do_shutdown` ()

Properties¶

Inherited:: EBackend.Backend (5)

Name	Type	Flags	Short Description
`cache-dir`	`str`	r/w/en	The backend’s cache directory
`proxy-resolver`	`Gio.ProxyResolver`	r	The proxy resolver for this backend
`registry`	`EDataServer.SourceRegistry`	r/w/co	Data source registry
`writable`	`bool`	r/w/en	Whether the backend will accept changes

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`closed`	Emitted when a client destroys its #EBookClient for backend.
`shutdown`	Emitted when the last client destroys its #EBookClient for backend.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`EBackend.Backend`	r

Class Details¶

class EDataBook.BookBackend(**kwargs)¶

Bases:: EBackend.Backend
Abstract:: No
Structure:: EDataBook.BookBackendClass

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

add_view(view)¶

Parameters:: view (EDataBook.DataBookView) – an EDataBook.DataBookView

Adds view to self for querying.

configure_direct(config)¶

Parameters:: config (str) – The configuration string for the given backend

This method is called on self in direct read access mode. The config argument is the same configuration string which the same backend reported in the EDataBook.DataBookDirect returned by EDataBook.BookBackend.get_direct_book().

The configuration string is optional and is used to ensure that direct access backends are properly configured to interface with the same data as the running server side backend.

New in version 3.8.

contains_email(email_address, cancellable, callback, *user_data)¶

Parameters:

email_address (str) – an email address
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

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

When the operation is finished, callback will be called. You can then call EDataBook.BookBackend.contains_email_finish() to get the result of the operation.

New in version 3.44.

contains_email_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Finishes the operation started with EDataBook.BookBackend.contains_email().

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

New in version 3.44.

contains_email_sync(email_address, cancellable)¶

Parameters:

email_address (str) – an email address
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

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 address book.

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

New in version 3.44.

create_contacts(vcards, opflags, cancellable, callback, *user_data)¶

Parameters:

vcards (str) – a None-terminated array of vCard strings
opflags (int) – bit-or of EBookContacts.BookOperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously creates one or more new contacts from vcards.

When the operation is finished, callback will be called. You can then call EDataBook.BookBackend.create_contacts_finish() to get the result of the operation.

New in version 3.10.

create_contacts_finish(result, out_contacts)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult
out_contacts (GLib.Queue) – a GLib.Queue in which to deposit results

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Finishes the operation started with EDataBook.BookBackend.create_contacts().

An EBookContacts.Contact instance for each newly-created contact is deposited in out_contacts. The returned EBookContacts.Contact instances are referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with them.

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

New in version 3.10.

create_contacts_sync(vcards, opflags, out_contacts, cancellable)¶

Parameters:

vcards (str) – a None-terminated array of vCard strings
opflags (int) – bit-or of EBookContacts.BookOperationFlags
out_contacts (GLib.Queue) – a GLib.Queue in which to deposit results
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Creates one or more new contacts from vcards, and deposits an EBookContacts.Contact instance for each newly-created contact in out_contacts.

The returned EBookContacts.Contact instances are referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with them.

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

New in version 3.10.

create_cursor(sort_fields, sort_types, n_fields)¶

Parameters:

sort_fields (EBookContacts.ContactField) – the EBookContacts.ContactFields to sort by
sort_types (EBookContacts.BookCursorSortType) – the EBookContacts.BookCursorSortTypes for the sorted fields
n_fields (int) – the number of fields in the sort_fields and sort_types

Raises:

GLib.Error

Returns:

A newly created cursor, the cursor belongs to the backend and should not be unreffed, or None on error

Return type:

EDataBook.DataBookCursor

Creates a new EDataBook.DataBookCursor for the given backend if the backend has cursor support. If the backend does not support cursors then an EDataServer.ClientError.NOT_SUPPORTED error will be set in error.

Backends can also refuse to create cursors for some values of sort_fields and report more specific errors.

The returned cursor belongs to self and should be destroyed with EDataBook.BookBackend.delete_cursor() when no longer needed.

New in version 3.12.

delete_cursor(cursor)¶

Parameters:: cursor (EDataBook.DataBookCursor) – the EDataBook.DataBookCursor to destroy
Raises:: GLib.Error
Returns:: Whether cursor was successfully deleted.
Return type:: bool

Requests self to release and destroy cursor, this will trigger an EDataServer.ClientError.INVALID_ARG error if cursor is not owned by self.

New in version 3.12.

dup_cache_dir()¶

Returns:: a newly-allocated copy of EDataBook.BookBackend :cache-dir
Return type:: str

Thread-safe variation of EDataBook.BookBackend.get_cache_dir(). Use this function when accessing self from multiple threads.

The returned string should be freed with GLib.free() when no longer needed.

New in version 3.10.

dup_locale()¶

Returns:: A copy of the currently configured locale for the addressbook. Free with GLib.free() when done with it.
Return type:: str

Fetches a copy of the currently configured locale for the addressbook

New in version 3.12.

dup_view_contacts(view_id, range_start, range_length)¶

Parameters:

view_id (int) – a view identifier
range_start (int) – 0-based range start to retrieve the contacts for
range_length (int) – how many contacts to retrieve

Returns:

an array of the contacts, or None, when the view cannot be found or when the range_start is out of bounds.

Return type:

[EBookContacts.Contact] or None

Returns range_length contacts from 0-based index range_start in the view identified by the view_id. When there are asked more than EDataBook.BookBackend.get_view_n_total() contacts only those up to the total number of contacts are read. Asking for out of range contacts results in an error, though it can return less than range_length contacts.

The default implementation tracks the view’s content in memory and returns the contacts as needed. The subclasses can do more efficient implementation.

Note: This function should be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY views.

New in version 3.50.

dup_view_indices(view_id)¶

Parameters:: view_id (int) – a view identifier
Returns:: an array of EBookContacts.BookIndices, or None
Return type:: EBookContacts.BookIndices or None

Returns a list of EBookContacts.BookIndices holding indices of the contacts in the view identified by view_id. The array is terminated by an item with chr member being None.

The default implementation returns an array previously set by EDataBook.BookBackend.set_view_indices().

Free the returned array with e_book_indices_free(), when no longer needed.

Note: This function should be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY views.

New in version 3.50.

dup_view_sort_fields(view_id)¶

Parameters:: view_id (int) – a view identifier
Returns:: current sort fields for the view_id, as an EBookContacts.BookClientViewSortFields array, or None, when the view could not be found.
Return type:: EBookContacts.BookClientViewSortFields

Returns currently used sort fields for manual query views. The returned array is None only if the view could not be found. The default sort is by the file-as filed in ascending order.

The array is terminated by an item with an EBookContacts.ContactField.FIELD_LAST field.

Free the returned array with e_book_client_view_sort_fields_free(), when no longer needed.

Note: This function should be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY views.

New in version 3.50.

foreach_view(func, *user_data)¶

Parameters:

func (EDataBook.BookBackendForeachViewFunc or None) – an EDataBook.BookBackendForeachViewFunc function to call
user_data (object or None) – user data to pass to func

Returns:

whether the call had been stopped by func

Return type:

bool

Calls func for each existing view (as returned by EDataBook.BookBackend.list_views()). The func can return False to stop early.

New in version 3.34.

foreach_view_notify_progress(only_completed_views, percent, message)¶

Parameters:

only_completed_views (bool) – whether notify in completed views only
percent (int) – percent complete
message (str or None) – message describing the operation in progress, or None

Notifies each view of the self about progress. When only_completed_views is True, notifies only completed views.

New in version 3.34.

get_backend_property(prop_name)¶

Parameters:: prop_name (str) – a backend property name
Returns:: the value for prop_name
Return type:: str

Obtains the value of the backend property named prop_name. Freed the returned string with GLib.free() when finished with it.

New in version 3.10.

get_cache_dir()¶

Returns:: the cache directory path
Return type:: str

Returns the cache directory path used by self.

New in version 2.32.

get_contact(uid, cancellable, callback, *user_data)¶

Parameters:

uid (str) – a contact ID
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously obtains an EBookContacts.Contact for uid.

When the operation is finished, callback will be called. You can then call EDataBook.BookBackend.get_contact_finish() to get the result of the operation.

New in version 3.10.

get_contact_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: an EBookContacts.Contact, or None on error
Return type:: EBookContacts.Contact

Finishes the operation started with EDataBook.BookBackend.get_contact_finish().

The returned EBookContacts.Contact is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

If an error occurred, the function will set error and return None.

New in version 3.10.

get_contact_list(query, cancellable, callback, *user_data)¶

Parameters:

query (str) – a search query in S-expression format
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously obtains a set of EBookContacts.Contact instances which satisfy the criteria specified in query.

When the operation is finished, callback will be called. You can then call EDataBook.BookBackend.get_contact_list_finish() to get the result of the operation.

New in version 3.10.

get_contact_list_finish(result, out_contacts)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult
out_contacts (GLib.Queue) – a GLib.Queue in which to deposit results

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Finishes the operation started with EDataBook.BookBackend.get_contact_list().

The matching EBookContacts.Contact instances are deposited in out_contacts. The returned EBookContacts.Contact instances are referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with them.

If an error occurred, the function will set error and return False. Note that an empty result set does not necessarily imply an error.

New in version 3.10.

get_contact_list_sync(query, out_contacts, cancellable)¶

Parameters:

query (str) – a search query in S-expression format
out_contacts (GLib.Queue) – a GLib.Queue in which to deposit results
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Obtains a set of EBookContacts.Contact instances which satisfy the criteria specified in query, and deposits them in out_contacts.

The returned EBookContacts.Contact instances are referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with them.

If an error occurs, the function will set error and return False. Note that an empty result set does not necessarily imply an error.

New in version 3.10.

get_contact_list_uids(query, cancellable, callback, *user_data)¶

Parameters:

query (str) – a search query in S-expression format
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously obtains a set of ID strings for contacts which satisfy the criteria specified in query.

When the operation is finished, callback will be called. You can then call EDataBook.BookBackend.get_contact_list_uids_finish() to get the result of the operation.

New in version 3.10.

get_contact_list_uids_finish(result, out_uids)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult
out_uids (GLib.Queue) – a GLib.Queue in which to deposit results

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Finishes the operation started with EDataBook.BookBackend.get_contact_list_uids_finish().

ID strings for the matching contacts are deposited in out_uids, and must be freed with GLib.free() when finished with them.

If an error occurs, the function will set error and return False. Note that an empty result set does not necessarily imply an error.

New in version 3.10.

get_contact_list_uids_sync(query, out_uids, cancellable)¶

Parameters:

query (str) – a search query in S-expression format
out_uids (GLib.Queue) – a GLib.Queue in which to deposit results
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Obtains a set of ID strings for contacts which satisfy the criteria specified in query, and deposits them in out_uids.

The returned ID strings must be freed with GLib.free() with finished with them.

If an error occurs, the function will set error and return False. Note that an empty result set does not necessarily imply an error.

New in version 3.10.

get_contact_sync(uid, cancellable)¶

Parameters:

uid (str) – a contact ID
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

an EBookContacts.Contact, or None on error

Return type:

EBookContacts.Contact

Obtains an EBookContacts.Contact for uid.

The returned EBookContacts.Contact is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

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

New in version 3.10.

get_direct_book()¶

Returns:: A new EDataBook.DataBookDirect object, or None if self does not support direct access
Return type:: EDataBook.DataBookDirect or None

Tries to create an EDataBook.DataBookDirect for self if backend supports direct read access.

New in version 3.8.

get_registry()¶

Returns:: an EDataServer.SourceRegistry
Return type:: EDataServer.SourceRegistry

Returns the data source registry to which EBackend.Backend :source belongs.

New in version 3.6.

get_view_n_total(view_id)¶

Parameters:: view_id (int) – a view identifier
Returns:: how many contacts the view identified by view_id contains.
Return type:: int

Returns how many contacts the view identified by view_id contains.

The default implementation of this virtual method returns the value previously set by EDataBook.BookBackend.set_view_n_total().

Note: This function should be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY views.

New in version 3.50.

get_writable()¶

Returns:: whether self is writable
Return type:: bool

Returns whether self will accept changes to its data content.

New in version 3.8.

is_opened()¶

Returns:: True if fully opened, False otherwise.
Return type:: bool

Checks if self's storage has been opened (and authenticated, if necessary) and the backend itself is ready for accessing. This property is changed automatically after the self is successfully opened.

New in version 3.2.

is_readonly()¶

Returns:: True if read-only, False if not.
Return type:: bool

Checks if we can write to self.

New in version 3.2.

list_views()¶

Returns:: a list of book views
Return type:: [EDataBook.DataBookView]

Returns a list of EDataBook.DataBookView instances added with EDataBook.BookBackend.add_view().

The views returned in the list are referenced for thread-safety. They must each be unreferenced with GObject.Object.unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list properly in one step is as follows:

g_list_free_full (list, g_object_unref);

New in version 3.8.

modify_contacts(vcards, opflags, cancellable, callback, *user_data)¶

Parameters:

vcards (str) – a None-terminated array of vCard strings
opflags (int) – bit-or of EBookContacts.BookOperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously modifies one or more contacts according to vcards.

When the operation is finished, callback will be called. You can then call EDataBook.BookBackend.modify_contacts_finish() to get the result of the operation.

New in version 3.10.

modify_contacts_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Finishes the operation started with EDataBook.BookBackend.modify_contacts().

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

New in version 3.10.

modify_contacts_sync(vcards, opflags, cancellable)¶

Parameters:

vcards (str) – a None-terminated array of vCard strings
opflags (int) – bit-or of EBookContacts.BookOperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Modifies one or more contacts according to vcards.

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

New in version 3.10.

notify_complete()¶: Notifies all of self's book views that the current set of notifications is complete; use this after a series of EDataBook.BookBackend.notify_update() and EDataBook.BookBackend.notify_remove() calls.

notify_error(message)¶

Parameters:: message (str) – an error message

Notifies each backend listener about an error. This is meant to be used for cases where is no GLib.Error return possibility, to notify user about an issue.

New in version 3.2.

notify_property_changed(prop_name, prop_value)¶

Parameters:

prop_name (str) – property name, which changed
prop_value (str or None) – new property value

Notifies clients about property value change.

New in version 3.2.

notify_remove(id)¶

Parameters:: id (str) – a contact id

Notifies all of self's book views that the contact with UID id has been removed.

EDataBook.DataBook.respond_remove_contacts() calls this function for you. You only need to call this from your backend if contacts are removed by another (non-PAS-using) client.

notify_update(contact)¶

Parameters:: contact (EBookContacts.Contact) – a new or modified contact

Notifies all of self's book views about the new or modified contacts contact.

EDataBook.DataBook.respond_create_contacts() and EDataBook.DataBook.respond_modify_contacts() call this function for you. You only need to call this from your backend if contacts are created or modified by another (non-PAS-using) client.

open(cancellable, callback, *user_data)¶

Parameters:

cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously “opens” the self. Opening a backend is something of an outdated concept, but the operation is hanging around for a little while longer. This usually involves some custom initialization logic, and testing of remote authentication if applicable.

When the operation is finished, callback will be called. You can then call EDataBook.BookBackend.open_finish() to get the result of the operation.

New in version 3.10.

open_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Finishes the operation started with EDataBook.BookBackend.open().

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

New in version 3.10.

open_sync(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

“Opens” the self. Opening a backend is something of an outdated concept, but the operation is hanging around for a little while longer. This usually involves some custom initialization logic, and testing of remote authentication if applicable.

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

New in version 3.10.

prepare_for_completion(opid)¶

Parameters:: opid (int) – an operation ID given to EDataBook.DataBook
Returns:: a Gio.Task
Return type:: Gio.Task

Obtains the Gio.Task for opid.

This is a temporary function to serve EDataBook.DataBook's “respond” functions until they can be removed. Nothing else should be calling this function.

New in version 3.10.

ref_data_book()¶

Returns:: an EDataBook.DataBook, or None
Return type:: EDataBook.DataBook or None

Returns the EDataBook.DataBook for self. The EDataBook.DataBook is essentially the glue between incoming D-Bus requests and self's native API.

An EDataBook.DataBook should be set only once after self is first created. If an EDataBook.DataBook has not yet been set, the function returns None.

The returned EDataBook.DataBook is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

New in version 3.10.

ref_proxy_resolver()¶

Returns:: a Gio.ProxyResolver, or None
Return type:: Gio.ProxyResolver or None

Returns the Gio.ProxyResolver for self (if applicable), as indicated by the EDataServer.SourceAuthentication :proxy-uid of self's EBackend.Backend :source or one of its ancestors.

The returned Gio.ProxyResolver is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

New in version 3.12.

ref_view(view_id)¶

Parameters:: view_id (int) – a view identifier
Returns:: a referenced EDataBook.DataBookView corresponding to the given view_id, or None, when it cannot be found
Return type:: EDataBook.DataBookView or None

References an EDataBook.DataBookView by its identifier.

Unref the returned non-None view with GObject.Object.unref(), when no longer needed.

New in version 3.50.

ref_view_user_data(view_id)¶

Parameters:: view_id (int) – a view identifier
Returns:: previously set user data for the view_id, or None when none had been set yet or when the view does not exist.
Return type:: GObject.Object

References user data previously set by EDataBook.BookBackend.take_view_user_data() for the view_id.

Free the returned non-None object with GObject.Object.unref(), when no longer needed.

New in version 3.50.

refresh(cancellable, callback, *user_data)¶

Parameters:

cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously initiates a refresh for self, if the self supports refreshing. The actual refresh operation completes on its own time. This function, along with EDataBook.BookBackend.refresh_finish(), merely initiates the operation.

Once the refresh is initiated, callback will be called. You can then call EDataBook.BookBackend.refresh_finish() to get the result of the initiation.

New in version 3.10.

refresh_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Finishes the refresh initiation started with EDataBook.BookBackend.refresh().

If an error occurred while initiating the refresh, the function will set error and return False. If the self does not support refreshing, the function will set an EDataServer.ClientError.NOT_SUPPORTED error and return False.

New in version 3.10.

refresh_sync(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Initiates a refresh for self, if the self supports refreshing. The actual refresh operation completes on its own time. This function merely initiates the operation.

If an error occurs while initiating the refresh, the function will set error and return False. If the self does not support refreshing, the function will set an EDataServer.ClientError.NOT_SUPPORTED error and return False.

New in version 3.10.

remove_contacts(uids, opflags, cancellable, callback, *user_data)¶

Parameters:

uids ([str]) – a None-terminated array of contact ID strings
opflags (int) – bit-or of EBookContacts.BookOperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – data to pass to the callback function

Asynchronously removes one or more contacts according to uids.

When the operation is finished, callback will be called. You can then call EDataBook.BookBackend.remove_contacts_finish() to get the result of the operation.

New in version 3.10.

remove_contacts_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True on success, False on failure
Return type:: bool

Finishes the operation started with EDataBook.BookBackend.remove_contacts().

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

New in version 3.10.

remove_contacts_sync(uids, opflags, cancellable)¶

Parameters:

uids (str) – a None-terminated array of contact ID strings
opflags (int) – bit-or of EBookContacts.BookOperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Removes one or more contacts according to uids.

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

New in version 3.10.

remove_view(view)¶

Parameters:: view (EDataBook.DataBookView) – an EDataBook.DataBookView

Removes view from self.

schedule_custom_operation(use_cancellable, func, *user_data)¶

Parameters:

use_cancellable (Gio.Cancellable or None) – an optional Gio.Cancellable to use for func
func (EDataBook.BookBackendCustomOpFunc) – a function to call in a dedicated thread
user_data (object or None) – user data being passed to func

Schedules user function func to be run in a dedicated thread as a blocking operation.

The function adds its own reference to use_cancellable, if not None.

The error returned from func is propagated to client using EDataBook.BookBackend.notify_error() function. If it’s not desired, then left the error unchanged and notify about errors manually.

New in version 3.26.

set_cache_dir(cache_dir)¶

Parameters:: cache_dir (str) – a local cache directory path

Sets the cache directory path for use by self.

Note that EDataBook.BookBackend is initialized with a default cache directory path which should suffice for most cases. Backends should not override the default path without good reason.

New in version 2.32.

set_data_book(data_book)¶

Parameters:: data_book (EDataBook.DataBook) – an EDataBook.DataBook

Sets the EDataBook.DataBook for self. The EDataBook.DataBook is essentially the glue between incoming D-Bus requests and self's native API.

An EDataBook.DataBook should be set only once after self is first created.

New in version 3.10.

set_locale(locale, cancellable)¶

Parameters:

locale (str) – the new locale for the addressbook
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Notify the addressbook backend that the current locale has changed, this is important for backends which support ordered result lists which are locale sensitive.

New in version 3.12.

set_view_indices(view_id, indices)¶

Parameters:

view_id (int) – a view identifier
indices (EBookContacts.BookIndices or None) – an array of EBookContacts.BookIndices, or None

Stores current indices for the view identified by the view_id and, if such exists, notifies about it also the corresponding EDataBook.DataBookView. The array is terminated by an item with chr member being None.

Note: This function should be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY views.

New in version 3.50.

set_view_n_total(view_id, n_total)¶

Parameters:

view_id (int) – a view identifier
n_total (int) – the value to set

Stores how many contacts the view identified by view_id contains. It also sets the n_total to the corresponding EDataBook.DataBookView, if such exists. The function does nothing when the view cannot be found.

Note: This function should be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY views.

New in version 3.50.

set_view_sort_fields(view_id, fields)¶

Parameters:

view_id (int) – a view identifier
fields (EBookContacts.BookClientViewSortFields or None) – an array of EBookContacts.BookClientViewSortFields, or None

Sets the sort fields for the view identified by the view_id. The fields array should be terminated by an item, which has the field member set to EBookContacts.ContactField.FIELD_LAST.

When the fields is None, the sort by file-as in ascending order is used instead.

The default implementation of this virtual method stores the fields into the internal structure for the self, to be available by EDataBook.BookBackend.dup_view_sort_fields().

Note: This function should be used only with EBookContacts.BookClientViewFlags.MANUAL_QUERY views.

New in version 3.50.

set_writable(writable)¶

Parameters:: writable (bool) – whether self is writable

Sets whether self will accept changes to its data content.

New in version 3.8.

start_view(view)¶

Parameters:: view (EDataBook.DataBookView) – the EDataBook.DataBookView to start

Starts running the query specified by view, emitting signals for matching contacts.

stop_view(view)¶

Parameters:: view (EDataBook.DataBookView) – the EDataBook.DataBookView to stop

Stops running the query specified by view, emitting no more signals.

sync()¶

take_view_user_data(view_id, user_data)¶

Parameters:

view_id (int) – a view identifier
user_data (GObject.Object or None) – user data to set

Sets the user data for the view_id. The function assumes ownership of the user_data. The user_data can be None, which unsets the current user data for the view.

This is primarily aimed as a helper for backend implementations of the manual query views (EBookContacts.BookClientViewFlags.MANUAL_QUERY).

New in version 3.50.

do_closed(sender) virtual¶

Parameters:: sender (str) –

A signal notifying that the backend was closed

do_impl_configure_direct(config) virtual¶

Parameters:: config (str) –

For addressbook backends which support Direct Read Access, configure a backend instantiated on the client side for Direct Read Access, using data reported from the server via the get_direct_book method.

do_impl_contains_email(book, opid, cancellable, email_address) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –
email_address (str) –

Checkes whether the backend contains an email address

do_impl_create_contacts(book, opid, cancellable, vcards, opflags) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –
vcards (str) –
opflags (int) –

Add and store the passed vcards

do_impl_delete_cursor(cursor) virtual¶

Parameters:: cursor (EDataBook.DataBookCursor) –
Return type:: bool

Delete an EDataBook.DataBookCursor previously created by this backend

do_impl_dup_locale() virtual¶

Return type:: str

Return the currently set locale setting (must be a string duplicate, for thread safety).

do_impl_dup_view_indices(view_id) virtual¶

Parameters:: view_id (int) –
Return type:: EBookContacts.BookIndices

retrieve indexes into an alphabet for contacts in the “manual query” view; default implementation returns value set by EDataBook.BookBackend.set_view_indices().

New in version 3.50.

do_impl_get_backend_property(prop_name) virtual¶

Parameters:: prop_name (str) –
Return type:: str

Fetch a property value by name from the backend

do_impl_get_contact(book, opid, cancellable, id) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –
id (str) –

Fetch a contact by UID

do_impl_get_contact_list(book, opid, cancellable, query) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –
query (str) –

Fetch a list of contacts based on a search expression

do_impl_get_contact_list_uids(book, opid, cancellable, query) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –
query (str) –

Fetch a list of contact UIDs based on a search expression

do_impl_get_view_n_total(view_id) virtual¶

Parameters:: view_id (int) –
Return type:: int

retrieve how many contacts a “manual query” view has; default implementation returns value set by EDataBook.BookBackend.set_view_n_total().

New in version 3.50.

do_impl_modify_contacts(book, opid, cancellable, vcards, opflags) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –
vcards (str) –
opflags (int) –

Modify the existing contacts using the passed vcards

do_impl_notify_update(contact) virtual¶

Parameters:: contact (EBookContacts.Contact) –

Notify changes which might have occured for a given contact

do_impl_open(book, opid, cancellable) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –

Open the backend

do_impl_refresh(book, opid, cancellable) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –

Refresh the backend

do_impl_remove_contacts(book, opid, cancellable, uids, opflags) virtual¶

Parameters:

book (EDataBook.DataBook) –
opid (int) –
cancellable (Gio.Cancellable or None) –
uids (str) –
opflags (int) –

Remove the contacts specified by the passed UIDs

do_impl_set_locale(locale, cancellable) virtual¶

Parameters:

locale (str) –
cancellable (Gio.Cancellable or None) –

Return type:

bool

Store & remember the passed locale setting

do_impl_set_view_sort_fields(view_id, fields) virtual¶

Parameters:

view_id (int) –
fields (EBookContacts.BookClientViewSortFields) –

sets sort fields for “manual query” views; default implementation saves the values into internal structures, which can be read back with EDataBook.BookBackend.dup_view_sort_fields().

New in version 3.50.

do_impl_start_view(view) virtual¶

Parameters:: view (EDataBook.DataBookView) –

Start up the specified view

do_impl_stop_view(view) virtual¶

Parameters:: view (EDataBook.DataBookView) –

Stop the specified view

do_shutdown() virtual¶: A signal notifying that the backend is being shut down

Signal Details¶

EDataBook.BookBackend.signals.closed(book_backend, sender)¶

Signal Name:

closed

Flags:

RUN_LAST

Parameters:

book_backend (EDataBook.BookBackend) – The object which received the signal
sender (str) – the bus name that invoked the “close” method

Emitted when a client destroys its #EBookClient for backend.

New in version 3.10.

EDataBook.BookBackend.signals.shutdown(book_backend)¶

Signal Name:: shutdown
Flags:: RUN_LAST
Parameters:: book_backend (EDataBook.BookBackend) – The object which received the signal

Emitted when the last client destroys its #EBookClient for backend. This signals the backend to begin final cleanup tasks such as synchronizing data to permanent storage.

New in version 3.10.

Property Details¶

EDataBook.BookBackend.props.cache_dir¶

Name:: cache-dir
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The backend’s cache directory

EDataBook.BookBackend.props.proxy_resolver¶

Name:: proxy-resolver
Type:: Gio.ProxyResolver
Default Value:: None
Flags:: READABLE

The proxy resolver for this backend

EDataBook.BookBackend.props.registry¶

Name:: registry
Type:: EDataServer.SourceRegistry
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Data source registry

EDataBook.BookBackend.props.writable¶

Name:: writable
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the backend will accept changes