WebsocketConnection
Superclasses: Object
The WebSocket Protocol
Provides support for the WebSocket protocol.
To connect to a WebSocket server, create a Session
and call
websocket_connect_async
. To accept WebSocket
connections, create a Server
and add a handler to it with
add_websocket_handler
.
(Lower-level support is available via
websocket_client_prepare_handshake
and
websocket_client_verify_handshake
, for handling the client side of the
WebSocket handshake, and websocket_server_process_handshake
for
handling the server side.)
WebsocketConnection
handles the details of WebSocket communication. You
can use send_text
and
send_binary
to send data, and the
message
signal to receive data.
(WebsocketConnection
currently only supports asynchronous I/O.)
Constructors
- class WebsocketConnection
- classmethod new(stream: IOStream, uri: Uri, type: WebsocketConnectionType, origin: str | None, protocol: str | None, extensions: list[WebsocketExtension]) WebsocketConnection
Creates a
WebsocketConnection
onstream
with the given activeextensions
.This should be called after completing the handshake to begin using the WebSocket protocol.
- Parameters:
stream – a
IOStream
connected to the WebSocket serveruri – the URI of the connection
type – the type of connection (client/side)
origin – the Origin of the client
protocol – the subprotocol in use
extensions – a
List
ofWebsocketExtension
objects
Methods
- class WebsocketConnection
- close(code: int, data: str | None = None) None
Close the connection in an orderly fashion.
Note that until the
closed
signal fires, the connection is not yet completely closed. The close message is not even sent until the main loop runs.The
code
anddata
are sent to the peer along with the close request. Ifcode
isNO_STATUS
a close message with no body (without code and data) is sent. Note that thedata
must be UTF-8 valid.- Parameters:
code – close code
data – close data
- get_close_code() int
Get the close code received from the WebSocket peer.
This only becomes valid once the WebSocket is in the
CLOSED
state. The value will often be in theWebsocketCloseCode
enumeration, but may also be an application defined close code.
- get_close_data() str
Get the close data received from the WebSocket peer.
This only becomes valid once the WebSocket is in the
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() WebsocketConnectionType
Get the connection type (client/server) of the connection.
- get_extensions() list[WebsocketExtension]
Get the extensions chosen via negotiation with the peer.
- get_state() WebsocketState
Get the current state of the WebSocket.
- get_uri() 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: Sequence[int] | None = None) None
Send a binary message to the peer.
If
length
is 0,data
may beNone
.The message is queued to be sent and will be sent when the main loop is run.
- Parameters:
data – the message contents
- send_message(type: WebsocketDataType, message: Bytes) None
Send a message of the given
type
to the peer. Note that this method, allows to send text messages containingNone
characters.The message is queued to be sent and will be sent when the main loop is run.
- Parameters:
type – the type of message contents
message – the message data as
Bytes
- send_text(text: str) None
Send a
None
-terminated text (UTF-8) message to the peer.If you need to send text messages containing
None
characters usesend_message
instead.The message is queued to be sent and will be sent when the main loop is run.
- Parameters:
text – the message contents
Properties
- class WebsocketConnection
- props.connection_type: WebsocketConnectionType
The type of connection (client/server).
- props.extensions: None
List of
WebsocketExtension
objects that are active in the connection.
- props.io_stream: IOStream
The underlying IO stream the WebSocket is communicating over.
The input and output streams must be pollable streams.
- props.keepalive_interval: int
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.
- props.max_incoming_payload_size: int
The maximum payload size for incoming packets.
The protocol expects or 0 to not limit it.
- props.state: WebsocketState
The current state of the WebSocket.
Signals
- class WebsocketConnection.signals
- closed() None
Emitted when the connection has completely closed.
This happens either due to an orderly close from the peer, one initiated via
close
or a fatal error condition that caused a close.This signal will be emitted once.
- error(error: GError) None
Emitted when an error occurred on the WebSocket.
This may be fired multiple times. Fatal errors will be followed by the
closed
signal being emitted.- Parameters:
error – the error that occured