Soup.WebsocketConnection

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

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:

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:

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:

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.