EBackend.CollectionBackend¶

Subclasses:	`EBackend.WebDAVCollectionBackend`

Methods¶

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

	`authenticate_children` (credentials)
	`claim_all_resources` ()
	`create_resource` (source, cancellable, callback, *user_data)
	`create_resource_finish` (result)
	`create_resource_sync` (source, cancellable)
	`delete_resource` (source, cancellable, callback, *user_data)
	`delete_resource_finish` (result)
	`delete_resource_sync` (source, cancellable)
	`dup_resource_id` (child_source)
	`freeze_populate` ()
	`get_cache_dir` ()
	`get_part_enabled` (parts)
	`get_populate_frozen` ()
	`is_new_source` (source)
	`list_calendar_sources` ()
	`list_contacts_sources` ()
	`list_mail_sources` ()
	`new_child` (resource_id)
	`ref_proxy_resolver` ()
	`ref_server` ()
	`schedule_populate` ()
	`thaw_populate` ()

Virtual Methods¶

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

	`do_child_added` (child_source)
	`do_child_removed` (child_source)
	`do_create_resource` (source, cancellable, callback, *user_data)
	`do_create_resource_finish` (result)
	`do_create_resource_sync` (source, cancellable)
	`do_delete_resource` (source, cancellable, callback, *user_data)
	`do_delete_resource_finish` (result)
	`do_delete_resource_sync` (source, cancellable)
	`do_dup_resource_id` (child_source)
	`do_populate` ()

Properties¶

Inherited:	EBackend.Backend (5)

Name	Type	Flags	Short Description
`proxy-resolver`	`Gio.ProxyResolver`	r	The proxy resolver for this backend
`server`	`EBackend.SourceRegistryServer`	r/w/co	The server to which the backend belongs

Signals¶

Inherited:	GObject.Object (1)

Name	Short Description
`child-added`	Emitted when an `EBackend.ServerSideSource` is added to backend’s `EBackend.CollectionBackend` `:server` as a child of backend’s collection `EBackend.Backend` `:source`.
`child-removed`	Emitted when an `EBackend.ServerSideSource` that is a child of backend’s collection `EBackend.Backend` `:source` is removed from backend’s `EBackend.CollectionBackend` `:server`.

Fields¶

Inherited:	GObject.Object (1)

Name	Type	Access	Description
parent	`EBackend.Backend`	r

Class Details¶

class EBackend.CollectionBackend(**kwargs)¶

Bases:	`EBackend.Backend`
Abstract:	No
Structure:	`EBackend.CollectionBackendClass`

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

New in version 3.6.

authenticate_children(credentials)¶

Parameters:	credentials (`EDataServer.NamedParameters`) – credentials to authenticate with

Authenticates all enabled children sources with the given crendetials. This is usually called when the collection source successfully used the credentials to connect to the (possibly) remote data store, to open the childern too. Already connected child sources are skipped.

New in version 3.16.

claim_all_resources()¶

Returns:	a list of previously used sources
Return type:	[`EDataServer.Source`]

Claims all previously used sources that have not yet been claimed by EBackend.CollectionBackend.new_child() and returns them in a GLib.List. Note that previously used sources can only be claimed once, so subsequent calls to this function for self will return None.

The self is then expected to compare the returned list with a current list of resources from a remote server, create new EDataServer.Source instances as needed with EBackend.CollectionBackend.new_child(), discard unneeded EDataServer.Source instances with EDataServer.Source.remove(), and export the remaining instances with EBackend.SourceRegistryServer.add_source().

The sources 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 GLib.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.6.

create_resource(source, cancellable, callback, *user_data)¶

Parameters:	source (`EDataServer.Source`) – an `EDataServer.Source` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously creates a server-side resource described by source. For example, if source describes a new calendar, an equivalent calendar is created on the server.

It is the implementor’s responsibility to examine source and determine what the equivalent server-side resource would be. If this cannot be determined without ambiguity, the function must return an error.

