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.

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

int

inbound_buffer_size

65535

int

max_queued_packets

2048

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.


int inbound_buffer_size = 65535 🔗

  • void set_inbound_buffer_size(value: int)

  • int get_inbound_buffer_size()

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


int max_queued_packets = 2048 🔗

  • 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.clientTLSOptions.client_unsafe

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


int get_close_code() const 🔗

返回收到的 WebSocket 关闭帧状态码,如果连接没有干净地关闭则返回 -1get_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_urlurl 得出,作为服务器时则从 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