EBackend.Backend¶

Subclasses:: EBackend.CollectionBackend

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

	`credentials_required` (reason, certificate_pem, certificate_errors, op_error, cancellable, callback, *user_data)
	`credentials_required_finish` (result)
	`credentials_required_sync` (reason, certificate_pem, certificate_errors, op_error, cancellable)
	`ensure_online_state_updated` (cancellable)
	`ensure_source_status_connected` ()
	`get_destination_address` ()
	`get_network_monitor` ()
	`get_online` ()
	`get_source` ()
	`get_user_prompter` ()
	`is_destination_reachable` (cancellable)
	`prepare_shutdown` ()
	`ref_connectable` ()
	`ref_main_context` ()
	`schedule_authenticate` (credentials)
	`schedule_credentials_required` (reason, certificate_pem, certificate_errors, op_error, cancellable, who_calls)
	`set_connectable` (connectable)
	`set_online` (online)
	`trust_prompt` (parameters, cancellable, callback, *user_data)
	`trust_prompt_finish` (result)
	`trust_prompt_sync` (parameters, cancellable)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_authenticate_sync` (credentials, out_certificate_pem, out_certificate_errors, cancellable)
	`do_get_destination_address` ()
	`do_prepare_shutdown` ()

Properties¶

Name	Type	Flags	Short Description
`connectable`	`Gio.SocketConnectable`	r/w/en	Socket endpoint of a network service
`main-context`	`GLib.MainContext`	r	The main loop context on which to attach event sources
`online`	`bool`	r/w/en	Whether the backend is online
`source`	`EDataServer.Source`	r/w/co	The data source being acted upon
`user-prompter`	`EBackend.UserPrompter`	r	User prompter instance

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class EBackend.Backend(**kwargs)¶

Bases:: GObject.Object
Abstract:: Yes
Structure:: EBackend.BackendClass

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

New in version 3.4.

credentials_required(reason, certificate_pem, certificate_errors, op_error, cancellable, callback, *user_data)¶

Parameters:

reason (EDataServer.SourceCredentialsReason) – an EDataServer.SourceCredentialsReason, why the credentials are required
certificate_pem (str) – PEM-encoded secure connection certificate, or an empty string
certificate_errors (Gio.TlsCertificateFlags) – a bit-or of Gio.TlsCertificateFlags for secure connection certificate
op_error (GLib.Error or None) – a GLib.Error with a description of the previous credentials error, or None
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 calls the EBackend.Backend.credentials_required_sync() on the self, to inform clients that credentials are required.

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

New in version 3.16.

credentials_required_finish(result)¶

Parameters:: result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:: GLib.Error
Returns:: True on success, False on error
Return type:: bool

Finishes the operation started with EBackend.Backend.credentials_required().

If an error occurs, the function sets error and returns False.

New in version 3.16.

credentials_required_sync(reason, certificate_pem, certificate_errors, op_error, cancellable)¶

Parameters:

reason (EDataServer.SourceCredentialsReason) – an EDataServer.SourceCredentialsReason, why the credentials are required
certificate_pem (str) – PEM-encoded secure connection certificate, or an empty string
certificate_errors (Gio.TlsCertificateFlags) – a bit-or of Gio.TlsCertificateFlags for secure connection certificate
op_error (GLib.Error or None) – a GLib.Error with a description of the previous credentials error, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

True on success, False on error

Return type:

bool

Synchronously lets the clients know that the backned requires credentials to be properly opened. It’s a proxy function for EDataServer.Source.invoke_credentials_required_sync(), where can be found more information about actual parameters meaning.

The provided credentials are received through EBackend.Backend.do_authenticate_sync() method asynchronously.

If an error occurs, the function sets error and returns False.

New in version 3.16.

ensure_online_state_updated(cancellable)¶

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

Makes sure that the “online” property is updated, that is, if there is any destination reachability test pending, it’ll be done immediately and the only state will be updated as well.

New in version 3.18.

ensure_source_status_connected()¶: Makes sure that the associated EDataServer.Source ::connection-status is connected. This is useful in cases when the backend can connect to the destination without invoking EBackend.Backend.do_authenticate_sync(), possibly through EBackend.Backend.schedule_authenticate().

New in version 3.18.

get_destination_address()¶

Returns:

True, when it’s a remote backend and provides both host and port; False otherwise.

host:: destination server host name
port:: destination server port

Return type:

(bool, host: str, port: int)

Provides destination server host name and port to which the backend connects. This is used to determine required connection point for EBackend.Backend.is_destination_reachable(). The host is a newly allocated string, which will be freed with GLib.free(). When self sets both host and port, then it should return True, indicating it’s a remote backend. Default implementation returns False, which is treated like the backend is local, no checking for server reachability is possible.

New in version 3.8.

get_network_monitor()¶

Returns:: a Gio.NetworkMonitor used by the self
Return type:: Gio.NetworkMonitor

Returns a Gio.NetworkMonitor used to check whether the backend can access the remote server. The instance is owned by the self.

New in version 3.50.

get_online()¶

Returns:: the online state
Return type:: bool

Returns the online state of self: True if self is online, False if offline.

If the EBackend.Backend :connectable property is non-None, the self will automatically determine whether the network service should be reachable, and hence whether the self is EBackend.Backend :online. But subclasses may override the online state if, for example, a connection attempt fails.

New in version 3.4.

get_source()¶

Returns:: the EDataServer.Source to which self is paired
Return type:: EDataServer.Source

Returns the EDataServer.Source to which self is paired.

New in version 3.4.

get_user_prompter()¶

Returns:: an EBackend.UserPrompter instance
Return type:: object or None

Gets an instance of EBackend.UserPrompter, associated with this self.

The returned instance is owned by the self.

New in version 3.8.

is_destination_reachable(cancellable)¶

Parameters:: cancellable (Gio.Cancellable or None) – a Gio.Cancellable instance, or None
Raises:: GLib.Error
Returns:: True, when destination server address is reachable or the backend doesn’t provide destination address; False if the backend destination server cannot be reached currently.
Return type:: bool

Checks whether the self ‘s destination server, as returned by EBackend.Backend.get_destination_address(), is reachable. If the EBackend.Backend.get_destination_address() returns False, this function returns True, meaning the destination is always reachable. This uses Gio.NetworkMonitor ‘s Gio.NetworkMonitor.can_reach() for reachability tests.

New in version 3.8.

prepare_shutdown()¶: Let’s the self know that it’ll be shut down shortly, no client connects to it anymore. The self can free any resources which reference it, for example the opened views.

New in version 3.16.

ref_connectable()¶

Returns:: a Gio.SocketConnectable, or None
Return type:: Gio.SocketConnectable or None

Returns the socket endpoint for the network service to which self is a client, or None if self does not use network sockets.

The initial value of the EBackend.Backend :connectable property is derived from the EDataServer.SourceAuthentication extension of the self's EBackend.Backend :source property, if the extension is present.

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

New in version 3.8.

ref_main_context()¶

Returns:: a GLib.MainContext
Return type:: GLib.MainContext

Returns the GLib.MainContext on which event sources for self are to be attached.

The returned GLib.MainContext is referenced for thread-safety and must be unreferenced with GLib.MainContext.unref() when finished with it.

New in version 3.8.

schedule_authenticate(credentials)¶

Parameters:: credentials (EDataServer.NamedParameters or None) – a credentials to use to authenticate, or None

Schedules a new authenticate session, cancelling any previously run. This is usually done automatically, when an ‘authenticate’ signal is received for the associated EDataServer.Source. With None credentials an attempt without it is run.

New in version 3.16.

schedule_credentials_required(reason, certificate_pem, certificate_errors, op_error, cancellable, who_calls)¶

Parameters:

reason (EDataServer.SourceCredentialsReason) – an EDataServer.SourceCredentialsReason, why the credentials are required
certificate_pem (str) – PEM-encoded secure connection certificate, or an empty string
certificate_errors (Gio.TlsCertificateFlags) – a bit-or of Gio.TlsCertificateFlags for secure connection certificate
op_error (GLib.Error or None) – a GLib.Error with a description of the previous credentials error, or None
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
who_calls (str or None) – an identification who calls this

Asynchronously invokes EBackend.Backend.credentials_required(), but installs its own callback which only prints a runtime warning on the console when the call fails. The who_calls is a prefix of the console message. This is useful when the caller just wants to start the operation without having actual place where to show the operation result.

New in version 3.16.

set_connectable(connectable)¶

Parameters:: connectable (Gio.SocketConnectable) – a Gio.SocketConnectable, or None

Sets the socket endpoint for the network service to which self is a client. This can be None if self does not use network sockets.

The initial value of the EBackend.Backend :connectable property is derived from the EDataServer.SourceAuthentication extension of the self's EBackend.Backend :source property, if the extension is present.

New in version 3.8.

set_online(online)¶

Parameters:: online (bool) – the online state

Sets the online state of self: True if self is online, False if offline.

If the EBackend.Backend :connectable property is non-None, the self will automatically determine whether the network service should be reachable, and hence whether the self is EBackend.Backend :online. But subclasses may override the online state if, for example, a connection attempt fails.

New in version 3.4.

trust_prompt(parameters, cancellable, callback, *user_data)¶

Parameters:

parameters (EDataServer.NamedParameters) – an EDataServer.NamedParameters with values for the trust prompt
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

Initiates a user trust prompt with given parameters.

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

New in version 3.8.

trust_prompt_finish(result)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult

Raises:

GLib.Error

Returns:

an EDataServer.TrustPromptResponse what user responded

Note: The function can return also EDataServer.TrustPromptResponse.UNKNOWN, it’s on error or if user closes the trust prompt dialog with other than the offered buttons. Usual behaviour in such case is to treat it as a temporary reject.

Return type:

EDataServer.TrustPromptResponse

Finishes the operation started with EBackend.Backend.trust_prompt(). If an error occurred, the function will set error and return EDataServer.TrustPromptResponse.UNKNOWN.

New in version 3.8.

trust_prompt_sync(parameters, cancellable)¶

Parameters:

parameters (EDataServer.NamedParameters) – an EDataServer.NamedParameters with values for the trust prompt
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

an EDataServer.TrustPromptResponse what user responded

Note: The function can return also EDataServer.TrustPromptResponse.UNKNOWN, it’s on error or if user closes the trust prompt dialog with other than the offered buttons. Usual behaviour in such case is to treat it as a temporary reject.

Return type:

EDataServer.TrustPromptResponse

Asks a user a trust prompt with given parameters, and returns what user responded. This blocks until the response is delivered.

New in version 3.8.

do_authenticate_sync(credentials, out_certificate_pem, out_certificate_errors, cancellable) virtual¶

Parameters:

credentials (EDataServer.NamedParameters) –
out_certificate_pem (str) –
out_certificate_errors (Gio.TlsCertificateFlags) –
cancellable (Gio.Cancellable or None) –

Return type:

EDataServer.SourceAuthenticationResult

Authenticate synchronously

do_get_destination_address() virtual¶

Returns:

True, when it’s a remote backend and provides both host and port; False otherwise.

host:: destination server host name
port:: destination server port

Return type:

(bool, host: str, port: int)

Provides destination server host name and port to which the backend connects. This is used to determine required connection point for EBackend.Backend.is_destination_reachable(). The host is a newly allocated string, which will be freed with GLib.free(). When backend sets both host and port, then it should return True, indicating it’s a remote backend. Default implementation returns False, which is treated like the backend is local, no checking for server reachability is possible.

New in version 3.8.

do_prepare_shutdown() virtual¶: Let’s the backend know that it’ll be shut down shortly, no client connects to it anymore. The backend can free any resources which reference it, for example the opened views.

New in version 3.16.

Property Details¶

EBackend.Backend.props.connectable¶

Name:: connectable
Type:: Gio.SocketConnectable
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Socket endpoint of a network service

EBackend.Backend.props.main_context¶

Name:: main-context
Type:: GLib.MainContext
Default Value:: None
Flags:: READABLE

The main loop context on which to attach event sources

EBackend.Backend.props.online¶

Name:: online
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the backend is online

EBackend.Backend.props.source¶

Name:: source
Type:: EDataServer.Source
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The data source being acted upon

EBackend.Backend.props.user_prompter¶

Name:: user-prompter
Type:: EBackend.UserPrompter
Default Value:: None
Flags:: READABLE

User prompter instance