EDataBook.BookMetaBackend¶

Subclasses:	None

Methods¶

Inherited:	EDataBook.BookBackendSync (8), EDataBook.BookBackend (57), EBackend.Backend (20), GObject.Object (37)
Structs:	GObject.ObjectClass (5)

	`connect_sync` (credentials, cancellable)
	`disconnect_sync` (cancellable)
	`dup_sync_tag` ()
	`empty_cache_sync` (cancellable)
	`ensure_connected_sync` (cancellable)
	`get_capabilities` ()
	`get_changes_sync` (last_sync_tag, is_repeat, cancellable)
	`get_connected_writable` ()
	`get_ever_connected` ()
	`get_ssl_error_details` ()
	`inline_local_photos_sync` (contact, cancellable)
	`list_existing_sync` (cancellable)
	`load_contact_sync` (uid, extra, cancellable)
	`process_changes_sync` (created_objects, modified_objects, removed_objects, cancellable)
	`ref_cache` ()
	`refresh_sync` (cancellable)
	`remove_contact_sync` (conflict_resolution, uid, extra, object, opflags, cancellable)
	`requires_reconnect` ()
	`save_contact_sync` (overwrite_existing, conflict_resolution, contact, extra, opflags, cancellable)
	`schedule_refresh` ()
	`search_sync` (expr, meta_contact, cancellable)
	`search_uids_sync` (expr, cancellable)
	`set_cache` (cache)
	`set_connected_writable` (value)
	`set_ever_connected` (value)
	`split_changes_sync` (objects, cancellable)
	`store_inline_photos_sync` (contact, cancellable)

Virtual Methods¶

Inherited:	EDataBook.BookBackendSync (2), EDataBook.BookBackend (18), EBackend.Backend (3), GObject.Object (7)

	`do_connect_sync` (credentials, cancellable)
	`do_disconnect_sync` (cancellable)
	`do_get_changes_sync` (last_sync_tag, is_repeat, cancellable)
	`do_get_ssl_error_details` ()
	`do_list_existing_sync` (cancellable)
	`do_load_contact_sync` (uid, extra, cancellable)
	`do_remove_contact_sync` (conflict_resolution, uid, extra, object, opflags, cancellable)
	`do_requires_reconnect` ()
	`do_save_contact_sync` (overwrite_existing, conflict_resolution, contact, extra, opflags, cancellable)
	`do_search_sync` (expr, meta_contact, cancellable)
	`do_search_uids_sync` (expr, cancellable)
	`do_source_changed` ()

Properties¶

Inherited:	EDataBook.BookBackend (4), EBackend.Backend (5)

Name	Type	Flags	Short Description
`cache`	`EDataBook.BookCache`	r/w/en	Book Cache

Signals¶

Inherited:	EDataBook.BookBackend (2), GObject.Object (1)

Name	Short Description
`refresh-completed`
`source-changed`	This signal is emitted whenever the underlying backend `EDataServer.Source` changes.

Fields¶

Inherited:	EDataBook.BookBackend (2), GObject.Object (1)

Name	Type	Access	Description
parent	`EDataBook.BookBackendSync`	r

Class Details¶

class EDataBook.BookMetaBackend(**kwargs)¶

Bases:	`EDataBook.BookBackendSync`
Abstract:	Yes
Structure:	`EDataBook.BookMetaBackendClass`

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

New in version 3.26.

connect_sync(credentials, cancellable)¶

Parameters:

credentials (EDataServer.NamedParameters or None) – an EDataServer.NamedParameters with previously used credentials, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_auth_result:
	an `EDataServer.SourceAuthenticationResult` with an authentication result
out_certificate_pem:
	a PEM encoded certificate on failure, or `None`
out_certificate_errors:
	a `Gio.TlsCertificateFlags` on failure, or 0

Return type:

(bool, out_auth_result: EDataServer.SourceAuthenticationResult, out_certificate_pem: str, out_certificate_errors: Gio.TlsCertificateFlags)

