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。
GDScript
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 及在线教程。
属性
| ||
| ||
| ||
| ||
|
方法
accept_stream(stream: StreamPeer) | |
void | |
connect_to_url(url: String, tls_client_options: TLSOptions = null) | |
get_close_code() const | |
get_close_reason() const | |
get_connected_host() const | |
get_connected_port() const | |
get_ready_state() const | |
get_requested_url() const | |
get_selected_protocol() const | |
void | poll() |
send(message: PackedByteArray, write_mode: WriteMode = 1) | |
void | set_no_delay(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()
🔗
void set_handshake_headers(value: PackedStringArray)
PackedStringArray get_handshake_headers()
在 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
🔗
输入缓冲区的大小,单位为字节(大致是将分配给入站数据包的最大内存量)。
int max_queued_packets = 2048
🔗
队列中允许的最大数据包数量(包括入站和出站)。
int outbound_buffer_size = 65535
🔗
输入缓冲区的大小,单位为字节(大致是将分配给出站数据包的最大内存量)。
PackedStringArray supported_protocols = PackedStringArray()
🔗
void set_supported_protocols(value: PackedStringArray)
PackedStringArray get_supported_protocols()
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。
注意:要避免 Web 中的混合内容警告或错误,你可能需要使用以 wss://
(安全)开头的 url
而不是 ws://
。采用这种做法时,请确保使用与服务器 TLS 证书相匹配的主机域名全称。wss://
连接请勿直接使用 IP 地址连接,因为不会与 TLS 证书匹配。
返回收到的 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) 🔗
Disable Nagle’s algorithm on the underlying TCP socket (default). See StreamPeerTCP.set_no_delay for more information.
Note: Not available in the Web export.
bool was_string_packet() const 🔗
如果最后收到的数据包是作为文本有效载荷发送的,返回 true
。见 WriteMode。