Soup.WebsocketConnection¶
- Subclasses:
None
Methods¶
- Inherited:
- Structs:
class |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Virtual Methods¶
- Inherited:
Properties¶
Name |
Type |
Flags |
Short Description |
---|---|---|---|
r/w/co |
Connection type (client/server) |
||
r/w/co |
The list of active extensions |
||
r/w/co |
Underlying I/O stream |
||
r/w/c |
Keepalive interval |
||
r/w/c |
Max incoming payload size |
||
r/w/co |
The WebSocket origin |
||
r/w/co |
The chosen WebSocket protocol |
||
r |
State |
||
r/w/co |
The WebSocket URI |
Signals¶
- Inherited:
Name |
Short Description |
---|---|
Emitted when the connection has completely closed. |
|
This signal will be emitted during an orderly close. |
|
Emitted when an error occurred on the WebSocket. |
|
Emitted when we receive a message from the peer. |
|
Emitted when we receive a Pong frame (solicited or unsolicited) from the peer. |
Fields¶
- Inherited:
Class Details¶
- class Soup.WebsocketConnection(**kwargs)¶
- Bases:
- Abstract:
No
- Structure:
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
) – aGio.IOStream
connected to the WebSocket serveruri (
GLib.Uri
) – the URI of the connectiontype (
Soup.WebsocketConnectionType
) – the type of connection (client/side)extensions ([
Soup.WebsocketExtension
]) – aGLib.List
ofSoup.WebsocketExtension
objects
- Returns:
a new
Soup.WebsocketConnection
- Return type:
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)¶
-
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:
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()¶
-
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:
Get the connection type (client/server) of the connection.
- get_extensions()¶
- Returns:
a
GLib.List
ofSoup.WebsocketExtension
objects- Return type:
Get the extensions chosen via negotiation with the peer.
- get_io_stream()¶
- Returns:
the WebSocket’s I/O stream.
- Return type:
Get the I/O stream the WebSocket is communicating over.
- get_keepalive_interval()¶
- Returns:
the keepalive interval.
- Return type:
Gets the keepalive interval in seconds or 0 if disabled.
- get_max_incoming_payload_size()¶
- Returns:
the maximum payload size.
- Return type:
Gets the maximum payload size allowed for incoming packets.
- get_protocol()¶
-
Get the protocol chosen via negotiation with the peer.
- get_state()¶
- Returns:
the state
- Return type:
Get the current state of the WebSocket.
- get_uri()¶
- Returns:
the URI
- Return type:
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)¶
-
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 contentsmessage (
GLib.Bytes
) – the message data asGLib.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.
Signal Details¶
- Soup.WebsocketConnection.signals.closed(websocket_connection)¶
- Signal Name:
closed
- Flags:
- 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:
- 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:
- Parameters:
websocket_connection (
Soup.WebsocketConnection
) – The object which received the signalerror (
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:
- Parameters:
websocket_connection (
Soup.WebsocketConnection
) – The object which received the signaltype (
int
) – the type of message contentsmessage (
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:
- Parameters:
websocket_connection (
Soup.WebsocketConnection
) – The object which received the signalmessage (
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:
- Default Value:
- Flags:
The type of connection (client/server).
- Soup.WebsocketConnection.props.extensions¶
- Name:
extensions
- Type:
- Default Value:
- Flags:
List of [class`WebsocketExtension`] objects that are active in the connection.
- Soup.WebsocketConnection.props.io_stream¶
- Name:
io-stream
- Type:
- Default Value:
- Flags:
The underlying IO stream the WebSocket is communicating over.
The input and output streams must be pollable streams.
- Soup.WebsocketConnection.props.keepalive_interval¶
-
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:
- Default Value:
131072
- Flags:
The maximum payload size for incoming packets.
The protocol expects or 0 to not limit it.
- Soup.WebsocketConnection.props.origin¶
- Name:
origin
- Type:
- Default Value:
- Flags:
The client’s Origin.
- Soup.WebsocketConnection.props.protocol¶
- Name:
protocol
- Type:
- Default Value:
- Flags:
The chosen protocol, or
None
if a protocol was not agreed upon.
- Soup.WebsocketConnection.props.state¶
- Name:
state
- Type:
- Default Value:
- Flags:
The current state of the WebSocket.