This is called always before any operation which requires a connection to the remote side. It can fail with an EDataServer.ClientError.REPOSITORY_OFFLINE error to indicate that the remote side cannot be currently reached. Other errors are propagated to the caller/client side. This method is not called when the backend is offline.

The descendant should also call EDataBook.BookBackend.set_writable() after successful connect to the remote side. This value is stored for later use, when being opened offline.

The credentials parameter consists of the previously used credentials. It’s always None with the first connection attempt. To get the credentials, just set the out_auth_result to EDataServer.SourceAuthenticationResult.REQUIRED for the first time and the function will be called again once the credentials are available. See the documentation of EDataServer.SourceAuthenticationResult for other available results.

The out parameters are passed to EBackend.Backend.schedule_credentials_required() and are ignored when the descendant returns True, aka they are used only if the connection fails. The out_certificate_pem and out_certificate_errors should be used together and they can be left untouched if the failure reason was not related to certificate. Use out_auth_result EDataServer.SourceAuthenticationResult.UNKNOWN to indicate other error than credentials error, otherwise the error is used according to out_auth_result value.

It is mandatory to implement this virtual method by the descendant.

New in version 3.26.

disconnect_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	Whether succeeded.
Return type:	`bool`

This is called when the backend goes into offline mode or when the disconnect is required. The implementation should not report any error when it is called and the self is not connected.

It is mandatory to implement this virtual method by the descendant.

New in version 3.26.

dup_sync_tag()¶

Returns:	The last known synchronization tag, or `None`, when none is stored.
Return type:	`str` or `None`

Returns the last known synchronization tag, the same as used to call EDataBook.BookMetaBackend.get_changes_sync().

Free the returned string with GLib.free(), when no longer needed.

New in version 3.28.

empty_cache_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	Whether succeeded.
Return type:	`bool`

Empties the local cache by removing all known contacts from it and notifies about such removal any opened views.

New in version 3.26.

ensure_connected_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	Whether succeeded.
Return type:	`bool`

Ensures that the self is connected to its destination.

New in version 3.26.

get_capabilities()¶

Returns:	an `EDataBook.BookBackend` `::capabilities` property to be used by the descendant in conjunction to the descendant’s capabilities in the result of `EDataBook.BookBackend.get_backend_property`() with `EDataServer.CLIENT_BACKEND_PROPERTY_CAPABILITIES`.
Return type:	`str`

New in version 3.26.

get_changes_sync(last_sync_tag, is_repeat, cancellable)¶

Parameters:

last_sync_tag (str or None) – optional sync tag from the last check
is_repeat (bool) – set to True when this is the repeated call
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_new_sync_tag:
	new sync tag to store on success
out_repeat:	whether to repeat this call again; default is `False`
out_created_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been created since the last check
out_modified_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been modified since the last check
out_removed_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been removed since the last check

Return type:

(bool, out_new_sync_tag: str, out_repeat: bool, out_created_objects: [EDataBook.BookMetaBackendInfo], out_modified_objects: [EDataBook.BookMetaBackendInfo], out_removed_objects: [EDataBook.BookMetaBackendInfo])

Gathers the changes since the last check which had been done on the remote side.

The last_sync_tag can be used as a tag of the last check. This can be None, when there was no previous call or when the descendant doesn’t store any such tags. The out_new_sync_tag can be populated with a value to be stored and used the next time.

The out_repeat can be set to True when the descendant didn’t finish read of all the changes. In that case the self calls this function again with the out_new_sync_tag as the last_sync_tag, but also notifies about the found changes immediately. The is_repeat is set to True as well in this case, otherwise it’s False.

The descendant can populate also EDataBook.BookMetaBackendInfo ::object of the out_created_objects and out_modified_objects, if known, in which case this will be used instead of loading it with EDataBook.BookMetaBackend.load_contact_sync().

