Soup.WebsocketConnection¶

Subclasses:: None

Methods¶

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

class	`new` (stream, uri, type, origin, protocol, extensions)
	`close` (code, data)
	`get_close_code` ()
	`get_close_data` ()
	`get_connection_type` ()
	`get_extensions` ()
	`get_io_stream` ()
	`get_keepalive_interval` ()
	`get_max_incoming_payload_size` ()
	`get_origin` ()
	`get_protocol` ()
	`get_state` ()
	`get_uri` ()
	`send_binary` (data)
	`send_message` (type, message)
	`send_text` (text)
	`set_keepalive_interval` (interval)
	`set_max_incoming_payload_size` (max_incoming_payload_size)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`connection-type`	`Soup.WebsocketConnectionType`	r/w/co	Connection type (client/server)
`extensions`	`int`	r/w/co	The list of active extensions
`io-stream`	`Gio.IOStream`	r/w/co	Underlying I/O stream
`keepalive-interval`	`int`	r/w/c	Keepalive interval
`max-incoming-payload-size`	`int`	r/w/c	Max incoming payload size
`origin`	`str`	r/w/co	The WebSocket origin
`protocol`	`str`	r/w/co	The chosen WebSocket protocol
`state`	`Soup.WebsocketState`	r	State
`uri`	`GLib.Uri`	r/w/co	The WebSocket URI

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`closed`	Emitted when the connection has completely closed.
`closing`	This signal will be emitted during an orderly close.
`error`	Emitted when an error occurred on the WebSocket.
`message`	Emitted when we receive a message from the peer.
`pong`	Emitted when we receive a Pong frame (solicited or unsolicited) from the peer.

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Soup.WebsocketConnection(**kwargs)¶

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

The WebSocket Protocol

Provides support for the WebSocket protocol.

To connect to a WebSocket server, create a [class`Session`] and call [method`Session`.websocket_connect_async]. To accept WebSocket connections, create a [class`Server`] and add a handler to it with [method`Server`.add_websocket_handler].

(Lower-level support is available via [func`websocket_client_prepare_handshake`] and [func`websocket_client_verify_handshake`], for handling the client side of the WebSocket handshake, and [func`websocket_server_process_handshake`] for handling the server side.)

Soup.WebsocketConnection handles the details of WebSocket communication. You can use [method`WebsocketConnection`.send_text] and [method`WebsocketConnection`.send_binary] to send data, and the [signal`WebsocketConnection`:py:func:::message<Soup.WebsocketConnection.signals.message>] signal to receive data. (Soup.WebsocketConnection currently only supports asynchronous I/O.)

classmethod new(stream, uri, type, origin, protocol, extensions)¶

Parameters:

stream (Gio.IOStream) – a Gio.IOStream connected to the WebSocket server
uri (GLib.Uri) – the URI of the connection
type (Soup.WebsocketConnectionType) – the type of connection (client/side)
origin (str or None) – the Origin of the client
protocol (str or None) – the subprotocol in use
extensions ([Soup.WebsocketExtension]) – a GLib.List of Soup.WebsocketExtension objects

Returns:

a new Soup.WebsocketConnection

Return type:

Soup.WebsocketConnection

Creates a Soup.WebsocketConnection on stream with the given active extensions.

This should be called after completing the handshake to begin using the WebSocket protocol.

close(code, data)¶

Parameters:

code (int) – close code
data (str or None) – close data

Close the connection in an orderly fashion.

Note that until the [signal`WebsocketConnection`:py:func:::closed<Soup.WebsocketConnection.signals.closed>] signal fires, the connection is not yet completely closed. The close message is not even sent until the main loop runs.

The code and data are sent to the peer along with the close request. If code is Soup.WebsocketCloseCode.NO_STATUS a close message with no body (without code and data) is sent. Note that the data must be UTF-8 valid.

get_close_code()¶

Returns:: the close code or zero.
Return type:: int

Get the close code received from the WebSocket peer.

This only becomes valid once the WebSocket is in the Soup.WebsocketState.CLOSED state. The value will often be in the [enum`WebsocketCloseCode`] enumeration, but may also be an application defined close code.

get_close_data()¶

Returns:: the close data or None
Return type:: str

Get the close data received from the WebSocket peer.

This only becomes valid once the WebSocket is in the Soup.WebsocketState.CLOSED state. The data may be freed once the main loop is run, so copy it if you need to keep it around.

get_connection_type()¶

Returns:: the connection type
Return type:: Soup.WebsocketConnectionType

Get the connection type (client/server) of the connection.

get_extensions()¶

Returns:: a GLib.List of Soup.WebsocketExtension objects
Return type:: [Soup.WebsocketExtension]

Get the extensions chosen via negotiation with the peer.

get_io_stream()¶

Returns:: the WebSocket’s I/O stream.
Return type:: Gio.IOStream

Get the I/O stream the WebSocket is communicating over.

get_keepalive_interval()¶

Returns:: the keepalive interval.
Return type:: int

Gets the keepalive interval in seconds or 0 if disabled.

get_max_incoming_payload_size()¶

Returns:: the maximum payload size.
Return type:: int

Gets the maximum payload size allowed for incoming packets.

get_origin()¶

Returns:: the origin
Return type:: str or None

Get the origin of the WebSocket.