After the server-side resource is successfully created, the implementor must also add an EDataServer.Source to self’s EBackend.CollectionBackend :server. This can either be done immediately or in response to some “resource created” notification from the server. The added EDataServer.Source can be source itself or a different EDataServer.Source instance that describes the new resource.

When the operation is finished, callback will be called. You can then call EBackend.CollectionBackend.create_resource_finish() to get the result of the operation.

New in version 3.6.

create_resource_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 EBackend.CollectionBackend.create_resource().

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

New in version 3.6.

create_resource_sync(source, cancellable)¶

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

Creates a server-side resource described by source. For example, if source describes a new calendar, an equivalent calendar is created on the server.

It is the implementor’s responsibility to examine source and determine what the equivalent server-side resource would be. If this cannot be determined without ambiguity, the function must return an error.

After the server-side resource is successfully created, the implementor must also add an EDataServer.Source to self’s EBackend.CollectionBackend :server. This can either be done immediately or in response to some “resource created” notification from the server. The added EDataServer.Source can be source itself or a different EDataServer.Source instance that describes the new resource.

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

New in version 3.6.

delete_resource(source, cancellable, callback, *user_data)¶

Parameters:	source (`EDataServer.Source`) – an `EDataServer.Source` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously deletes a server-side resource described by source. The source must be a child of self’s collection EBackend.Backend :source.

After the server-side resource is successfully deleted, the implementor must also remove source from the self’s EBackend.CollectionBackend :server. This can either be done immediately or in response to some “resource deleted” notification from the server.

When the operation is finished, callback will be called. You can then call EBackend.CollectionBackend.delete_resource_finish() to get the result of the operation.

New in version 3.6.

delete_resource_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 EBackend.CollectionBackend.delete_resource().

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

New in version 3.6.

delete_resource_sync(source, cancellable)¶

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

Deletes a server-side resource described by source. The source must be a child of self’s collection EBackend.Backend :source.

After the server-side resource is successfully deleted, the implementor must also remove source from the self’s EBackend.CollectionBackend :server. This can either be done immediately or in response to some “resource deleted” notification from the server.

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

New in version 3.6.

dup_resource_id(child_source)¶

Parameters:	child_source (`EDataServer.Source`) – an `EDataServer.Source` managed by self
Returns:	a newly-allocated resource ID for child_source, or `None`
Return type:	`str`

Extracts the resource ID for child_source, which is supposed to be a stable and unique server-assigned identifier for the remote resource described by child_source. If child_source is not actually a child of the collection EBackend.Backend :source owned by self, the function returns None.

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

New in version 3.6.

freeze_populate()¶

Returns:	`True`, when this is the first freeze call
Return type:	`bool`

Freezes populate of the backend’s content. This is used to avoid calling populate multiple times in parallel. Every call to this function should be followed by the call of EBackend.CollectionBackend.thaw_populate() to reverse the effect of this function, regardless of the return value of this function.

New in version 3.38.

get_cache_dir()¶

Returns:	the cache directory for self
Return type:	`str`

Returns the private cache directory path for self, which is named after the EDataServer.Source :uid of self’s collection EBackend.Backend :source.

The cache directory is meant to store key files for backend-created data sources. See also: EBackend.ServerSideSource.set_write_directory()

New in version 3.6.

get_part_enabled(parts)¶

Parameters:	parts (`EBackend.CollectionBackendParts`) – a bit-or of `EBackend.CollectionBackendParts` with parts to be checked
Returns:	`True`, when at least one of the parts is enabled and the backend’s `EDataServer.Source` is enabled as well.
Return type:	`bool`

Checks whether the self has enabled at least of the parts.

New in version 3.38.3.

get_populate_frozen()¶

Returns:	Whether the backend has currently frozen (disabled) populate of its content.
Return type:	`bool`

New in version 3.38.

is_new_source(source)¶

