EBackend.Backend

g EBackend.Backend EBackend.Backend GObject.Object GObject.Object GObject.Object->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:

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:
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:

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:

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:
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:
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