It is optional to implement this virtual method by the descendant. The default implementation calls EDataBook.BookMetaBackend.list_existing_sync() and then compares the list with the current content of the local cache and populates the respective lists appropriately.

Each output GLib.SList should be freed with g_slist_free_full (objects, EDataBook.BookMetaBackendInfo.free); when no longer needed.

New in version 3.26.

get_connected_writable()¶

Returns:	Whether the self connected to a writable destination.
Return type:	`bool`

This value has meaning only if EDataBook.BookMetaBackend.get_ever_connected() is True.

New in version 3.26.

get_ever_connected()¶

Returns:	Whether the self ever made a successful connection to its destination.
Return type:	`bool`

New in version 3.26.

get_ssl_error_details()¶

Returns:

True, when the SSL error details had been available and the out parameters populated, False otherwise.

out_certificate_pem:
	SSL certificate encoded in PEM format
out_certificate_errors:
	bit-or of `Gio.TlsCertificateFlags` claiming the certificate errors

Return type: (bool, out_certificate_pem: str, out_certificate_errors: Gio.TlsCertificateFlags)

It is optional to implement this virtual method by the descendants. It is used to receive SSL error details when any online operation returns E_CLIENT_ERROR, EDataServer.ClientError.TLS_NOT_AVAILABLE error.

New in version 3.28.

inline_local_photos_sync(contact, cancellable)¶

Parameters:	contact (`EBookContacts.Contact`) – an `EBookContacts.Contact` to work with cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	Whether succeeded.
Return type:	`bool`

Changes all URL photos and logos which point to a local file in contact to inline type, aka adds the file content into the contact. This is called automatically before EDataBook.BookMetaBackend.save_contact_sync().

The reverse operation is EDataBook.BookMetaBackend.store_inline_photos_sync().

New in version 3.26.

list_existing_sync(cancellable)¶

Parameters: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises: GLib.Error

Returns:

Whether succeeded.

out_new_sync_tag:
	optional return location for a new sync tag
out_existing_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which are stored on the remote side

Return type: (bool, out_new_sync_tag: str, out_existing_objects: [EDataBook.BookMetaBackendInfo])

Used to get list of all existing objects on the remote side. The descendant can optionally provide out_new_sync_tag, which will be stored on success, if not None. The descendant can populate also EDataBook.BookMetaBackendInfo ::object of the out_existing_objects, if known, in which case this will be used instead of loading it with EDataBook.BookMetaBackend.load_contact_sync().

It is mandatory to implement this virtual method by the descendant, unless it implements its own EDataBook.BookMetaBackend.do_get_changes_sync().

The out_existing_objects GLib.SList should be freed with g_slist_free_full (objects, EDataBook.BookMetaBackendInfo.free); when no longer needed.

New in version 3.26.

load_contact_sync(uid, extra, cancellable)¶

Parameters:

uid (str) – a contact UID
extra (str or None) – optional extra data stored with the contact, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_contact:	a loaded contact, as an `EBookContacts.Contact`
out_extra:	an extra data to store to `EDataBook.BookCache` with this contact

Return type:

(bool, out_contact: EBookContacts.Contact, out_extra: str)

Loads a contact from the remote side.

It is mandatory to implement this virtual method by the descendant.

The returned out_contact should be freed with GObject.Object.unref(), when no longer needed.

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

New in version 3.26.

process_changes_sync(created_objects, modified_objects, removed_objects, cancellable)¶

Parameters:	created_objects ([`EDataBook.BookMetaBackendInfo`] or `None`) – a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been created modified_objects ([`EDataBook.BookMetaBackendInfo`] or `None`) – a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been modified removed_objects ([`EDataBook.BookMetaBackendInfo`] or `None`) – a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been removed cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	Whether succeeded.
Return type:	`bool`

Processes given changes by updating local cache content accordingly. The self processes the changes like being online and particularly requires to be online to load created and modified objects when needed.

New in version 3.26.

ref_cache()¶

