WebSocketPeer

继承： PacketPeer < RefCounted < Object

WebSocket 连接。

描述

该类代表WebSocket连接，可以用作WebSocket客户端（符合RFC 6455）或Websocket服务器的远程对等。 您可以使用 PacketPeer.put_packet(), 与WebSocket文本帧一起使用 send() (与基于文本的API交互时，更喜欢文本帧). 您可以通过 was_string_packet().

要启动Websocket客户端，请首先 connect_to_url(), 然后定期 poll() (e.g. during Item process). 您可以通过 get_ready_state(), 使用待处理数据包的数量 PacketPeer.get_available_packet_count(), 并通过 PacketPeer.get_packet().

S3Script

extends Item

var socket = WebSocketPeer.new()

func _ready():
    socket.connect_to_url("wss://example.com")

func _process(delta):
    socket.poll()
    var state = socket.get_ready_state()
    if state == WebSocketPeer.STATE_OPEN:
        while socket.get_available_packet_count():
            print("Packet: ", socket.get_packet())
    elif state == WebSocketPeer.STATE_CLOSING:
        # 保持轮询以实现适当的近距离。
        pass
    elif state == WebSocketPeer.STATE_CLOSED:
        var code = socket.get_close_code()
        var reason = socket.get_close_reason()
        print("WebSocket closed with code: %d, reason %s. Clean: %s" % [code, reason, code != -1])
        set_process(false) # Stop processing.

如果要作为 WebSocket 服务器的对等体使用，请参考 accept_stream() 。

属性

PackedStringArray	handshake_headers	PackedStringArray()
float	heartbeat_interval	0.0
int	inbound_buffer_size	65535
int	max_queued_packets	4096
int	outbound_buffer_size	65535
PackedStringArray	supported_protocols	PackedStringArray()

方法

Error	accept_stream(stream: StreamPeer)
void	close(code: int = 1000, reason: String = "")
Error	connect_to_url(url: String, tls_client_options: TLSOptions = null)
int	get_close_code() const
String	get_close_reason() const
String	get_connected_host() const
int	get_connected_port() const
int	get_current_outbound_buffered_amount() const
State	get_ready_state() const
String	get_requested_url() const
String	get_selected_protocol() const
void	poll()
Error	send(message: PackedByteArray, write_mode: WriteMode = 1)
Error	send_text(message: String)
void	set_no_delay(enabled: bool)
bool	was_string_packet() const

---

枚举

enum Writemode: 🔗

WriteMode WRITE_MODE_TEXT = 0

指定 WebSockets 消息应作为文本有效载荷传输（只允许有效的 UTF-8）。

WriteMode WRITE_MODE_BINARY = 1

指定 WebSockets 消息应以二进制有效载荷的形式传输（允许任何字节组合）。

---

enum 状态: 🔗

State STATE_CONNECTING = 0

已创建套接字。连接尚未打开。

State STATE_OPEN = 1

连接已打开，通讯就绪。

State STATE_CLOSING = 2

连接正在关闭过程中。这意味着已经向远程对等体发送了关闭请求，但还没有收到确认。

State STATE_CLOSED = 3

连接已关闭或无法打开。

---

属性说明

PackedStringArray handshake_headers = PackedStringArray() 🔗

• void set_handshake_headers(value: PackedStringArray)

• PackedStringArray get_handshake_headers()

在WebSocket握手期间要发送的额外HTTP标头。

注意：由于浏览器的限制，在 Web 导出中不支持。 注意：将 复制 返回的数组，对它的任何更改都不会更新原始属性值。有关详细信息，请参阅 PackedStringArray 。

---

float heartbeat_interval = 0.0 🔗

• void set_heartbeat_interval(value: float)

• float get_heartbeat_interval()

该间隔（以秒为单位）将自动发送Websocket“ ping”控制帧。 设置为 0, 不会发送“ ping”控制帧。

注意: 由于浏览器限制，对Web出口没有影响。

---

int inbound_buffer_size = 65535 🔗

• void set_inbound_buffer_size(value: int)

• int get_inbound_buffer_size()

输入缓冲区的大小，单位为字节（大致是将分配给入站数据包的最大内存量）。

---

int max_queued_packets = 4096 🔗

• void set_max_queued_packets(value: int)

• int get_max_queued_packets()

队列中允许的最大数据包数量（包括入站和出站）。

---

int outbound_buffer_size = 65535 🔗

• void set_outbound_buffer_size(value: int)

• int get_outbound_buffer_size()

