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.