EBackend.SourceRegistryServer¶

Subclasses:: None

Methods¶

Inherited:: EBackend.DataFactory (12), EBackend.DBusServer (5), GObject.Object (37), EDataServer.Extensible (3), Gio.Initable (2), EBackend.OAuth2Support (3)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`add_source` (source)
	`find_extension` (source, extension_name)
	`get_oauth2_services` ()
	`list_sources` (extension_name)
	`load_directory` (path, flags)
	`load_error` (file, error)
	`load_file` (file, flags)
	`load_resource` (resource, path, flags)
	`ref_backend` (source)
	`ref_backend_factory` (source)
	`ref_credentials_provider` ()
	`ref_oauth2_support` ()
	`ref_source` (uid)
	`remove_source` (source)

Virtual Methods¶

Inherited:: EBackend.DataFactory (3), EBackend.DBusServer (5), GObject.Object (7), Gio.Initable (1), EBackend.OAuth2Support (3)

	`do_files_loaded` ()
	`do_load_error` (file, error)
	`do_source_added` (source)
	`do_source_removed` (source)
	`do_tweak_key_file` (key_file, uid)

Properties¶

Inherited:: EBackend.DataFactory (3)

Signals¶

Inherited:: EBackend.DBusServer (5), GObject.Object (1)

Name	Short Description
`files-loaded`	Emitted after all data source key files are loaded on startup.
`load-error`	Emitted when an error occurs while loading or parsing a data source key file.
`source-added`	Emitted when an `EBackend.ServerSideSource` is added to server.
`source-removed`	Emitted when an `EBackend.ServerSideSource` is removed from server.
`tweak-key-file`	Emitted from `EBackend.SourceRegistryServer.load_file`() just prior to instantiating an `EBackend.ServerSideSource`.

Fields¶

Inherited:: EBackend.DBusServer (5), GObject.Object (1)

Name	Type	Access	Description
parent	`EBackend.DataFactory`	r

Class Details¶

class EBackend.SourceRegistryServer(**kwargs)¶

Bases:: EBackend.DataFactory, EBackend.OAuth2Support
Abstract:: No
Structure:: EBackend.SourceRegistryServerClass

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

New in version 3.6.

classmethod new()¶

Returns:: a new instance of EBackend.SourceRegistryServer
Return type:: EBackend.DBusServer

Creates a new instance of EBackend.SourceRegistryServer.

New in version 3.6.

add_source(source)¶

Parameters:: source (EDataServer.Source) – an EDataServer.Source

Adds source to self.

New in version 3.6.

find_extension(source, extension_name)¶

Parameters:

source (EDataServer.Source) – an EDataServer.Source
extension_name (str) – the extension name to find

Returns:

an EDataServer.Source, or None if no match was found

Return type:

EDataServer.Source or None

Examines source and its ancestors and returns the “deepest” EDataServer.Source having an EDataServer.SourceExtension with the given extension_name. If neither source nor any of its ancestors have such an extension, the function returns None.

This function is useful in cases when an EDataServer.SourceExtension is meant to apply to both the EDataServer.Source it belongs to and the EDataServer.Source's descendants.

A common example is the EDataServer.SourceCollection extension, where descendants of an EDataServer.Source having an EDataServer.SourceCollection extension are implied to be members of that collection. In that example, this function can be used to test whether source is a member of a collection.

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

Note the function returns the EDataServer.Source containing the EDataServer.SourceExtension instead of the EDataServer.SourceExtension itself because extension instances are not to be referenced directly (see EDataServer.Source.get_extension()).

New in version 3.8.

get_oauth2_services()¶

Returns:: an EDataServer.OAuth2Services instance owned by self
Return type:: EDataServer.OAuth2Services

New in version 3.28.

list_sources(extension_name)¶

Parameters:: extension_name (str or None) – an extension name, or None
Returns:: a sorted list of sources
Return type:: [EDataServer.Source]

Returns a list of registered sources, sorted by display name. If extension_name is given, restrict the list to sources having that extension name.

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.

load_directory(path, flags)¶

Parameters:

path (str) – the path to the directory to load
flags (EBackend.SourcePermissionFlags) – permission flags for files loaded from path

Raises:

GLib.Error

Returns:

True if path was successfully opened, but this does not imply the key files were successfully loaded

Return type:

bool

Loads data source key files in path. Because multiple errors can occur when loading multiple files, error is only set if path can not be opened. If a key file fails to load, the error is broadcast through the EBackend.SourceRegistryServer ::load-error signal.

If the EBackend.SourcePermissionFlags.REMOVABLE flag is given, then the self will emit signals on the D-Bus interface when key files are created or deleted in path.

New in version 3.6.

load_error(file, error)¶

Parameters:

file (Gio.File) – the Gio.File that failed to load
error (GLib.Error) – a GLib.Error describing the load error

Emits the EBackend.SourceRegistryServer ::load-error signal.

New in version 3.6.

load_file(file, flags)¶

Parameters:

file (Gio.File) – the data source key file to load
flags (EBackend.SourcePermissionFlags) – initial permission flags for the data source

Raises:

GLib.Error

Returns:

the newly-added EDataServer.Source, or None on error

Return type:

EDataServer.Source or None

Creates an EDataServer.Source for a native key file and adds it to self. If an error occurs, the function returns None and sets error.

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

New in version 3.6.

load_resource(resource, path, flags)¶

Parameters:

resource (Gio.Resource) – a Gio.Resource containing data source key files
path (str) – the path to the data source key files inside resource
flags (EBackend.SourcePermissionFlags) – permission flags for files loaded from path

Raises:

GLib.Error

Returns:

True if path was successfully located, but this does not imply the key files were successfully loaded

