EBackend.CollectionBackend¶

Subclasses:: EBackend.WebDAVCollectionBackend

Methods¶

Inherited:: EBackend.Backend (21), 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] or None

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 or None

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.40.

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 or None

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