Parameters:	source (`EDataServer.Source`) – a child `EDataServer.Source`
Returns:	`True`, when the source is a new child; `False` when it had been known before.
Return type:	`bool`

Returns whether the source is a newly created child or not. New sources are remembered between two populate calls only.

New in version 3.32.

list_calendar_sources()¶

Returns:	a list of calendar sources
Return type:	[`EDataServer.Source`]

Returns a list of calendar sources belonging to the data source collection managed by self.

The sources 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 GLib.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.6.

list_contacts_sources()¶

Returns:	a list of address book sources
Return type:	[`EDataServer.Source`]

Returns a list of address book sources belonging to the data source collection managed by self.

The sources 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 GLib.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.6.

list_mail_sources()¶

Returns:	a list of mail sources
Return type:	[`EDataServer.Source`]

Returns a list of mail sources belonging to the data source collection managed by self.

The sources 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 GLib.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.6.

new_child(resource_id)¶

Parameters:	resource_id (`str`) – a stable and unique resource ID
Returns:	a newly-created data source
Return type:	`EDataServer.Source`

Creates a new EBackend.ServerSideSource as a child of the collection EBackend.Backend :source owned by self. If possible, the EBackend.ServerSideSource is drawn from a cache of previously used sources indexed by resource_id so that locally cached data from previous sessions can be reused.

The returned data source should be passed to EBackend.SourceRegistryServer.add_source() to export it over D-Bus.

New in version 3.6.

ref_proxy_resolver()¶

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

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

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

New in version 3.12.

ref_server()¶

Returns:	the `EBackend.SourceRegistryServer` for self
Return type:	`EBackend.SourceRegistryServer`

Returns the EBackend.SourceRegistryServer to which self belongs.

The returned EBackend.SourceRegistryServer is referenced for thread-safety. Unreference the EBackend.SourceRegistryServer with GObject.Object.unref() when finished with it.

New in version 3.6.

schedule_populate()¶: Schedules a call to populate() of the self on idle. The function does nothing in case the self is offline.

New in version 3.30.

thaw_populate()¶: Thaws populate of the backend’s content. This is a pair function for EBackend.CollectionBackend.freeze_populate().

New in version 3.38.

do_child_added(child_source) virtual¶

Parameters:	child_source (`EDataServer.Source`) –

do_child_removed(child_source) virtual¶

Parameters:	child_source (`EDataServer.Source`) –

do_create_resource(source, cancellable, callback, *user_data) virtual¶

Parameters:	source (`EDataServer.Source`) – an `EDataServer.Source` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously creates a server-side resource described by source. For example, if source describes a new calendar, an equivalent calendar is created on the server.

It is the implementor’s responsibility to examine source and determine what the equivalent server-side resource would be. If this cannot be determined without ambiguity, the function must return an error.

After the server-side resource is successfully created, the implementor must also add an EDataServer.Source to backend’s EBackend.CollectionBackend :server. This can either be done immediately or in response to some “resource created” notification from the server. The added EDataServer.Source can be source itself or a different EDataServer.Source instance that describes the new resource.

When the operation is finished, callback will be called. You can then call EBackend.CollectionBackend.create_resource_finish() to get the result of the operation.

New in version 3.6.

do_create_resource_finish(result) virtual¶

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

Finishes the operation started with EBackend.CollectionBackend.create_resource().

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

New in version 3.6.

do_create_resource_sync(source, cancellable) virtual¶

