EDataCal.CalMetaBackend¶

Subclasses:: None

Methods¶

Inherited:: EDataCal.CalBackendSync (14), EDataCal.CalBackend (73), EBackend.Backend (21), GObject.Object (37), ECal.TimezoneCache (3)
Structs:: GObject.ObjectClass (5)

	`connect_sync` (credentials, cancellable)
	`disconnect_sync` (cancellable)
	`dup_sync_tag` ()
	`empty_cache_sync` (cancellable)
	`ensure_connected_sync` (cancellable)
	`gather_timezones_sync` (vcalendar, remove_existing, cancellable)
	`get_capabilities` ()
	`get_changes_sync` (last_sync_tag, is_repeat, cancellable)
	`get_connected_writable` ()
	`get_ever_connected` ()
	`get_ssl_error_details` ()
	`inline_local_attachments_sync` (component, cancellable)
	`list_existing_sync` (cancellable)
	`load_component_sync` (uid, extra, cancellable)
	`merge_instances` (instances, replace_tzid_with_location)
	`process_changes_sync` (created_objects, modified_objects, removed_objects, cancellable)
	`ref_cache` ()
	`refresh_sync` (cancellable)
	`remove_component_sync` (conflict_resolution, uid, extra, object, opflags, cancellable)
	`requires_reconnect` ()
	`save_component_sync` (overwrite_existing, conflict_resolution, instances, extra, opflags, cancellable)
	`schedule_refresh` ()
	`search_components_sync` (expr, cancellable)
	`search_sync` (expr, cancellable)
	`set_cache` (cache)
	`set_connected_writable` (value)
	`set_ever_connected` (value)
	`set_sync_tag` (sync_tag)
	`split_changes_sync` (objects, cancellable)
	`store_inline_attachments_sync` (component, cancellable)

Virtual Methods¶

Inherited:: EDataCal.CalBackendSync (7), EDataCal.CalBackend (15), EBackend.Backend (3), GObject.Object (7), ECal.TimezoneCache (2)

	`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_component_sync` (uid, extra, cancellable)
	`do_remove_component_sync` (conflict_resolution, uid, extra, object, opflags, cancellable)
	`do_requires_reconnect` ()
	`do_save_component_sync` (overwrite_existing, conflict_resolution, instances, extra, opflags, cancellable)
	`do_search_components_sync` (expr, cancellable)
	`do_search_sync` (expr, cancellable)
	`do_source_changed` ()

Properties¶

Inherited:: EDataCal.CalBackend (5), EBackend.Backend (5)

Name	Type	Flags	Short Description
`cache`	`EDataCal.CalCache`	r/w/en	Calendar Cache

Signals¶

Inherited:: EDataCal.CalBackend (2), GObject.Object (1), ECal.TimezoneCache (1)

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

Fields¶

Inherited:: EDataCal.CalBackend (2), GObject.Object (1), ECal.TimezoneCache (1)

Name	Type	Access	Description
parent	`EDataCal.CalBackendSync`	r

Class Details¶

class EDataCal.CalMetaBackend(**kwargs)¶

Bases:: EDataCal.CalBackendSync
Abstract:: Yes
Structure:: EDataCal.CalMetaBackendClass

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 EDataCal.CalBackend.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 EDataCal.CalMetaBackend.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 components from it and notifies about such removal any opened views. It removes also all known time zones.

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.

gather_timezones_sync(vcalendar, remove_existing, cancellable)¶

Parameters:

vcalendar (ICalGLib.Component) – a VCALENDAR ICalGLib.Component
remove_existing (bool) – whether to remove any existing first
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Extracts all VTIMEZONE components from the vcalendar and adds them to the memory cache, thus they are available when needed. The function does nothing when the vcalendar doesn’t hold a VCALENDAR component.

Set the remove_existing argument to True to remove all cached timezones first and then add the existing in the vcalendar, or set it to False to preserver existing timezones and merge them with those in vcalendar.

New in version 3.26.

get_capabilities()¶

Returns:: an EDataCal.CalBackend ::capabilities property to be used by the descendant in conjunction to the descendant’s capabilities in the result of EDataCal.CalBackend.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 EDataCal.CalMetaBackendInfo object infos which had been created since the last check
out_modified_objects:: a GLib.SList of EDataCal.CalMetaBackendInfo object infos which had been modified since the last check
out_removed_objects:: a GLib.SList of EDataCal.CalMetaBackendInfo object infos which had been removed since the last check