Returns:	Referenced `EDataBook.BookCache`, which is used by self. Unref it with `GObject.Object.unref`(), when no longer needed.
Return type:	`EDataBook.BookCache`

New in version 3.26.

refresh_sync(cancellable)¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	Whether succeeded.
Return type:	`bool`

Refreshes the self immediately. To just schedule refresh operation call EDataBook.BookMetaBackend.schedule_refresh().

New in version 3.26.

remove_contact_sync(conflict_resolution, uid, extra, object, opflags, cancellable)¶

Parameters:	conflict_resolution (`EDataServer.ConflictResolution`) – an `EDataServer.ConflictResolution` to use uid (`str`) – a contact UID extra (`str` or `None`) – extra data being saved with the contact in the local cache, or `None` object (`str` or `None`) – corresponding vCard object, as stored in the local cache, or `None` opflags (`int`) – bit-or of `EBookContacts.BookOperationFlags` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	Whether succeeded.
Return type:	`bool`

Removes a contact from the remote side. The object is not None when it’s removing locally deleted object in offline mode. Being it None, the descendant can obtain the object from the EDataBook.BookCache.

It is mandatory to implement this virtual method by the writable descendant.

New in version 3.26.

requires_reconnect()¶

Returns:	`True`, when reconnect is required, `False` otherwise.
Return type:	`bool`

Determines, whether current source content requires reconnect of the backend.

It is optional to implement this virtual method by the descendant. The default implementation compares EDataServer.SOURCE_EXTENSION_AUTHENTICATION and EDataServer.SOURCE_EXTENSION_WEBDAV_BACKEND, if existing in the source, with the values after the last successful connect and returns True when they changed. It always return True when there was no successful connect done yet.

New in version 3.26.

save_contact_sync(overwrite_existing, conflict_resolution, contact, extra, opflags, cancellable)¶

Parameters:

overwrite_existing (bool) – True when can overwrite existing contacts, False otherwise
conflict_resolution (EDataServer.ConflictResolution) – one of EDataServer.ConflictResolution, what to do on conflicts
contact (EBookContacts.Contact) – an EBookContacts.Contact to save
extra (str or None) – extra data saved with the contacts in an EDataBook.BookCache
opflags (int) – bit-or of EBookContacts.BookOperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_new_uid:	return location for the UID of the saved contact
out_new_extra:	return location for the extra data to store with the contact

Return type:

(bool, out_new_uid: str, out_new_extra: str)

Saves one contact into the remote side. When the overwrite_existing is True, then the descendant can overwrite an object with the same UID on the remote side (usually used for modify). The conflict_resolution defines what to do when the remote side had made any changes to the object since the last update.

The contact has already converted locally stored photos and logos into inline variants, thus it’s not needed to call EDataBook.BookMetaBackend.inline_local_photos_sync() by the descendant.

The out_new_uid can be populated with a UID of the saved contact as the server assigned it to it. This UID, if set, is loaded from the remote side afterwards, also to see whether any changes had been made to the contact by the remote side.

The out_new_extra can be populated with a new extra data to save with the contact. Left it None, to keep the same value as the extra.

The descendant can use an EDataServer.ClientError.OUT_OF_SYNC error to indicate that the save failed due to made changes on the remote side, and let the self resolve this conflict based on the conflict_resolution on its own. The EDataServer.ClientError.OUT_OF_SYNC error should not be used when the descendant is able to resolve the conflicts itself.

It is mandatory to implement this virtual method by the writable descendant.

New in version 3.26.

schedule_refresh()¶

Schedules refresh of the content of the self. If there’s any already scheduled, then the function does nothing.

Use EDataBook.BookMetaBackend.refresh_sync() to refresh the self immediately.

New in version 3.26.

search_sync(expr, meta_contact, cancellable)¶

Parameters:

expr (str or None) – a search expression, or None
meta_contact (bool) – True, when return EBookContacts.Contact filled with UID and REV only, False to return full contacts
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_contacts:	return location for the found contacts as `EBookContacts.Contact`