输入缓冲区的大小，单位为字节（大致是将分配给出站数据包的最大内存量）。

---

PackedStringArray supported_protocols = PackedStringArray() 🔗

• void set_supported_protocols(value: PackedStringArray)

• PackedStringArray get_supported_protocols()

WebSocket 握手期间允许的 WebSocket 子协议。

注意: 将 复制 返回的数组，对它的任何更改都不会更新原始属性值。有关详细信息，请参阅 PackedStringArray 。

---

方法说明

Error accept_stream(stream: StreamPeer) 🔗

接受执行HTTP握手作为Websocket服务器的对等连接。 这 stream 必须是通过通过 TCPServer.take_connection(), 或通过 StreamPeerTLS.accept_stream().

注意: 由于浏览器的限制，网络出口不支持。

---

void close(code: int = 1000, reason: String = "") 🔗

关闭此WebSocket连接。code 是关闭的状态代码 (有关有效状态代码的列表，请参见RFC 6455第7.4节). reason 是关闭联系的人类可读理由 (可以是小于123个字节的任何UTF-8字符串). 如果 code 为负，连接将立即关闭，而无需通知远程对等。

注意: 要完成清洁的近距离，您需要继续进行轮询直到 STATE_CLOSED 达到。

注意: Web导出可能不支持所有状态代码。 有关更多详细信息，请参考特定于浏览器的文档。

---

Error connect_to_url(url: String, tls_client_options: TLSOptions = null) 🔗

连接到给定的URL。 使用TLS证书在使用该宿主的名称进行验证 wss://``协议。 您可以通过可选 ``tls_client_options 定制可信赖认证机构或禁用通用名称验证的参数。 看 TLSOptions.client() 和 TLSOptions.client_unsafe().

注意: 此方法是非障碍的，并且会返回 @GlobalScope.OK 在建立连接之前，只要提供的参数有效并且对等方不处于无效状态（例如已经连接）。 定期打电话 poll() (e.g. during Item process) 并检查结果 get_ready_state() 知道连接成功还是失败。

注意: 为了避免网络中混合的内容警告或错误，您可能必须使用 url that starts with wss:// （安全）而不是 ws://. 这样做时，请确保使用与服务器TLS证书中定义的完全合格的域名。 不要直接通过IP地址连接 wss:// 连接，因为它与TLS证书不匹配。

---

int get_close_code() const 🔗

返回收到的 WebSocket 关闭帧状态码，如果连接没有干净地关闭则返回 -1。get_ready_state() 返回 STATE_CLOSED 才能调用这个方法。

---

String get_close_reason() const 🔗

返回收到的 WebSocket 关闭帧状态原因字符串。get_ready_state() 返回 STATE_CLOSED 才能调用这个方法。

---

String get_connected_host() const 🔗

返回连接对等的IP地址。

注意: 网络导出中没有。

---

int get_connected_port() const 🔗

返回连接到对等的遥控端口。

注意: 网络导出中没有。

---

int get_current_outbound_buffered_amount() const 🔗

返回 websocket 输出缓冲区中的当前数据量。注意：Web 导出使用 WebSocket.bufferedAmount，而其他平台使用内部缓冲区。

---

State get_ready_state() const 🔗

返回该连接的就绪状态，见 State。

---

String get_requested_url() const 🔗

返回该对等体请求的 URL。该 URL 由传给 connect_to_url() 的 url 得出，作为服务器时则从 HTTP 标头获取（即使用 accept_stream() 时）。

---

String get_selected_protocol() const 🔗

返回这个连接所选用的 WebSocket 子协议，如果未选择子协议则返回空字符串。

---

void poll() 🔗

更新连接状态并接收传入的数据包。请定期调用此函数，保持其清洁状态。

---

Error send(message: PackedByteArray, write_mode: WriteMode = 1) 🔗

使用期望的 write_mode 发送给定的 message。发送 String 时，请优先使用 send_text()。

---

Error send_text(message: String) 🔗

使用 WebSocket 文本模式发送给定的 message。与第三方文本 API 交互时请优先使用这个方法而不是 PacketPeer.put_packet()（例如使用 JSON 格式的消息时）。

---

void set_no_delay(enabled: bool) 🔗

在基础TCP插座上禁用Nagle的算法（默认）。 看 StreamPeerTCP.set_no_delay() 有关更多信息。

注意: 网络导出中没有。

---

bool was_string_packet() const 🔗

如果最后收到的数据包是作为文本有效载荷发送的，返回 true。见 WriteMode。