EDataBook.BookBackend

g EBackend.Backend EBackend.Backend EDataBook.BookBackend EDataBook.BookBackend EBackend.Backend->EDataBook.BookBackend GObject.Object GObject.Object GObject.Object->EBackend.Backend

Subclasses:EDataBook.BookBackendSync

Methods

Inherited:EBackend.Backend (20), GObject.Object (37)
Structs:GObject.ObjectClass (5)
  add_view (view)
  configure_direct (config)
  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 ()
  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_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, result_queue)
  ref_data_book ()
  ref_proxy_resolver ()
  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_writable (writable)
  start_view (view)
  stop_view (view)
  sync ()

Virtual Methods

Inherited:EBackend.Backend (3), GObject.Object (7)
  do_closed (sender)
  do_impl_configure_direct (config)
  do_impl_create_contacts (book, opid, cancellable, vcards, opflags)
  do_impl_delete_cursor (cursor)
  do_impl_dup_locale ()
  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_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_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.

create_contacts(vcards, opflags, cancellable, callback, *user_data)
Parameters:

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

GLib.Error
Returns:

A newly created cursor, the cursor belongs to the backend and should not be unreffed, or None
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.

foreach_view(func, *user_data)
Parameters:
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:

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

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

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

GLib.Error
Returns:

an EBookContacts.Contact, or None
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_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:

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

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, result_queue)
Parameters:
Returns:

a Gio.SimpleAsyncResult
Return type:

Gio.SimpleAsyncResult

Obtains the Gio.SimpleAsyncResult for opid and sets result_queue as a place to deposit results prior to completing the Gio.SimpleAsyncResult.

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.

refresh(cancellable, callback, *user_data)
Parameters:

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:

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

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:
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_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()
do_closed(sender) virtual
Parameters:sender (str) –
do_impl_configure_direct(config) virtual
Parameters:config (str) –
do_impl_create_contacts(book, opid, cancellable, vcards, opflags) virtual
Parameters:
do_impl_delete_cursor(cursor) virtual
Parameters:cursor (EDataBook.DataBookCursor) –
Return type:bool
do_impl_dup_locale() virtual
Return type:str
do_impl_get_backend_property(prop_name) virtual
Parameters:prop_name (str) –
Return type:str
do_impl_get_contact(book, opid, cancellable, id) virtual
Parameters:
do_impl_get_contact_list(book, opid, cancellable, query) virtual
Parameters:
do_impl_get_contact_list_uids(book, opid, cancellable, query) virtual
Parameters:
do_impl_modify_contacts(book, opid, cancellable, vcards, opflags) virtual
Parameters:
do_impl_notify_update(contact) virtual
Parameters:contact (EBookContacts.Contact) –
do_impl_open(book, opid, cancellable) virtual
Parameters:
do_impl_refresh(book, opid, cancellable) virtual
Parameters:
do_impl_remove_contacts(book, opid, cancellable, uids, opflags) virtual
Parameters:
do_impl_set_locale(locale, cancellable) virtual
Parameters:
Return type:

bool
do_impl_start_view(view) virtual
Parameters:view (EDataBook.DataBookView) –
do_impl_stop_view(view) virtual
Parameters:view (EDataBook.DataBookView) –
do_shutdown() virtual

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