EDataServer.SoupSession¶

Subclasses:: EDataServer.GDataSession, EDataServer.WebDAVSession

Methods¶

Inherited:: Soup.Session (43), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`new` (source)
class	`util_get_force_http1_supported` ()
class	`util_get_message_bytes` (message)
class	`util_normalize_uri_path` (uri)
class	`util_ref_message_request_body` (message)
class	`util_set_message_request_body` (message, content_type, input_stream, length)
class	`util_set_message_request_body_from_data` (message, create_copy, content_type, data, length, free_func)
class	`util_status_to_string` (status_code, reason_phrase)
	`check_result` (message, read_bytes, bytes_length)
	`dup_credentials` ()
	`get_authentication_requires_credentials` ()
	`get_force_http1` ()
	`get_handle_backoff_responses` ()
	`get_log_level` ()
	`get_source` ()
	`get_ssl_error_details` ()
	`handle_authentication_failure` (credentials, op_error)
	`new_message` (method, uri_string)
	`new_message_from_uri` (method, uri)
	`prepare_message_send_sync` (message, cancellable)
	`send_message` (message, io_priority, prepare_data, cancellable, callback, *user_data)
	`send_message_finish` (result)
	`send_message_simple_sync` (message, cancellable)
	`send_message_sync` (message, cancellable)
	`set_credentials` (credentials)
	`set_force_http1` (force_http1)
	`set_handle_backoff_responses` (handle_backoff_responses)
	`setup_logging` (logging_level)

Virtual Methods¶

Inherited:: Soup.Session (2), GObject.Object (7)

Properties¶

Inherited:: Soup.Session (12)

Name	Type	Flags
`credentials`	`EDataServer.NamedParameters`	r/w/en
`force-http1`	`bool`	r/w/en
`handle-backoff-responses`	`bool`	r/w/en
`source`	`EDataServer.Source`	r/w/co

Signals¶

Inherited:: Soup.Session (2), GObject.Object (1)

Fields¶

Inherited:: Soup.Session (2), GObject.Object (1)

Name	Type	Access	Description
parent	`Soup.Session`	r

Class Details¶

class EDataServer.SoupSession(**kwargs)¶

Bases:: Soup.Session
Abstract:: No
Structure:: EDataServer.SoupSessionClass

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

New in version 3.26.

classmethod error_quark()¶

Return type:: int

classmethod new(source)¶

Parameters:: source (EDataServer.Source) – an EDataServer.Source
Returns:: a new EDataServer.SoupSession; free it with GObject.Object.unref(), when no longer needed.
Return type:: EDataServer.SoupSession

Creates a new EDataServer.SoupSession associated with given source. The source can be used to store and read SSL trust settings, but only if it already contains an EDataServer.SourceWebdav extension. Otherwise the SSL trust settings are ignored.

New in version 3.26.

classmethod util_get_force_http1_supported()¶

Returns:: True, when the force of HTTP/1 is supported, False otherwise
Return type:: bool

Checks whether EDataServer.SoupSession.set_force_http1() can be used to force HTTP/1 usage. This depends on the libsoup version the data server had been compiled with.

New in version 3.48.

classmethod util_get_message_bytes(message)¶

Parameters:: message (Soup.Message) – a Soup.Message
Returns:: read message data on failed request, or None, when none had been read
Return type:: bytes or None

Returns bytes read from the message response, when the message send failed. This can be used to examine detailed error returned by the server in the response body.

New in version 3.46.

classmethod util_normalize_uri_path(uri)¶

Parameters:: uri (GLib.Uri) – a GLib.Uri to normalize the path for
Returns:: a new GLib.Uri with modified path, or None, when no change was required.
Return type:: GLib.Uri or None

Normalizes the path of the uri, aka encodes characters, which should be encoded, if needed. Returns, modified URI when any change had been made to the path. It doesn’t touch other parts of the uri.

New in version 3.46.

classmethod util_ref_message_request_body(message)¶

Parameters:

message (Soup.Message) – a Soup.Message

Returns:

a new Gio.InputStream with the request body being previously set, or None. The out_length is set to the length of the returned input stream.

out_length:: length of the input stream

Return type:

(Gio.InputStream or None, out_length: int)

