Soup.WebsocketConnection¶

Subclasses:	None

Methods¶

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

class	`new` (stream, uri, type, origin, protocol)
class	`new_with_extensions` (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)

	`do_closed` ()
	`do_closing` ()
	`do_error` (error)
	`do_message` (type, message)
	`do_pong` (message)

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`	`Soup.URI`	r/w/co	The WebSocket URI

Signals¶

Inherited:	GObject.Object (1)

Name	Short Description
`closed`	Emitted when the connection has completely closed, either due to an orderly close from the peer, one initiated via `Soup.WebsocketConnection.close`() or a fatal error condition that caused a close.
`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)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Soup.WebsocketConnection(**kwargs)¶

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

A class representing a WebSocket connection.

New in version 2.50.

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

Parameters:	stream (`Gio.IOStream`) – a `Gio.IOStream` connected to the WebSocket server uri (`Soup.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
Returns:	a new `Soup.WebsocketConnection`
Return type:	`Soup.WebsocketConnection`

Creates a Soup.WebsocketConnection on stream. This should be called after completing the handshake to begin using the WebSocket protocol.

New in version 2.50.

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

Parameters:	stream (`Gio.IOStream`) – a `Gio.IOStream` connected to the WebSocket server uri (`Soup.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.

New in version 2.68.

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

New in version 2.50.

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 Soup.WebsocketCloseCode enumeration, but may also be an application defined close code.

New in version 2.50.

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.

New in version 2.50.

get_connection_type()¶

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

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

New in version 2.50.

get_extensions()¶

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

Get the extensions chosen via negotiation with the peer.

New in version 2.68.

get_io_stream()¶

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

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

New in version 2.50.

get_keepalive_interval()¶

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

Gets the keepalive interval in seconds or 0 if disabled.

New in version 2.58.

get_max_incoming_payload_size()¶

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

Gets the maximum payload size allowed for incoming packets.

New in version 2.56.

get_origin()¶

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

Get the origin of the WebSocket.

New in version 2.50.

get_protocol()¶

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

Get the protocol chosen via negotiation with the peer.

New in version 2.50.

get_state()¶

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

Get the current state of the WebSocket.

New in version 2.50.

get_uri()¶

Returns:	the URI
Return type:	`Soup.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.

New in version 2.50.

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.

New in version 2.50.

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.

New in version 2.68.

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 Soup.WebsocketConnection.send_message() instead.

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

New in version 2.50.

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.

New in version 2.58.

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.

New in version 2.56.

do_closed() virtual¶

do_closing() virtual¶

do_error(error) virtual¶

Parameters:	error (`GLib.Error`) –

do_message(type, message) virtual¶

Parameters:	type (`Soup.WebsocketDataType`) – message (`GLib.Bytes`) –

do_pong(message) virtual¶

Parameters:	message (`GLib.Bytes`) –

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, either due to an orderly close from the peer, one initiated via Soup.WebsocketConnection.close() or a fatal error condition that caused a close.

This signal will be emitted once.

New in version 2.50.

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.

New in version 2.50.

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 Soup.WebsocketConnection ::closed signal being emitted.

New in version 2.50.

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 NUL-terminated, but the NUL byte will not be included in the length count.

New in version 2.50.

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 NUL-terminated, but the NUL byte will not be included in the length count.

New in version 2.60.

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

New in version 2.50.

Soup.WebsocketConnection.props.extensions¶

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

List of Soup.WebsocketExtension objects that are active in the connection.

New in version 2.68.

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.

New in version 2.50.

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.

New in version 2.58.

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.

New in version 2.56.

Soup.WebsocketConnection.props.origin¶

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

The client’s Origin.

New in version 2.50.

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.

New in version 2.50.

Soup.WebsocketConnection.props.state¶

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

The current state of the WebSocket.

New in version 2.50.

Soup.WebsocketConnection.props.uri¶

Name:	`uri`
Type:	`Soup.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.

New in version 2.50.