Return type:

(bool, out_contacts: [EBookContacts.Contact])

Searches self with given expression expr and returns found contacts as a GLib.SList of EBookContacts.Contact out_contacts. Free the returned out_contacts with g_slist_free_full (contacts, GObject.Object.unref); when no longer needed. When the expr is None, all objects are returned. To get UID-s instead, call EDataBook.BookMetaBackend.search_uids_sync().

It is optional to implement this virtual method by the descendant. The default implementation searches self’s cache. It’s also not required to be online for searching, thus self doesn’t ensure it.

New in version 3.26.

search_uids_sync(expr, cancellable)¶

Parameters:

expr (str or None) – a search expression, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_uids:	return location for the found contact UID-s

Return type:

(bool, out_uids: [str])

Searches self with given expression expr and returns found contact UID-s as a GLib.SList out_contacts. Free the returned out_uids with g_slist_free_full (uids, GLib.free); when no longer needed. When the expr is None, all UID-s are returned. To get EBookContacts.Contact(s) instead, call EDataBook.BookMetaBackend.search_sync().

It is optional to implement this virtual method by the descendant. The default implementation searches self’s cache. It’s also not required to be online for searching, thus self doesn’t ensure it.

New in version 3.26.

set_cache(cache)¶

Parameters:	cache (`EDataBook.BookCache`) – an `EDataBook.BookCache` to use

Sets the cache as the cache to be used by the self. By default, a cache.db in EDataBook.BookBackend ::cache-dir is created in the constructed method. This function can be used to override the default.

Note the self adds its own reference to the cache.

New in version 3.26.

set_connected_writable(value)¶

Parameters:	value (`bool`) – value to set

Sets whether the self connected to a writable destination. This value has meaning only if EDataBook.BookMetaBackend.get_ever_connected() is True.

This is used by the self itself, during the opening phase, to set the backend writable or not also in the offline mode.

New in version 3.26.

set_ever_connected(value)¶

Parameters:	value (`bool`) – value to set

Sets whether the self ever made a successful connection to its destination.

This is used by the self itself, during the opening phase, when it had not been connected yet, then it does so immediately, to eventually report settings error easily.

New in version 3.26.

split_changes_sync(objects, cancellable)¶

Parameters:

objects ([EDataBook.BookMetaBackendInfo]) – a GLib.SList of EDataBook.BookMetaBackendInfo object infos to split
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

out_created_objects:
objects:	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos to split
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been created
out_modified_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been modified
out_removed_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been removed; it can be `None`, to not gather list of removed object infos

Return type:

(bool, objects: [EDataBook.BookMetaBackendInfo], out_created_objects: [EDataBook.BookMetaBackendInfo], out_modified_objects: [EDataBook.BookMetaBackendInfo], out_removed_objects: [EDataBook.BookMetaBackendInfo])

Splits objects into created/modified/removed lists according to current local cache content. Only the out_removed_objects can be None, others cannot. The function modifies objects by moving its ‘data’ to corresponding out lists and sets the objects ‘data’ to None.

Each output GLib.SList should be freed with g_slist_free_full (objects, EDataBook.BookMetaBackendInfo.free); when no longer needed.

The caller is still responsible to free objects as well.

New in version 3.26.

store_inline_photos_sync(contact, cancellable)¶

Parameters:	contact (`EBookContacts.Contact`) – an `EBookContacts.Contact` to work with cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Raises:	`GLib.Error`
Returns:	Whether succeeded.
Return type:	`bool`

Changes all inline photos and logos to URL type in contact, which will point to a local file instead, beside the cache file. This is called automatically after EDataBook.BookMetaBackend.load_contact_sync().

The reverse operation is EDataBook.BookMetaBackend.inline_local_photos_sync().

New in version 3.26.

do_connect_sync(credentials, cancellable) virtual¶

Parameters:

credentials (EDataServer.NamedParameters or None) – an EDataServer.NamedParameters with previously used credentials, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded.