Returns referenced request data for the message, as being previously set by the EDataServer.SoupSession.util_set_message_request_body() or EDataServer.SoupSession.util_set_message_request_body_from_data().

Do not call this function while the message is queued in a Soup.Session, nor modify the input stream position until the message lefts the Soup.Session.

New in version 3.46.

classmethod util_set_message_request_body(message, content_type, input_stream, length)¶

Parameters:

message (Soup.Message) – a Soup.Message
content_type (str or None) – optional Content-Type of the data, or None input_stream (transfer none): the request body data as a Gio.InputStream
input_stream (Gio.InputStream) –
length (int) – length of the data

Sets the request body of the message from the input_stream of the length, with optional content_type. The function makes sure the message request body is set again when the message is restarted.

The input_stream should implement the Gio.Seekable interface.

New in version 3.46.

classmethod util_set_message_request_body_from_data(message, create_copy, content_type, data, length, free_func)¶

Parameters:

message (Soup.Message) – a Soup.Message
create_copy (bool) – whether to create copy of the data
content_type (str or None) – optional Content-Type of the data, or None
data (object or None) – the request body data
length (int) – length of the data
free_func (GLib.DestroyNotify or None) – a free function for the data, or None

Sets the request body of the message from the data of the length, with optional content_type. The function makes sure the message request body is set again when the message is restarted.

When the create_copy is True, the free_func should be None.

New in version 3.46.

classmethod util_status_to_string(status_code, reason_phrase)¶

Parameters:

status_code (int) – an HTTP status code
reason_phrase (str or None) – preferred string to use for the message, or None

Returns:

Error text based on given arguments. The returned value is valid as long as reason_phrase is not freed.

Return type:

str

Returns the reason_phrase, if it’s non-None and non-empty, a static string corresponding to status_code. In case neither that can be found a localized “Unknown error” message is returned.

New in version 3.26.

check_result(message, read_bytes, bytes_length)¶

Parameters:

message (Soup.Message) – a Soup.Message
read_bytes (object or None) – optional bytes which had been read from the stream, or None
bytes_length (int) – how many bytes had been read; ignored when read_bytes is None

Raises:

GLib.Error

Returns:

Whether succeeded, aka True, when no error recognized and False otherwise.

Return type:

bool

Checks result of the message and sets the error if it failed. When it failed and the read_bytes is provided, then these are set to message's response body, thus it can be used later.

New in version 3.26.

dup_credentials()¶

Returns:: A copy of the credentials being previously set with EDataServer.SoupSession.set_credentials(), or None when none are set. Free the returned pointer with EDataServer.NamedParameters.free(), when no longer needed.
Return type:: EDataServer.NamedParameters or None

New in version 3.26.

get_authentication_requires_credentials()¶

Returns:: Whether the last connection attempt required any credentials. Authentications like OAuth2 do not want extra credentials to work.
Return type:: bool

New in version 3.28.

get_force_http1()¶

Returns:: whether it’s forced to use HTTP/1
Return type:: bool

Returns whether it’s forced to use HTTP/1 for the messages created by the self. See EDataServer.SoupSession.set_force_http1() for more information about the limitations.

New in version 3.48.

get_handle_backoff_responses()¶

Returns:: whether the self handles backoff responses
Return type:: bool

Returns whether the self can handle backoff responses from the server. See EDataServer.SoupSession.set_handle_backoff_responses() for more information about the limitations.

New in version 3.54.

get_log_level()¶

Returns:: Current log level, as Soup.LoggerLogLevel
Return type:: Soup.LoggerLogLevel

New in version 3.26.

get_source()¶

Returns:: Associated EDataServer.Source with the self, or None.
Return type:: EDataServer.Source or None

Returns an EDataServer.Source associated with the self, if such was set in the creation time.

New in version 3.26.

get_ssl_error_details()¶

Returns:

Whether the information was available and set to the out parameters.

out_certificate_pem:: return location for a server TLS/SSL certificate in PEM format, when the last operation failed with a TLS/SSL error, or None
out_certificate_errors:: return location for a Gio.TlsCertificateFlags, with certificate error flags when the operation failed with a TLS/SSL error, or None

Return type:

(bool, out_certificate_pem: str, out_certificate_errors: Gio.TlsCertificateFlags)

