:right-sidebar: True WebsocketConnection =================================================================== .. currentmodule:: gi.repository.Soup .. class:: WebsocketConnection(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` :Constructors: :: WebsocketConnection(**properties) new(stream:Gio.IOStream, uri:GLib.Uri, type:Soup.WebsocketConnectionType, origin:str=None, protocol:str=None, extensions:list) -> Soup.WebsocketConnection 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_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: ~typing.Sequence[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_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 connection (client/server). .. attribute:: props.extensions :type: None List of :obj:`~gi.repository.Soup.WebsocketExtension` objects that are active in the connection. .. attribute:: props.io_stream :type: ~gi.repository.Gio.IOStream The underlying IO stream the WebSocket is communicating over. The input and output streams must be pollable streams. .. attribute:: props.keepalive_interval :type: 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. .. attribute:: props.max_incoming_payload_size :type: int The maximum payload size for incoming packets. The protocol expects or 0 to not limit it. .. attribute:: props.origin :type: str The client's Origin. .. attribute:: props.protocol :type: str The chosen protocol, or :const:`None` if a protocol was not agreed upon. .. attribute:: props.state :type: ~gi.repository.Soup.WebsocketState The current state of the WebSocket. .. attribute:: props.uri :type: ~gi.repository.GLib.Uri The URI of the WebSocket. For servers this represents the address of the WebSocket, and for clients it is the address connected to. Signals ------- .. rst-class:: interim-class .. class:: WebsocketConnection.signals :no-index: .. method:: closed() -> None Emitted when the connection has completely closed. This happens either due to an orderly close from the peer, one initiated via :obj:`~gi.repository.WebsocketConnection.close` or a fatal error condition that caused a close. This signal will be emitted once. .. method:: closing() -> None This signal will be emitted during an orderly close. .. method:: error(error: ~gi.repository.GLib.GError) -> None Emitted when an error occurred on the WebSocket. This may be fired multiple times. Fatal errors will be followed by the :obj:`~gi.repository.Soup.WebsocketConnection.signals.closed` signal being emitted. :param error: the error that occured .. method:: message(type: int, message: ~gi.repository.GLib.Bytes) -> None Emitted when we receive a message from the peer. As a convenience, the ``message`` data will always be :const:`None`-terminated, but the NUL byte will not be included in the length count. :param type: the type of message contents :param message: the message data .. method:: pong(message: ~gi.repository.GLib.Bytes) -> None Emitted when we receive a Pong frame (solicited or unsolicited) from the peer. As a convenience, the ``message`` data will always be :const:`None`-terminated, but the NUL byte will not be included in the length count. :param message: the application data (if any)