Return type:

(bool, out_new_sync_tag: str, out_repeat: bool, out_created_objects: [EDataCal.CalMetaBackendInfo], out_modified_objects: [EDataCal.CalMetaBackendInfo], out_removed_objects: [EDataCal.CalMetaBackendInfo])

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 EDataCal.CalMetaBackendInfo ::object of the out_created_objects and out_modified_objects, if known, in which case this will be used instead of loading it with EDataCal.CalMetaBackend.load_component_sync().

It is optional to implement this virtual method by the descendant. The default implementation calls EDataCal.CalMetaBackend.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, EDataCal.CalMetaBackendInfo.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 EDataCal.CalMetaBackend.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_attachments_sync(component, cancellable)¶

Parameters:

component (ICalGLib.Component) – an ICalGLib.Component 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 attachments which point to a local file in component to inline attachments, aka adds the file content into the component. It also populates FILENAME parameter on the attachment. This is called automatically before EDataCal.CalMetaBackend.save_component_sync().

The reverse operation is EDataCal.CalMetaBackend.store_inline_attachments_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 EDataCal.CalMetaBackendInfo object infos which are stored on the remote side

Return type:

(bool, out_new_sync_tag: str, out_existing_objects: [EDataCal.CalMetaBackendInfo])

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 EDataCal.CalMetaBackendInfo ::object of the out_existing_objects, if known, in which case this will be used instead of loading it with EDataCal.CalMetaBackend.load_component_sync().

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

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

New in version 3.26.

load_component_sync(uid, extra, cancellable)¶

Parameters:

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

Raises:

GLib.Error

Returns:

Whether succeeded.

out_component:: a loaded component, as ICalGLib.Component
out_extra:: an extra data to store to EDataCal.CalCache with this component

Return type:

(bool, out_component: ICalGLib.Component, out_extra: str)

Loads a component from the remote side. Any detached instances should be returned together with the master object. The out_component can be either a VCALENDAR component, which would contain the master object and all of its detached instances, eventually also used time zones, or the requested component of type VEVENT, VJOURNAL or VTODO.

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

The returned out_component 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.

merge_instances(instances, replace_tzid_with_location)¶

Parameters:

instances ([ECal.Component]) – component instances to merge
replace_tzid_with_location (bool) – whether to replace TZID-s with locations

Returns:

an ICalGLib.Component containing a VCALENDAR component which consists of all the given instances. Free the returned pointer with GObject.Object.unref(), when no longer needed.

See: EDataCal.CalMetaBackend.save_component_sync()

Return type:

ICalGLib.Component

Merges all the instances provided in instances list into one VCALENDAR object, which would eventually contain also all the used timezones. The instances list should contain the master object and eventually all the detached instances for one component (they all have the same UID).

Any TZID property parameters can be replaced with corresponding timezone location, which will not influence the timezone itself.

New in version 3.26.

process_changes_sync(created_objects, modified_objects, removed_objects, cancellable)¶

Parameters:

created_objects ([EDataCal.CalMetaBackendInfo] or None) – a GLib.SList of EDataCal.CalMetaBackendInfo object infos which had been created
modified_objects ([EDataCal.CalMetaBackendInfo] or None) – a GLib.SList of EDataCal.CalMetaBackendInfo object infos which had been modified
removed_objects ([EDataCal.CalMetaBackendInfo] or None) – a GLib.SList of EDataCal.CalMetaBackendInfo 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 EDataCal.CalCache, which is used by self. Unref it with GObject.Object.unref() when no longer needed.
Return type:: EDataCal.CalCache

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 EDataCal.CalMetaBackend.schedule_refresh().

New in version 3.26.

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

Parameters:

conflict_resolution (EDataServer.ConflictResolution) – an EDataServer.ConflictResolution to use
uid (str) – a component UID
extra (str or None) – extra data being saved with the component in the local cache, or None
object (str or None) – corresponding iCalendar object, as stored in the local cache, or None
opflags (ECal.OperationFlags) – bit-or of ECal.OperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

Whether succeeded.

Return type:

bool

Removes a component from the remote side, with all its detached instances. 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 EDataCal.CalCache.

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_component_sync(overwrite_existing, conflict_resolution, instances, extra, opflags, cancellable)¶

Parameters:

overwrite_existing (bool) – True when can overwrite existing components, False otherwise
conflict_resolution (EDataServer.ConflictResolution) – one of EDataServer.ConflictResolution, what to do on conflicts
instances ([ECal.Component]) – instances of the component to save
extra (str or None) – extra data saved with the components in an EDataCal.CalCache
opflags (ECal.OperationFlags) – bit-or of ECal.OperationFlags
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 component
out_new_extra:: return location for the extra data to store with the component

Return type:

(bool, out_new_uid: str, out_new_extra: str)

Saves one component into the remote side. The instances contain the master object and all the detached instances of the same component (all have the same UID). 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 descendant can use EDataCal.CalMetaBackend.merge_instances() to merge the instances into one VCALENDAR component, which will contain also used time zones.

The components in instances have already converted locally stored attachments into inline attachments, thus it’s not needed to call EDataCal.CalMetaBackend.inline_local_attachments_sync() by the descendant.

The out_new_uid can be populated with a UID of the saved component 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 component by the remote side.

The out_new_extra can be populated with a new extra data to save with the component. 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 to 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 EDataCal.CalMetaBackend.refresh_sync() to refresh the self immediately.

New in version 3.26.

search_components_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_components:: return location for the found ECal.Component-s

Return type:

(bool, out_components: [ECal.Component])

Searches self with given expression expr and returns found components as a GLib.SList of ECal.Component out_components. Free the returned out_components with g_slist_free_full (components, GObject.Object.unref); when no longer needed. When the expr is None, all objects are returned. To get iCal strings instead, call EDataCal.CalMetaBackend.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.

search_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_icalstrings:: return location for the found components as iCal strings

Return type:

(bool, out_icalstrings: [str])

Searches self with given expression expr and returns found components as a GLib.SList of iCal strings out_icalstrings. Free the returned out_icalstrings with g_slist_free_full (icalstrings, GLib.free); when no longer needed. When the expr is None, all objects are returned. To get ECal.Component-s instead, call EDataCal.CalMetaBackend.search_components_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 (EDataCal.CalCache) – an EDataCal.CalCache to use

Sets the cache as the cache to be used by the self. By default, a cache.db in EDataCal.CalBackend ::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 EDataCal.CalMetaBackend.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.

set_sync_tag(sync_tag)¶

Parameters:: sync_tag (str or None) – a sync tag to set, or None to unset the old one

Sets the sync_tag for the self.

New in version 3.50.

split_changes_sync(objects, cancellable)¶

Parameters:

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

Raises:

GLib.Error

Returns:

Whether succeeded.

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

Return type:

(bool, objects: [EDataCal.CalMetaBackendInfo], out_created_objects: [EDataCal.CalMetaBackendInfo], out_modified_objects: [EDataCal.CalMetaBackendInfo], out_removed_objects: [EDataCal.CalMetaBackendInfo])

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, EDataCal.CalMetaBackendInfo.free); when no longer needed.

The caller is still responsible to free objects as well.

New in version 3.26.

store_inline_attachments_sync(component, cancellable)¶

Parameters:

component (ICalGLib.Component) – an ICalGLib.Component 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 attachments to URL attachments in component, which will point to a local file instead. The function expects FILENAME parameter to be set on the attachment as the file name of it. This is called automatically after EDataCal.CalMetaBackend.load_component_sync().

The reverse operation is EDataCal.CalMetaBackend.inline_local_attachments_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 EDataCal.CalBackend.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 EDataCal.CalMetaBackendInfo object infos which had been created since the last check
out_modified_objects:: a GLib.SList of EDataCal.CalMetaBackendInfo object infos which had been modified since the last check
out_removed_objects:: a GLib.SList of EDataCal.CalMetaBackendInfo object infos which had been removed since the last check

Return type:

(bool, out_new_sync_tag: str, out_repeat: bool, out_created_objects: [EDataCal.CalMetaBackendInfo], out_modified_objects: [EDataCal.CalMetaBackendInfo], out_removed_objects: [EDataCal.CalMetaBackendInfo])

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 EDataCal.CalMetaBackendInfo ::object of the out_created_objects and out_modified_objects, if known, in which case this will be used instead of loading it with EDataCal.CalMetaBackend.load_component_sync().

It is optional to implement this virtual method by the descendant. The default implementation calls EDataCal.CalMetaBackend.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, EDataCal.CalMetaBackendInfo.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 EDataCal.CalMetaBackendInfo object infos which are stored on the remote side

Return type:

