Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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

void

close ( int code=1000, String reason="" )

Error

connect_to_url ( String url, TLSOptions tls_client_options=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 ( PackedByteArray message, WriteMode write_mode=1 )

Error

send_text ( String message )

void

set_no_delay ( bool enabled )

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 导出中不支持。

int inbound_buffer_size = 65535

  • void set_inbound_buffer_size ( int value )

  • int get_inbound_buffer_size ( )

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

int max_queued_packets = 2048

  • void set_max_queued_packets ( int value )

  • int get_max_queued_packets ( )

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

int outbound_buffer_size = 65535

  • void set_outbound_buffer_size ( int value )

  • int get_outbound_buffer_size ( )

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

PackedStringArray supported_protocols = PackedStringArray()

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

方法说明

Error accept_stream ( StreamPeer stream )

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

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

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

关闭该 WebSocket 连接。code 是关闭的状态码（有效状态代码的列表见 RFC 6455 第 7.4 节）。reason 是人类可读的关闭连接原因（可以是任何小于 123 字节的 UTF-8 字符串）。如果 code 为负数，则连接会立即关闭，不通知远程对等体。

注意：为了实现干净得体的关闭，你需要在达到 STATE_CLOSED 之前保持轮询。

注意：Web 导出可能不支持部分状态码。详情请参考具体浏览器的文档。

Error connect_to_url ( String url, TLSOptions tls_client_options=null )

连接到给定的 URL。使用 wss:// 协议连接时会校验 TLS 证书与主机名。传入可选的 tls_client_options 参数可以自定义信任的证书颁发机构，也可以禁用通用名校验。见 TLSOptions.client 和 TLSOptions.client_unsafe。

注意：要避免 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 ( PackedByteArray message, WriteMode write_mode=1 )

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

Error send_text ( String message )

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

void set_no_delay ( bool enabled )

禁用底层 TCP 套接字的 Nagle 算法（默认）。详情见 StreamPeerTCP.set_no_delay。

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

bool was_string_packet ( ) const

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