Populates out_certificate_pem and out_certificate_errors with the last values returned on Gio.TlsError.BAD_CERTIFICATE error.

New in version 3.26.

handle_authentication_failure(credentials, op_error)¶

Parameters:

credentials (EDataServer.NamedParameters or None) – credentials used for the authentication
op_error (GLib.Error) – a GLib.Error of the authentication operation

Raises:

GLib.Error

Returns:

out_auth_result:: an EDataServer.SourceAuthenticationResult with an authentication result
out_certificate_pem:: return location for a server TLS/SSL certificate in PEM format, when the last operation failed with a TLS/SSL error, or None
out_certificate_errors:: return location for a Gio.TlsCertificateFlags, with certificate error flags when the operation failed with a TLS/SSL error, or None

Return type:

(out_auth_result: EDataServer.SourceAuthenticationResult, out_certificate_pem: str, out_certificate_errors: Gio.TlsCertificateFlags)

Handles authentication failure and sets appropriate value to the out_auth_result for the provided op_error and used credentials. Converts the op_error into an appropriate error returned in the error.

Also updates connection status on the associated EDataServer.Source with the self.

New in version 3.46.

new_message(method, uri_string)¶

Parameters:

method (str) – an HTTP method
uri_string (str) – a URI string to use for the request

Raises:

GLib.Error

Returns:

a new Soup.Message, or None on error

Return type:

Soup.Message

Creates a new Soup.Message, similar to Soup.Message.new(), but also presets request headers with “User-Agent” to be “Evolution/version” and with “Connection” to be “close”.

New in version 3.26.

new_message_from_uri(method, uri)¶

Parameters:

method (str) – an HTTP method
uri (GLib.Uri) – a GLib.Uri to use for the request

Raises:

GLib.Error

Returns:

a new Soup.Message, or None on error

Return type:

Soup.Message

Creates a new Soup.Message, similar to Soup.Message.new_from_uri(), but also presets request headers with “User-Agent” to be “Evolution/version” and with “Connection” to be “close”.

New in version 3.46.

prepare_message_send_sync(message, cancellable)¶

Parameters:

message (Soup.Message) – a Soup.Message to prepare for asynchronous send
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

prepare data for EDataServer.SoupSession.send_message(), or None on error.

Return type:

object or None

Prepares the message to be a sent asynchronously with EDataServer.SoupSession.send_message(). The returned pointer is passed to the EDataServer.SoupSession.send_message() as the prepare_data parameter.

New in version 3.46.

send_message(message, io_priority, prepare_data, cancellable, callback, *user_data)¶

Parameters:

message (Soup.Message) – a Soup.Message to send
io_priority (int) – the I/O priority of the request, like GLib.PRIORITY_DEFAULT
prepare_data (object or None) – data returned from EDataServer.SoupSession.prepare_message_send_sync()
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
callback (Gio.AsyncReadyCallback or None) – the callback to invoke once the request is finished
user_data (object or None) – user data for callback

Asynchronously sends the message. Finish the call with EDataServer.SoupSession.send_message_finish().

The prepare_data is a result of the EDataServer.SoupSession.prepare_message_send_sync() and this function assumes ownership of it. The prepare_data cannot be used again after this call.

New in version 3.46.

send_message_finish(result)¶

Parameters:

result (Gio.AsyncResult) – a Gio.AsyncResult object

Raises:

GLib.Error

Returns:

a Gio.InputStream for reading the response body, or None on error

out_certificate_pem:: return location for a server TLS/SSL certificate in PEM format, when the last operation failed with a TLS/SSL error
out_certificate_errors:: return location for a Gio.TlsCertificateFlags, with certificate error flags when the operation failed with a TLS/SSL error

Return type:

(Gio.InputStream or None, out_certificate_pem: str or None, out_certificate_errors: Gio.TlsCertificateFlags)

Finishes the call of EDataServer.SoupSession.send_message(). This is supposed to be called from the callback passed to the EDataServer.SoupSession.send_message().

The optional out_certificate_pem and out_certificate_errors are set, when provided, only if the operation failed with a TLS/SSL error.

Make sure the Gio.InputStream is read and freed from the same thread, and with the same thread default main context, which this function was called from, otherwise it can break libsoup3.

