Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

WebSocketPeer

继承： PacketPeer < RefCounted < Object

WebSocket 连接。

描述

这个类代表 WebSocket 连接，可以用作 WebSocket 客户端（兼容 RFC 6455），也可以用作 WebSocket 服务器的远程对等体。

发送 WebSocket 二进制帧请使用 PacketPeer.put_packet()，发送 WebSocket 文本帧请使用 send()（与基于文本的 API 交互时请优先选择文本帧）。可以通过 was_string_packet() 检查最近一个数据包的帧类型。

开启 WebSocket 客户端的方法是：首先调用 connect_to_url()，然后定期调用 poll()（例如在 Node 的处理过程中）。查询套接字的状态请使用 get_ready_state()，获取挂起的数据包数量请使用 PacketPeer.get_available_packet_count()，获取挂起的数据包请使用 PacketPeer.get_packet()。

extends Node

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("数据包：", 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 已关闭，代码：%d，原因 %s。干净得体：%s" % [code, reason, code != -1])
        set_process(false) # 停止处理。

如果要作为 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 STATE_CONNECTING = 0

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

State STATE_OPEN = 1

连接已打开，通讯就绪。

State STATE_CLOSING = 2

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

State STATE_CLOSED = 3

连接已关闭或无法打开。

属性说明

PackedStringArray handshake_headers = PackedStringArray() 🔗

在 WebSocket 握手过程中要发送的额外 HTTP 标头。

注意：由于浏览器的限制，在 Web 导出中不支持。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.

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() 🔗

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

Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.

方法说明

Error accept_stream(stream: StreamPeer) 🔗

以 WebSocket 服务器的名义，接受正在执行 HTTP 握手的对等体连接。stream 必须是从 TCPServer.take_connection() 获取的有效 TCP 流，或者是从 StreamPeerTLS.accept_stream() 接受的 TLS 流。

注意：由于浏览器的限制，Web 导出中不支持此方法。

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。使用 wss:// 协议连接时会校验 TLS 证书与主机名。传入可选的 tls_client_options 参数可以自定义信任的证书颁发机构，也可以禁用通用名校验。见 TLSOptions.client() 和 TLSOptions.client_unsafe()。

注意：该方法不会阻塞，只要提供的参数有效且对等体不处于无效状态（例如已连接）就会在建立连接前返回 @GlobalScope.OK。要检测连接成功还是失败，请定期调用 poll()（例如在 Node 的处理方法中）并检查 get_ready_state() 的结果。

注意：为了避免 Web 中的混合内容警告或错误，你可能需要使用以 wss://（安全）开头的 url 而不是 ws://。采用这种做法时，请确保使用与服务器 TLS 证书相匹配的主机域名全称。wss:// 连接请勿直接使用 IP 地址连接，因为不会与 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 地址。

注意：在 Web 导出中不可用。

int get_connected_port() const 🔗

返回已连接对等体的远程端口。

注意：在 Web 导出中不可用。

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()。

注意：在 Web 导出中不可用。

bool was_string_packet() const 🔗

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