get_protocol()¶

Returns:: the chosen protocol
Return type:: str or None

Get the protocol chosen via negotiation with the peer.

get_state()¶

Returns:: the state
Return type:: Soup.WebsocketState

Get the current state of the WebSocket.

get_uri()¶

Returns:: the URI
Return type:: GLib.Uri

Get the URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.

send_binary(data)¶

Parameters:: data (bytes or None) – the message contents

Send a binary message to the peer.

If length is 0, data may be None.

The message is queued to be sent and will be sent when the main loop is run.

send_message(type, message)¶

Parameters:

type (Soup.WebsocketDataType) – the type of message contents
message (GLib.Bytes) – the message data as GLib.Bytes

Send a message of the given type to the peer. Note that this method, allows to send text messages containing None characters.

The message is queued to be sent and will be sent when the main loop is run.

send_text(text)¶

Parameters:: text (str) – the message contents

Send a None-terminated text (UTF-8) message to the peer.

If you need to send text messages containing None characters use [method`WebsocketConnection`.send_message] instead.

The message is queued to be sent and will be sent when the main loop is run.

set_keepalive_interval(interval)¶

Parameters:: interval (int) – the interval to send a ping message or 0 to disable it

Sets the interval in seconds on when to send a ping message which will serve as a keepalive message.

If set to 0 the keepalive message is disabled.

set_max_incoming_payload_size(max_incoming_payload_size)¶

Parameters:: max_incoming_payload_size (int) – the maximum payload size

Sets the maximum payload size allowed for incoming packets.

It does not limit the outgoing packet size.

Signal Details¶

Soup.WebsocketConnection.signals.closed(websocket_connection)¶

Signal Name:: closed
Flags:: RUN_FIRST
Parameters:: websocket_connection (Soup.WebsocketConnection) – The object which received the signal

Emitted when the connection has completely closed.

This happens either due to an orderly close from the peer, one initiated via [method`WebsocketConnection`.close] or a fatal error condition that caused a close.

This signal will be emitted once.

Soup.WebsocketConnection.signals.closing(websocket_connection)¶

Signal Name:: closing
Flags:: RUN_LAST
Parameters:: websocket_connection (Soup.WebsocketConnection) – The object which received the signal

This signal will be emitted during an orderly close.

Soup.WebsocketConnection.signals.error(websocket_connection, error)¶

Signal Name:

error

Flags:

RUN_FIRST

Parameters:

websocket_connection (Soup.WebsocketConnection) – The object which received the signal
error (GLib.Error) – the error that occured

Emitted when an error occurred on the WebSocket.

This may be fired multiple times. Fatal errors will be followed by the [signal`WebsocketConnection`:py:func:::closed<Soup.WebsocketConnection.signals.closed>] signal being emitted.

Soup.WebsocketConnection.signals.message(websocket_connection, type, message)¶

Signal Name:

message

Flags:

RUN_FIRST

Parameters:

websocket_connection (Soup.WebsocketConnection) – The object which received the signal
type (int) – the type of message contents
message (GLib.Bytes) – the message data

Emitted when we receive a message from the peer.

As a convenience, the message data will always be None-terminated, but the NUL byte will not be included in the length count.

Soup.WebsocketConnection.signals.pong(websocket_connection, message)¶

Signal Name:

pong

Flags:

RUN_FIRST

Parameters:

websocket_connection (Soup.WebsocketConnection) – The object which received the signal
message (GLib.Bytes) – the application data (if any)

Emitted when we receive a Pong frame (solicited or unsolicited) from the peer.

As a convenience, the message data will always be None-terminated, but the NUL byte will not be included in the length count.

Property Details¶

Soup.WebsocketConnection.props.connection_type¶

Name:: connection-type
Type:: Soup.WebsocketConnectionType
Default Value:: Soup.WebsocketConnectionType.UNKNOWN
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The type of connection (client/server).

Soup.WebsocketConnection.props.extensions¶

Name:: extensions
Type:: int
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

List of [class`WebsocketExtension`] objects that are active in the connection.

Soup.WebsocketConnection.props.io_stream¶

Name:: io-stream
Type:: Gio.IOStream
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The underlying IO stream the WebSocket is communicating over.

The input and output streams must be pollable streams.

Soup.WebsocketConnection.props.keepalive_interval¶

Name:: keepalive-interval
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE, CONSTRUCT

Interval in seconds on when to send a ping message which will serve as a keepalive message.

If set to 0 the keepalive message is disabled.

Soup.WebsocketConnection.props.max_incoming_payload_size¶

Name:: max-incoming-payload-size
Type:: int
Default Value:: 131072
Flags:: READABLE, WRITABLE, CONSTRUCT

The maximum payload size for incoming packets.

The protocol expects or 0 to not limit it.

Soup.WebsocketConnection.props.origin¶

Name:: origin
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The client’s Origin.

Soup.WebsocketConnection.props.protocol¶

Name:: protocol
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The chosen protocol, or None if a protocol was not agreed upon.

Soup.WebsocketConnection.props.state¶

Name:: state
Type:: Soup.WebsocketState
Default Value:: Soup.WebsocketState.OPEN
Flags:: READABLE

The current state of the WebSocket.

Soup.WebsocketConnection.props.uri¶

Name:: uri
Type:: GLib.Uri
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.