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_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_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`

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