:right-sidebar: True WebsocketConnection =================================================================== .. currentmodule:: gi.repository.Soup .. class:: WebsocketConnection(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` The WebSocket Protocol Provides support for the `WebSocket `__ protocol. To connect to a WebSocket server, create a :obj:`~gi.repository.Soup.Session` and call :obj:`~gi.repository.Session.websocket_connect_async`\. To accept WebSocket connections, create a :obj:`~gi.repository.Soup.Server` and add a handler to it with :obj:`~gi.repository.Server.add_websocket_handler`\. (Lower-level support is available via :obj:`~gi.repository.Soup.websocket_client_prepare_handshake` and :obj:`~gi.repository.Soup.websocket_client_verify_handshake`\, for handling the client side of the WebSocket handshake, and :obj:`~gi.repository.Soup.websocket_server_process_handshake` for handling the server side.) :obj:`~gi.repository.Soup.WebsocketConnection` handles the details of WebSocket communication. You can use :obj:`~gi.repository.WebsocketConnection.send_text` and :obj:`~gi.repository.WebsocketConnection.send_binary` to send data, and the :obj:`~gi.repository.Soup.WebsocketConnection.signals.message` signal to receive data. (:obj:`~gi.repository.Soup.WebsocketConnection` currently only supports asynchronous I/O.) Constructors ------------ .. rst-class:: interim-class .. class:: WebsocketConnection :no-index: .. classmethod:: new(stream: ~gi.repository.Gio.IOStream, uri: ~gi.repository.GLib.Uri, type: ~gi.repository.Soup.WebsocketConnectionType, origin: str | None, protocol: str | None, extensions: list[~gi.repository.Soup.WebsocketExtension]) -> ~gi.repository.Soup.WebsocketConnection Creates a :obj:`~gi.repository.Soup.WebsocketConnection` on ``stream`` with the given active ``extensions``\. This should be called after completing the handshake to begin using the WebSocket protocol. :param stream: a :obj:`~gi.repository.Gio.IOStream` connected to the WebSocket server :param uri: the URI of the connection :param type: the type of connection (client/side) :param origin: the Origin of the client :param protocol: the subprotocol in use :param extensions: a :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.Soup.WebsocketExtension` objects Methods ------- .. rst-class:: interim-class .. class:: WebsocketConnection :no-index: .. method:: close(code: int, data: str | None = None) -> None Close the connection in an orderly fashion. Note that until the :obj:`~gi.repository.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 :const:`~gi.repository.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. :param code: close code :param data: close data .. method:: get_close_code() -> int Get the close code received from the WebSocket peer. This only becomes valid once the WebSocket is in the :const:`~gi.repository.Soup.WebsocketState.CLOSED` state. The value will often be in the :obj:`~gi.repository.Soup.WebsocketCloseCode` enumeration, but may also be an application defined close code. .. method:: get_close_data() -> str Get the close data received from the WebSocket peer. This only becomes valid once the WebSocket is in the :const:`~gi.repository.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. .. method:: get_connection_type() -> ~gi.repository.Soup.WebsocketConnectionType Get the connection type (client/server) of the connection. .. method:: get_extensions() -> list[~gi.repository.Soup.WebsocketExtension] Get the extensions chosen via negotiation with the peer. .. method:: get_io_stream() -> ~gi.repository.Gio.IOStream Get the I/O stream the WebSocket is communicating over. .. method:: get_keepalive_interval() -> int Gets the keepalive interval in seconds or 0 if disabled. .. method:: get_keepalive_pong_timeout() -> int Gets the keepalive pong timeout in seconds or 0 if disabled. .. versionadded:: 3.6 .. method:: get_max_incoming_payload_size() -> int Gets the maximum payload size allowed for incoming packets. .. method:: get_origin() -> str | None Get the origin of the WebSocket. .. method:: get_protocol() -> str | None Get the protocol chosen via negotiation with the peer. .. method:: get_state() -> ~gi.repository.Soup.WebsocketState Get the current state of the WebSocket. .. method:: get_uri() -> ~gi.repository.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. .. method:: send_binary(data: list[int] | None = None) -> None Send a binary message to the peer. If ``length`` is 0, ``data`` may be :const:`None`. The message is queued to be sent and will be sent when the main loop is run. :param data: the message contents .. method:: send_message(type: ~gi.repository.Soup.WebsocketDataType, message: ~gi.repository.GLib.Bytes) -> None Send a message of the given ``type`` to the peer. Note that this method, allows to send text messages containing :const:`None` characters. The message is queued to be sent and will be sent when the main loop is run. :param type: the type of message contents :param message: the message data as :obj:`~gi.repository.GLib.Bytes` .. method:: send_text(text: str) -> None Send a :const:`None`-terminated text (UTF-8) message to the peer. If you need to send text messages containing :const:`None` characters use :obj:`~gi.repository.WebsocketConnection.send_message` instead. The message is queued to be sent and will be sent when the main loop is run. :param text: the message contents .. method:: set_keepalive_interval(interval: int) -> None 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. :param interval: the interval to send a ping message or 0 to disable it .. method:: set_keepalive_pong_timeout(pong_timeout: int) -> None Set the timeout in seconds for when the absence of a pong from a keepalive ping is assumed to be caused by a faulty connection. If set to 0 then the absence of pongs from keepalive pings is ignored. .. versionadded:: 3.6 :param pong_timeout: the timeout in seconds .. method:: set_max_incoming_payload_size(max_incoming_payload_size: int) -> None Sets the maximum payload size allowed for incoming packets. It does not limit the outgoing packet size. :param max_incoming_payload_size: the maximum payload size Properties ---------- .. rst-class:: interim-class .. class:: WebsocketConnection :no-index: .. attribute:: props.connection_type :type: ~gi.repository.Soup.WebsocketConnectionType The type of the None singleton. .. attribute:: props.extensions :type: ~typing.Any The type of the None singleton. .. attribute:: props.io_stream :type: ~gi.repository.Gio.IOStream The type of the None singleton. .. attribute:: props.keepalive_interval :type: int The type of the None singleton. .. attribute:: props.keepalive_pong_timeout :type: int The type of the None singleton. .. versionadded:: 3.6 .. attribute:: props.max_incoming_payload_size :type: int The type of the None singleton. .. attribute:: props.origin :type: str The type of the None singleton. .. attribute:: props.protocol :type: str The type of the None singleton. .. attribute:: props.state :type: ~gi.repository.Soup.WebsocketState The type of the None singleton. .. attribute:: props.uri :type: ~gi.repository.GLib.Uri The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: WebsocketConnection.signals :no-index: .. method:: closed() -> None The type of the None singleton. .. method:: closing() -> None The type of the None singleton. .. method:: error(error: ~gi.repository.GLib.GError) -> None The type of the None singleton. :param error: the error that occured .. method:: message(type: int, message: ~gi.repository.GLib.Bytes) -> None The type of the None singleton. :param type: the type of message contents :param message: the message data .. method:: pong(message: ~gi.repository.GLib.Bytes) -> None The type of the None singleton. :param message: the application data (if any)