Return type:

bool

Loads data source key files from resource by enumerating the children at path and calling EBackend.SourceRegistryServer.load_file() on each child. Because multiple errors can occur when loading multiple files, error is only set if path is invalid. If a key file fails to load, the error is broadcast through the EBackend.SourceRegistryServer ::load-error signal.

New in version 3.8.

ref_backend(source)¶

Parameters:: source (EDataServer.Source) – an EDataServer.Source
Returns:: the EBackend.CollectionBackend for source, or None
Return type:: EBackend.CollectionBackend or None

Returns the EBackend.CollectionBackend associated with source, or None if there is no EBackend.CollectionBackend associated with source.

An EDataServer.Source is associated with an EBackend.CollectionBackend if the EDataServer.Source has an EDataServer.SourceCollection extension, or if it is a hierarchical descendant of another EDataServer.Source which has an EDataServer.SourceCollection extension.

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

New in version 3.6.

ref_backend_factory(source)¶

Parameters:: source (EDataServer.Source) – an EDataServer.Source
Returns:: the EBackend.CollectionBackendFactory for source, or None
Return type:: EBackend.CollectionBackendFactory or None

Returns the EBackend.CollectionBackendFactory for source, if available. If source does not have an EDataServer.SourceCollection extension, or if the EDataServer.SourceCollection extension names an EDataServer.SourceBackend :backend-name for which there is no corresponding EBackend.CollectionBackendFactory, the function returns None.

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

New in version 3.6.

ref_credentials_provider()¶

Returns:: A referenced EDataServer.SourceCredentialsProvider.
Return type:: EDataServer.SourceCredentialsProvider

Returns a referenced EDataServer.SourceCredentialsProvider. Unref it with GObject.Object.unref(), when no longer needed.

New in version 3.16.

ref_oauth2_support()¶

Returns:: the default EBackend.OAuth2Support, or None, when none exists
Return type:: EBackend.OAuth2Support or None

Returns the default EBackend.OAuth2Support implementation, which can be used when the source doesn’t have it overwritten.

Free the returned object with GObject.Object.unref(), when no longer needed.

New in version 3.40.

ref_source(uid)¶

Parameters:: uid (str) – a unique identifier string
Returns:: an EDataServer.Source, or None if no match was found
Return type:: EDataServer.Source or None

Looks up an EDataServer.Source in self by its unique identifier string.

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

New in version 3.6.

remove_source(source)¶

Parameters:: source (EDataServer.Source) – an EDataServer.Source

Removes source and all of its descendants from self.

New in version 3.6.

do_files_loaded() virtual¶

do_load_error(file, error) virtual¶

Parameters:

file (Gio.File) – the Gio.File that failed to load
error (GLib.Error) – a GLib.Error describing the load error

Emits the EBackend.SourceRegistryServer ::load-error signal.

New in version 3.6.

do_source_added(source) virtual¶

Parameters:: source (EDataServer.Source) –

do_source_removed(source) virtual¶

Parameters:: source (EDataServer.Source) –

do_tweak_key_file(key_file, uid) virtual¶

Parameters:

key_file (GLib.KeyFile) –
uid (str) –

Return type:

bool

Signal Details¶

EBackend.SourceRegistryServer.signals.files_loaded(source_registry_server)¶

Signal Name:: files-loaded
Flags:: RUN_LAST
Parameters:: source_registry_server (EBackend.SourceRegistryServer) – The object which received the signal

Emitted after all data source key files are loaded on startup. Extensions can connect to this signal to perform any additional work prior to running the main loop.

EBackend.SourceRegistryServer.signals.load_error(source_registry_server, file, error)¶

Signal Name:

load-error

Flags:

RUN_LAST

Parameters:

source_registry_server (EBackend.SourceRegistryServer) – The object which received the signal
file (Gio.File) – the Gio.File being loaded
error (GLib.Error) – a GLib.Error describing the error

Emitted when an error occurs while loading or parsing a data source key file.

EBackend.SourceRegistryServer.signals.source_added(source_registry_server, source)¶

Signal Name:

source-added

Flags:

RUN_LAST

Parameters:

source_registry_server (EBackend.SourceRegistryServer) – The object which received the signal
source (EBackend.ServerSideSource) – the newly-added EBackend.ServerSideSource

Emitted when an EBackend.ServerSideSource is added to server.

EBackend.SourceRegistryServer.signals.source_removed(source_registry_server, source)¶

Signal Name:

source-removed

Flags:

RUN_LAST

Parameters:

source_registry_server (EBackend.SourceRegistryServer) – The object which received the signal
source (EBackend.ServerSideSource) – the EBackend.ServerSideSource that got removed

Emitted when an EBackend.ServerSideSource is removed from server.

EBackend.SourceRegistryServer.signals.tweak_key_file(source_registry_server, key_file, uid)¶

Signal Name:

tweak-key-file

Flags:

RUN_LAST

Parameters:

source_registry_server (EBackend.SourceRegistryServer) – The object which received the signal
key_file (GLib.KeyFile) – a GLib.KeyFile
uid (str) – a unique identifier string for key_file

Returns:

True if key_file was modified, False otherwise

Return type:

bool

Emitted from EBackend.SourceRegistryServer.load_file() just prior to instantiating an EBackend.ServerSideSource. Signal handlers can tweak the key_file content as necessary and return True to write the modified content back to disk.

For the purposes of tweaking, it’s easier to deal with a plain GLib.KeyFile than an EDataServer.Source instance. An EDataServer.Source, for example, does not allow key file groups to be removed.

The return value is cumulative. If any signal handler returns True, the key_file content is written back to disk.

New in version 3.8.