out_auth_result:
	an `EDataServer.SourceAuthenticationResult` with an authentication result
out_certificate_pem:
	a PEM encoded certificate on failure, or `None`
out_certificate_errors:
	a `Gio.TlsCertificateFlags` on failure, or 0

Return type:

(bool, out_auth_result: EDataServer.SourceAuthenticationResult, out_certificate_pem: str, out_certificate_errors: Gio.TlsCertificateFlags)

This is called always before any operation which requires a connection to the remote side. It can fail with an EDataServer.ClientError.REPOSITORY_OFFLINE error to indicate that the remote side cannot be currently reached. Other errors are propagated to the caller/client side. This method is not called when the backend is offline.

The descendant should also call EDataBook.BookBackend.set_writable() after successful connect to the remote side. This value is stored for later use, when being opened offline.

The credentials parameter consists of the previously used credentials. It’s always None with the first connection attempt. To get the credentials, just set the out_auth_result to EDataServer.SourceAuthenticationResult.REQUIRED for the first time and the function will be called again once the credentials are available. See the documentation of EDataServer.SourceAuthenticationResult for other available results.

The out parameters are passed to EBackend.Backend.schedule_credentials_required() and are ignored when the descendant returns True, aka they are used only if the connection fails. The out_certificate_pem and out_certificate_errors should be used together and they can be left untouched if the failure reason was not related to certificate. Use out_auth_result EDataServer.SourceAuthenticationResult.UNKNOWN to indicate other error than credentials error, otherwise the error is used according to out_auth_result value.

It is mandatory to implement this virtual method by the descendant.

New in version 3.26.

do_disconnect_sync(cancellable) virtual¶

Parameters:	cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	Whether succeeded.
Return type:	`bool`

This is called when the backend goes into offline mode or when the disconnect is required. The implementation should not report any error when it is called and the meta_backend is not connected.

It is mandatory to implement this virtual method by the descendant.

New in version 3.26.

do_get_changes_sync(last_sync_tag, is_repeat, cancellable) virtual¶

Parameters:

last_sync_tag (str or None) – optional sync tag from the last check
is_repeat (bool) – set to True when this is the repeated call
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded.

out_new_sync_tag:
	new sync tag to store on success
out_repeat:	whether to repeat this call again; default is `False`
out_created_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been created since the last check
out_modified_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been modified since the last check
out_removed_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which had been removed since the last check

Return type:

(bool, out_new_sync_tag: str, out_repeat: bool, out_created_objects: [EDataBook.BookMetaBackendInfo], out_modified_objects: [EDataBook.BookMetaBackendInfo], out_removed_objects: [EDataBook.BookMetaBackendInfo])

Gathers the changes since the last check which had been done on the remote side.

The last_sync_tag can be used as a tag of the last check. This can be None, when there was no previous call or when the descendant doesn’t store any such tags. The out_new_sync_tag can be populated with a value to be stored and used the next time.

The out_repeat can be set to True when the descendant didn’t finish read of all the changes. In that case the meta_backend calls this function again with the out_new_sync_tag as the last_sync_tag, but also notifies about the found changes immediately. The is_repeat is set to True as well in this case, otherwise it’s False.

The descendant can populate also EDataBook.BookMetaBackendInfo ::object of the out_created_objects and out_modified_objects, if known, in which case this will be used instead of loading it with EDataBook.BookMetaBackend.load_contact_sync().

It is optional to implement this virtual method by the descendant. The default implementation calls EDataBook.BookMetaBackend.list_existing_sync() and then compares the list with the current content of the local cache and populates the respective lists appropriately.

Each output GLib.SList should be freed with g_slist_free_full (objects, EDataBook.BookMetaBackendInfo.free); when no longer needed.

New in version 3.26.

do_get_ssl_error_details() virtual¶

Returns:

True, when the SSL error details had been available and the out parameters populated, False otherwise.

out_certificate_pem:
	SSL certificate encoded in PEM format
