EDataServer.SoupSession

g EDataServer.SoupSession EDataServer.SoupSession GObject.Object GObject.Object Soup.Session Soup.Session GObject.Object->Soup.Session Soup.Session->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_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)

setup_logging (logging_level)

Virtual Methods

Inherited:

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

Properties

Inherited:

Soup.Session (12)

Name

Type

Flags

Short Description

credentials

EDataServer.NamedParameters

r/w/en

force-http1

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:

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:

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:
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_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:
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”.

See also EDataServer.SoupSession.new_message_from_uri().

New in version 3.26.

new_message_from_uri(method, uri)
Parameters:
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”.

See also EDataServer.SoupSession.new_message().

New in version 3.46.

prepare_message_send_sync(message, cancellable)
Parameters:
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:

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

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