(bool, out_new_sync_tag: str, out_existing_objects: [EDataCal.CalMetaBackendInfo])

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 EDataCal.CalMetaBackendInfo ::object of the out_existing_objects, if known, in which case this will be used instead of loading it with EDataCal.CalMetaBackend.load_component_sync().

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

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

New in version 3.26.

do_load_component_sync(uid, extra, cancellable) virtual¶

Parameters:

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

Returns:

Whether succeeded.

out_component:: a loaded component, as ICalGLib.Component
out_extra:: an extra data to store to EDataCal.CalCache with this component

Return type:

(bool, out_component: ICalGLib.Component, out_extra: str)

Loads a component from the remote side. Any detached instances should be returned together with the master object. The out_component can be either a VCALENDAR component, which would contain the master object and all of its detached instances, eventually also used time zones, or the requested component of type VEVENT, VJOURNAL or VTODO.

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

The returned out_component 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_component_sync(conflict_resolution, uid, extra, object, opflags, cancellable) virtual¶

Parameters:

conflict_resolution (EDataServer.ConflictResolution) – an EDataServer.ConflictResolution to use
uid (str) – a component UID
extra (str or None) – extra data being saved with the component in the local cache, or None
object (str or None) – corresponding iCalendar object, as stored in the local cache, or None
opflags (ECal.OperationFlags) – bit-or of ECal.OperationFlags
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Returns:

Whether succeeded.

Return type:

bool

Removes a component from the remote side, with all its detached instances. 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 EDataCal.CalCache.

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_component_sync(overwrite_existing, conflict_resolution, instances, extra, opflags, cancellable) virtual¶

Parameters:

overwrite_existing (bool) – True when can overwrite existing components, False otherwise
conflict_resolution (EDataServer.ConflictResolution) – one of EDataServer.ConflictResolution, what to do on conflicts
instances ([ECal.Component]) – instances of the component to save
extra (str or None) – extra data saved with the components in an EDataCal.CalCache
opflags (ECal.OperationFlags) – bit-or of ECal.OperationFlags
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 component
out_new_extra:: return location for the extra data to store with the component

Return type:

(bool, out_new_uid: str, out_new_extra: str)

Saves one component into the remote side. The instances contain the master object and all the detached instances of the same component (all have the same UID). 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 descendant can use EDataCal.CalMetaBackend.merge_instances() to merge the instances into one VCALENDAR component, which will contain also used time zones.

The components in instances have already converted locally stored attachments into inline attachments, thus it’s not needed to call EDataCal.CalMetaBackend.inline_local_attachments_sync() by the descendant.

The out_new_uid can be populated with a UID of the saved component 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 component by the remote side.

The out_new_extra can be populated with a new extra data to save with the component. 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 to 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_components_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_components:: return location for the found ECal.Component-s

Return type:

(bool, out_components: [ECal.Component])

Searches meta_backend with given expression expr and returns found components as a GLib.SList of ECal.Component out_components. Free the returned out_components with g_slist_free_full (components, GObject.Object.unref); when no longer needed. When the expr is None, all objects are returned. To get iCal strings instead, call EDataCal.CalMetaBackend.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_search_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_icalstrings:: return location for the found components as iCal strings

Return type:

(bool, out_icalstrings: [str])

Searches meta_backend with given expression expr and returns found components as a GLib.SList of iCal strings out_icalstrings. Free the returned out_icalstrings with g_slist_free_full (icalstrings, GLib.free); when no longer needed. When the expr is None, all objects are returned. To get ECal.Component-s instead, call EDataCal.CalMetaBackend.search_components_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¶

EDataCal.CalMetaBackend.signals.refresh_completed(cal_meta_backend)¶

Signal Name:: refresh-completed
Flags:: RUN_LAST
Parameters:: cal_meta_backend (EDataCal.CalMetaBackend) – The object which received the signal

EDataCal.CalMetaBackend.signals.source_changed(cal_meta_backend)¶

Signal Name:: source-changed
Flags:: RUN_LAST
Parameters:: cal_meta_backend (EDataCal.CalMetaBackend) – 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 EDataCal.CalMetaBackend itself and is emitted from a dedicated thread, thus it doesn’t block the main thread.

New in version 3.26.

Property Details¶

EDataCal.CalMetaBackend.props.cache¶

Name:: cache
Type:: EDataCal.CalCache
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The EDataCal.CalCache being used for this meta backend.