out_certificate_errors:
	bit-or of `Gio.TlsCertificateFlags` claiming the certificate errors

Return type: (bool, out_certificate_pem: str, out_certificate_errors: Gio.TlsCertificateFlags)

It is optional to implement this virtual method by the descendants. It is used to receive SSL error details when any online operation returns E_CLIENT_ERROR, EDataServer.ClientError.TLS_NOT_AVAILABLE error.

New in version 3.28.

do_list_existing_sync(cancellable) virtual¶

Parameters: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded.

out_new_sync_tag:
	optional return location for a new sync tag
out_existing_objects:
	a `GLib.SList` of `EDataBook.BookMetaBackendInfo` object infos which are stored on the remote side

Return type: (bool, out_new_sync_tag: str, out_existing_objects: [EDataBook.BookMetaBackendInfo])

Used to get list of all existing objects on the remote side. The descendant can optionally provide out_new_sync_tag, which will be stored on success, if not None. The descendant can populate also EDataBook.BookMetaBackendInfo ::object of the out_existing_objects, if known, in which case this will be used instead of loading it with EDataBook.BookMetaBackend.load_contact_sync().

It is mandatory to implement this virtual method by the descendant, unless it implements its own EDataBook.BookMetaBackend.do_get_changes_sync().

The out_existing_objects GLib.SList should be freed with g_slist_free_full (objects, EDataBook.BookMetaBackendInfo.free); when no longer needed.

New in version 3.26.

do_load_contact_sync(uid, extra, cancellable) virtual¶

Parameters:

uid (str) – a contact UID
extra (str or None) – optional extra data stored with the contact, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded.

out_contact:	a loaded contact, as an `EBookContacts.Contact`
out_extra:	an extra data to store to `EDataBook.BookCache` with this contact

Return type:

(bool, out_contact: EBookContacts.Contact, out_extra: str)

Loads a contact from the remote side.

It is mandatory to implement this virtual method by the descendant.

The returned out_contact should be freed with GObject.Object.unref(), when no longer needed.

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

New in version 3.26.

do_remove_contact_sync(conflict_resolution, uid, extra, object, opflags, cancellable) virtual¶

Parameters:	conflict_resolution (`EDataServer.ConflictResolution`) – an `EDataServer.ConflictResolution` to use uid (`str`) – a contact UID extra (`str` or `None`) – extra data being saved with the contact in the local cache, or `None` object (`str` or `None`) – corresponding vCard object, as stored in the local cache, or `None` opflags (`int`) – bit-or of `EBookContacts.BookOperationFlags` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	Whether succeeded.
Return type:	`bool`

Removes a contact from the remote side. The object is not None when it’s removing locally deleted object in offline mode. Being it None, the descendant can obtain the object from the EDataBook.BookCache.

It is mandatory to implement this virtual method by the writable descendant.

New in version 3.26.

do_requires_reconnect() virtual¶

Returns:	`True`, when reconnect is required, `False` otherwise.
Return type:	`bool`

Determines, whether current source content requires reconnect of the backend.

It is optional to implement this virtual method by the descendant. The default implementation compares EDataServer.SOURCE_EXTENSION_AUTHENTICATION and EDataServer.SOURCE_EXTENSION_WEBDAV_BACKEND, if existing in the source, with the values after the last successful connect and returns True when they changed. It always return True when there was no successful connect done yet.

New in version 3.26.

do_save_contact_sync(overwrite_existing, conflict_resolution, contact, extra, opflags, cancellable) virtual¶

Parameters:

overwrite_existing (bool) – True when can overwrite existing contacts, False otherwise
conflict_resolution (EDataServer.ConflictResolution) – one of EDataServer.ConflictResolution, what to do on conflicts
contact (EBookContacts.Contact) – an EBookContacts.Contact to save
extra (str or None) – extra data saved with the contacts in an EDataBook.BookCache
opflags (int) – bit-or of EBookContacts.BookOperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded.

