Soup.ServerMessage¶

Subclasses:: None

Methods¶

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

	`get_http_version` ()
	`get_local_address` ()
	`get_method` ()
	`get_reason_phrase` ()
	`get_remote_address` ()
	`get_remote_host` ()
	`get_request_body` ()
	`get_request_headers` ()
	`get_response_body` ()
	`get_response_headers` ()
	`get_socket` ()
	`get_status` ()
	`get_tls_peer_certificate` ()
	`get_tls_peer_certificate_errors` ()
	`get_uri` ()
	`is_options_ping` ()
	`pause` ()
	`set_http_version` (version)
	`set_redirect` (status_code, redirect_uri)
	`set_response` (content_type, resp_use, resp_body)
	`set_status` (status_code, reason_phrase)
	`steal_connection` ()
	`unpause` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`tls-peer-certificate`	`Gio.TlsCertificate`	r	The TLS peer certificate associated with the message
`tls-peer-certificate-errors`	`Gio.TlsCertificateFlags`	r	The verification errors on the message’s TLS peer certificate

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`accept-certificate`	Emitted during the msg's connection TLS handshake after client TLS certificate has been received.
`connected`	Emitted when the msg's socket is connected and the TLS handshake completed.
`disconnected`	Emitted when the msg's socket is disconnected.
`finished`	Emitted when all HTTP processing is finished for a message.
`got-body`	Emitted after receiving the complete request body.
`got-chunk`	Emitted after receiving a chunk of a message body.
`got-headers`	Emitted after receiving the Request-Line and request headers.
`wrote-body`	Emitted immediately after writing the complete response body for a message.
`wrote-body-data`	Emitted immediately after writing a portion of the message body to the network.
`wrote-chunk`	Emitted immediately after writing a body chunk for a message.
`wrote-headers`	Emitted immediately after writing the response headers for a message.
`wrote-informational`	Emitted immediately after writing a 1xx (Informational) response.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Soup.ServerMessage(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Soup.ServerMessageClass

An HTTP server request and response pair.

A Soup.ServerMessage represents an HTTP message that is being sent or received on a [class`Server`].

[class`Server`] will create ``SoupServerMessage``s automatically for incoming requests, which your application will receive via handlers.

Note that libsoup’s terminology here does not quite match the HTTP specification: in RFC 2616, an “HTTP-message” is *either* a Request, *or* a Response. In libsoup, a Soup.ServerMessage combines both the request and the response.

get_http_version()¶

Returns:: a Soup.HTTPVersion.
Return type:: Soup.HTTPVersion

Get the HTTP version of self.

get_local_address()¶

Returns:: the Gio.SocketAddress associated with the local end of a connection, it may be None if you used [method`Server`.accept_iostream].
Return type:: Gio.SocketAddress or None

Retrieves the [class`Gio`.SocketAddress] associated with the local end of a connection.

get_method()¶

Returns:: the HTTP method.
Return type:: str

Get the HTTP method of self.

get_reason_phrase()¶

Returns:: the reason phrase.
Return type:: str or None

Get the HTTP reason phrase of self.

get_remote_address()¶

Returns:: the Gio.SocketAddress associated with the remote end of a connection, it may be None if you used [class`Server`.accept_iostream].
Return type:: Gio.SocketAddress or None

Retrieves the [class`Gio`.SocketAddress] associated with the remote end of a connection.

get_remote_host()¶

Returns:: the IP address associated with the remote end of a connection, it may be None if you used [method`Server`.accept_iostream].
Return type:: str or None

Retrieves the IP address associated with the remote end of a connection.

get_request_body()¶

Returns:: a Soup.MessageBody.
Return type:: Soup.MessageBody

Get the request body of self.

get_request_headers()¶

Returns:: a Soup.MessageHeaders with the request headers.
Return type:: Soup.MessageHeaders

Get the request headers of self.

get_response_body()¶

Returns:: a Soup.MessageBody.
Return type:: Soup.MessageBody

Get the response body of self.

get_response_headers()¶

Returns:: a Soup.MessageHeaders with the response headers.
Return type:: Soup.MessageHeaders

Get the response headers of self.

get_socket()¶

Returns:: the Gio.Socket that self is associated with, None if you used [method`Server`.accept_iostream].
Return type:: Gio.Socket or None

Retrieves the [class`Gio`.Socket] that self is associated with.

If you are using this method to observe when multiple requests are made on the same persistent HTTP connection (eg, as the ntlm-test test program does), you will need to pay attention to socket destruction as well (eg, by using weak references), so that you do not get fooled when the allocator reuses the memory address of a previously-destroyed socket to represent a new socket.

get_status()¶

Returns:: the HTTP status code.
Return type:: int

Get the HTTP status code of self.

get_tls_peer_certificate()¶

Returns:: self's TLS peer certificate, or None if self's connection is not SSL.
Return type:: Gio.TlsCertificate or None

Gets the peer’s Gio.TlsCertificate associated with self's connection. Note that this is not set yet during the emission of Soup.ServerMessage ::accept-certificate signal.

New in version 3.2.

get_tls_peer_certificate_errors()¶

Returns:: a Gio.TlsCertificateFlags with self's TLS peer certificate errors.
Return type:: Gio.TlsCertificateFlags

Gets the errors associated with validating self's TLS peer certificate. Note that this is not set yet during the emission of Soup.ServerMessage ::accept-certificate signal.

New in version 3.2.

get_uri()¶

Returns:: a GLib.Uri
Return type:: GLib.Uri

Get self's URI.

is_options_ping()¶

Returns:: True if is an OPTIONS ping
Return type:: bool

Gets if self represents an OPTIONS message with the path *.

pause()¶

Pauses I/O on self.

This can be used when you need to return from the server handler without having the full response ready yet. Use [method`ServerMessage`.unpause] to resume I/O.

New in version 3.2.

set_http_version(version)¶

Parameters:: version (Soup.HTTPVersion) – a Soup.HTTPVersion

Set the HTTP version of self.

set_redirect(status_code, redirect_uri)¶

Parameters:

status_code (int) – a 3xx status code
redirect_uri (str) – the URI to redirect self to

Sets self's status_code to status_code and adds a Location header pointing to redirect_uri. Use this from a [class`Server`] when you want to redirect the client to another URI.

redirect_uri can be a relative URI, in which case it is interpreted relative to self's current URI. In particular, if redirect_uri is just a path, it will replace the path *and query* of self's URI.

set_response(content_type, resp_use, resp_body)¶

Parameters:

content_type (str or None) – MIME Content-Type of the body
resp_use (Soup.MemoryUse) – a Soup.MemoryUse describing how to handle resp_body
resp_body (bytes or None) – a data buffer containing the body of the message response.

Convenience function to set the response body of a Soup.ServerMessage. If content_type is None, the response body must be empty as well.

set_status(status_code, reason_phrase)¶

Parameters:

status_code (int) – an HTTP status code
reason_phrase (str or None) – a reason phrase

Sets self's status code to status_code.

If status_code is a known value and reason_phrase is None, the reason_phrase will be set automatically.

steal_connection()¶

Returns:: the Gio.IOStream formerly associated with self (or None if self was no longer associated with a connection). No guarantees are made about what kind of Gio.IOStream is returned.
Return type:: Gio.IOStream

“Steals” the HTTP connection associated with self from its Soup.Server. This happens immediately, regardless of the current state of the connection; if the response to self has not yet finished being sent, then it will be discarded; you can steal the connection from a [signal`ServerMessage`:py:func:::wrote-informational<Soup.ServerMessage.signals.wrote_informational>] or [signal`ServerMessage`:py:func:::wrote-body<Soup.ServerMessage.signals.wrote_body>] signal handler if you need to wait for part or all of the response to be sent.

Note that when calling this function from C, self will most likely be freed as a side effect.

unpause()¶

Resumes I/O on self.

Use this to resume after calling [method`ServerMessage`.pause], or after adding a new chunk to a chunked response. I/O won’t actually resume until you return to the main loop.

New in version 3.2.

Signal Details¶

Soup.ServerMessage.signals.accept_certificate(server_message, tls_peer_certificate, tls_peer_errors)¶

Signal Name:

accept-certificate

Flags:

RUN_LAST

Parameters:

server_message (Soup.ServerMessage) – The object which received the signal
tls_peer_certificate (Gio.TlsCertificate) – the peer’s Gio.TlsCertificate
tls_peer_errors (Gio.TlsCertificateFlags) – the tls errors of tls_certificate

Returns:

True to accept the TLS certificate and stop other handlers from being invoked, or False to propagate the event further.

Return type:

bool

Emitted during the msg's connection TLS handshake after client TLS certificate has been received. You can return True to accept tls_certificate despite tls_errors.

Soup.ServerMessage.signals.connected(server_message)¶

Signal Name:: connected
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted when the msg's socket is connected and the TLS handshake completed.

Soup.ServerMessage.signals.disconnected(server_message)¶

Signal Name:: disconnected
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted when the msg's socket is disconnected.

Soup.ServerMessage.signals.finished(server_message)¶

Signal Name:: finished
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted when all HTTP processing is finished for a message. (After [signal`ServerMessage`:py:func:::wrote-body<Soup.ServerMessage.signals.wrote_body>]).

Soup.ServerMessage.signals.got_body(server_message)¶

Signal Name:: got-body
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted after receiving the complete request body.

Soup.ServerMessage.signals.got_chunk(server_message, chunk)¶

Signal Name:

got-chunk

Flags:

RUN_FIRST

Parameters:

server_message (Soup.ServerMessage) – The object which received the signal
chunk (GLib.Bytes) – the just-read chunk

Emitted after receiving a chunk of a message body.

Note that “chunk” in this context means any subpiece of the body, not necessarily the specific HTTP 1.1 chunks sent by the other side.

Soup.ServerMessage.signals.got_headers(server_message)¶

Signal Name:: got-headers
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted after receiving the Request-Line and request headers.

Soup.ServerMessage.signals.wrote_body(server_message)¶

Signal Name:: wrote-body
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted immediately after writing the complete response body for a message.

Soup.ServerMessage.signals.wrote_body_data(server_message, chunk_size)¶

Signal Name:

wrote-body-data

Flags:

RUN_LAST

Parameters:

server_message (Soup.ServerMessage) – The object which received the signal
chunk_size (int) – the number of bytes written

Emitted immediately after writing a portion of the message body to the network.

Soup.ServerMessage.signals.wrote_chunk(server_message)¶

Signal Name:: wrote-chunk
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted immediately after writing a body chunk for a message.

Note that this signal is not parallel to [signal`ServerMessage`:py:func:::got-chunk<Soup.ServerMessage.signals.got_chunk>]; it is emitted only when a complete chunk (added with [method`MessageBody`.append] or [method`MessageBody`.append_bytes] has been written. To get more useful continuous progress information, use [signal`ServerMessage`:py:func:::wrote-body-data<Soup.ServerMessage.signals.wrote_body_data>].

Soup.ServerMessage.signals.wrote_headers(server_message)¶

Signal Name:: wrote-headers
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted immediately after writing the response headers for a message.

Soup.ServerMessage.signals.wrote_informational(server_message)¶

Signal Name:: wrote-informational
Flags:: RUN_LAST
Parameters:: server_message (Soup.ServerMessage) – The object which received the signal

Emitted immediately after writing a 1xx (Informational) response.

Property Details¶

Soup.ServerMessage.props.tls_peer_certificate¶

Name:: tls-peer-certificate
Type:: Gio.TlsCertificate
Default Value:: None
Flags:: READABLE

The peer’s Gio.TlsCertificate associated with the message

New in version 3.2.

Soup.ServerMessage.props.tls_peer_certificate_errors¶

Name:: tls-peer-certificate-errors
Type:: Gio.TlsCertificateFlags
Default Value:: Gio.TlsCertificateFlags.NO_FLAGS
Flags:: READABLE

The verification errors on Soup.ServerMessage :tls-peer-certificate

New in version 3.2.