New in version 3.46.

send_message_simple_sync(message, cancellable)¶

Parameters:

message (Soup.Message) – a Soup.Message to send
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

A newly allocated GLib.ByteArray, which contains whole content from the URI pointed to by message.

Return type:

bytes

Similar to EDataServer.SoupSession.send_message_sync(), except it reads whole response content into memory and returns it as a GLib.ByteArray. Use EDataServer.SoupSession.send_message_sync() when you want to have more control on the content read.

New in version 3.26.

send_message_sync(message, cancellable)¶

Parameters:

message (Soup.Message) – a Soup.Message to send
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None

Raises:

GLib.Error

Returns:

A newly allocated Gio.InputStream, that can be used to read from the URI pointed to by message. Free it with GObject.Object.unref(), when no longer needed.

Return type:

Gio.InputStream

Synchronously sends prepared message and returns Gio.InputStream that can be used to read its contents.

This calls Soup.Session.send() internally, but it also setups the message according to EDataServer.SoupSession :source authentication settings. It also extracts information about used certificate, in case of Gio.TlsError.BAD_CERTIFICATE error and keeps it for later use by EDataServer.SoupSession.get_ssl_error_details().

Use EDataServer.SoupSession.send_message_simple_sync() to read whole content into a GLib.ByteArray.

Note that Soup.Session doesn’t log content read from Gio.InputStream, thus the caller may print the read content on its own when needed.

Note the message is fully filled only after there is anything read from the resulting Gio.InputStream, thus use EDataServer.SoupSession.check_result() to verify that the receive had been finished properly.

Make sure the Gio.InputStream is read and freed from the same thread, and with the same thread default main context, which this function was called from, otherwise it can break libsoup3.

New in version 3.26.

set_credentials(credentials)¶

Parameters:: credentials (EDataServer.NamedParameters or None) – an EDataServer.NamedParameters with credentials to use, or None

Sets credentials to use for connection. Using None for credentials unsets previous value.

New in version 3.26.

set_force_http1(force_http1)¶

Parameters:: force_http1 (bool) – the value to set

Sets whether the messages created through the self using EDataServer.SoupSession.new_message() or EDataServer.SoupSession.new_message_from_uri() should force use of the HTTP/1, instead of trying HTTP/2 and fallback to HTTP/1, when the newer version cannot be used.

The property has no effect when EDataServer.SoupSession.util_get_force_http1_supported() returns False.

New in version 3.48.

set_handle_backoff_responses(handle_backoff_responses)¶

Parameters:: handle_backoff_responses (bool) – the value to set

Sets whether to automatically handle backoff responses from the server, that is, when the server requests the client to retry later.

Note: This handles only the synchronous functions to send the messages. Clients using the asynchronous API need to handle the backoff responses on their own.

New in version 3.54.

setup_logging(logging_level)¶

Parameters:: logging_level (str or None) – logging level to setup, or None

Setups logging for the self. The logging_level can be one of: “all” - log whole raw communication; “body” - the same as “all”; “headers” - log the headers only; “min” - minimal logging; “1” - the same as “all”. Any other value, including None, disables logging.

Use EDataServer.SoupSession.get_log_level() to get current log level.

New in version 3.26.

Property Details¶

EDataServer.SoupSession.props.credentials¶

Name:: credentials
Type:: EDataServer.NamedParameters
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The EDataServer.NamedParameters containing login credentials.

New in version 3.26.

EDataServer.SoupSession.props.force_http1¶

Name:: force-http1
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the messages created by the session should force use of HTTP/1 instead of trying HTTP/2 first and fallback to the HTTP/1 when the newer version failed to connect.

See EDataServer.SoupSession.set_force_http1() for more information about the limitations.

New in version 3.48.

EDataServer.SoupSession.props.handle_backoff_responses¶

Name:: handle-backoff-responses
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Set to True, which is the default, to automatically handle backoff responses from the server, that is, when the server requests the client to retry later.

Note: This handles only the synchronous functions to send the messages. Clients using the asynchronous API need to handle the backoff responses on their own.

New in version 3.54.

EDataServer.SoupSession.props.source¶

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

The EDataServer.Source being used for this soup session.

New in version 3.26.