out_new_uid:	return location for the UID of the saved contact
out_new_extra:	return location for the extra data to store with the contact

Return type:

(bool, out_new_uid: str, out_new_extra: str)

Saves one contact into the remote side. When the overwrite_existing is True, then the descendant can overwrite an object with the same UID on the remote side (usually used for modify). The conflict_resolution defines what to do when the remote side had made any changes to the object since the last update.

The contact has already converted locally stored photos and logos into inline variants, thus it’s not needed to call EDataBook.BookMetaBackend.inline_local_photos_sync() by the descendant.

The out_new_uid can be populated with a UID of the saved contact as the server assigned it to it. This UID, if set, is loaded from the remote side afterwards, also to see whether any changes had been made to the contact by the remote side.

The out_new_extra can be populated with a new extra data to save with the contact. Left it None, to keep the same value as the extra.

The descendant can use an EDataServer.ClientError.OUT_OF_SYNC error to indicate that the save failed due to made changes on the remote side, and let the meta_backend resolve this conflict based on the conflict_resolution on its own. The EDataServer.ClientError.OUT_OF_SYNC error should not be used when the descendant is able to resolve the conflicts itself.

It is mandatory to implement this virtual method by the writable descendant.

New in version 3.26.

do_search_sync(expr, meta_contact, cancellable) virtual¶

Parameters:

expr (str or None) – a search expression, or None
meta_contact (bool) – True, when return EBookContacts.Contact filled with UID and REV only, False to return full contacts
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded.

out_contacts:	return location for the found contacts as `EBookContacts.Contact`

Return type:

(bool, out_contacts: [EBookContacts.Contact])

Searches meta_backend with given expression expr and returns found contacts as a GLib.SList of EBookContacts.Contact out_contacts. Free the returned out_contacts with g_slist_free_full (contacts, GObject.Object.unref); when no longer needed. When the expr is None, all objects are returned. To get UID-s instead, call EDataBook.BookMetaBackend.search_uids_sync().

It is optional to implement this virtual method by the descendant. The default implementation searches meta_backend’s cache. It’s also not required to be online for searching, thus meta_backend doesn’t ensure it.

New in version 3.26.

do_search_uids_sync(expr, cancellable) virtual¶

Parameters:

expr (str or None) – a search expression, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded.

out_uids:	return location for the found contact UID-s

Return type:

(bool, out_uids: [str])

Searches meta_backend with given expression expr and returns found contact UID-s as a GLib.SList out_contacts. Free the returned out_uids with g_slist_free_full (uids, GLib.free); when no longer needed. When the expr is None, all UID-s are returned. To get EBookContacts.Contact(s) instead, call EDataBook.BookMetaBackend.search_sync().

It is optional to implement this virtual method by the descendant. The default implementation searches meta_backend’s cache. It’s also not required to be online for searching, thus meta_backend doesn’t ensure it.

New in version 3.26.

do_source_changed() virtual¶

Signal Details¶

EDataBook.BookMetaBackend.signals.refresh_completed(book_meta_backend)¶

Signal Name:	`refresh-completed`
Flags:	`RUN_LAST`
Parameters:	book_meta_backend (`EDataBook.BookMetaBackend`) – The object which received the signal

EDataBook.BookMetaBackend.signals.source_changed(book_meta_backend)¶

Signal Name:	`source-changed`
Flags:	`RUN_LAST`
Parameters:	book_meta_backend (`EDataBook.BookMetaBackend`) – The object which received the signal

This signal is emitted whenever the underlying backend EDataServer.Source changes. Unlike the EDataServer.Source’s ‘changed’ signal this one is tight to the EDataBook.BookMetaBackend itself and is emitted from a dedicated thread, thus it doesn’t block the main thread.

New in version 3.26.

Property Details¶

EDataBook.BookMetaBackend.props.cache¶

Name:	`cache`
Type:	`EDataBook.BookCache`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

The EDataBook.BookCache being used for this meta backend.