Parameters:	source (`EDataServer.Source`) – an `EDataServer.Source` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` on success, `False` on failure
Return type:	`bool`

Creates a server-side resource described by source. For example, if source describes a new calendar, an equivalent calendar is created on the server.

It is the implementor’s responsibility to examine source and determine what the equivalent server-side resource would be. If this cannot be determined without ambiguity, the function must return an error.

After the server-side resource is successfully created, the implementor must also add an EDataServer.Source to backend’s EBackend.CollectionBackend :server. This can either be done immediately or in response to some “resource created” notification from the server. The added EDataServer.Source can be source itself or a different EDataServer.Source instance that describes the new resource.

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

New in version 3.6.

do_delete_resource(source, cancellable, callback, *user_data) virtual¶

Parameters:	source (`EDataServer.Source`) – an `EDataServer.Source` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None` callback (`Gio.AsyncReadyCallback` or `None`) – a `Gio.AsyncReadyCallback` to call when the request is satisfied user_data (`object` or `None`) – data to pass to the callback function

Asynchronously deletes a server-side resource described by source. The source must be a child of backend’s collection EBackend.Backend :source.

After the server-side resource is successfully deleted, the implementor must also remove source from the backend’s EBackend.CollectionBackend :server. This can either be done immediately or in response to some “resource deleted” notification from the server.

When the operation is finished, callback will be called. You can then call EBackend.CollectionBackend.delete_resource_finish() to get the result of the operation.

New in version 3.6.

do_delete_resource_finish(result) virtual¶

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

Finishes the operation started with EBackend.CollectionBackend.delete_resource().

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

New in version 3.6.

do_delete_resource_sync(source, cancellable) virtual¶

Parameters:	source (`EDataServer.Source`) – an `EDataServer.Source` cancellable (`Gio.Cancellable` or `None`) – optional `Gio.Cancellable` object, or `None`
Returns:	`True` on success, `False` on failure
Return type:	`bool`

Deletes a server-side resource described by source. The source must be a child of backend’s collection EBackend.Backend :source.

After the server-side resource is successfully deleted, the implementor must also remove source from the backend’s EBackend.CollectionBackend :server. This can either be done immediately or in response to some “resource deleted” notification from the server.

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

New in version 3.6.

do_dup_resource_id(child_source) virtual¶

Parameters:	child_source (`EDataServer.Source`) – an `EDataServer.Source` managed by backend
Returns:	a newly-allocated resource ID for child_source, or `None`
Return type:	`str`

Extracts the resource ID for child_source, which is supposed to be a stable and unique server-assigned identifier for the remote resource described by child_source. If child_source is not actually a child of the collection EBackend.Backend :source owned by backend, the function returns None.

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

New in version 3.6.

do_populate() virtual¶

Signal Details¶

EBackend.CollectionBackend.signals.child_added(collection_backend, child_source)¶

Signal Name:	`child-added`
Flags:	`RUN_LAST`
Parameters:	collection_backend (`EBackend.CollectionBackend`) – The object which received the signal child_source (`EBackend.ServerSideSource`) – the newly-added child `EBackend.ServerSideSource`

Emitted when an EBackend.ServerSideSource is added to backend’s EBackend.CollectionBackend :server as a child of backend’s collection EBackend.Backend :source.

You can think of this as a filtered version of EBackend.SourceRegistryServer’s EBackend.SourceRegistryServer ::source-added signal which only lets through sources relevant to backend.

EBackend.CollectionBackend.signals.child_removed(collection_backend, child_source)¶

Signal Name:	`child-removed`
Flags:	`RUN_LAST`
Parameters:	collection_backend (`EBackend.CollectionBackend`) – The object which received the signal child_source (`EBackend.ServerSideSource`) – the child `EBackend.ServerSideSource` that got removed

Emitted when an EBackend.ServerSideSource that is a child of backend’s collection EBackend.Backend :source is removed from backend’s EBackend.CollectionBackend :server.

You can think of this as a filtered version of EBackend.SourceRegistryServer’s EBackend.SourceRegistryServer ::source-removed signal which only lets through sources relevant to backend.

Property Details¶

EBackend.CollectionBackend.props.proxy_resolver¶

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

The proxy resolver for this backend

EBackend.CollectionBackend.props.server¶

Name:	`server`
Type:	`EBackend.SourceRegistryServer`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The server to which the backend belongs