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. Clean: %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() 🔗

void set_handshake_headers(value: PackedStringArray)
PackedStringArray get_handshake_headers()

Дополнительные заголовки HTTP, которые будут отправлены во время рукопожатия WebSocket.

Примечание: Не поддерживается в веб-экспорте из-за ограничений браузеров.

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" отправляться не будут.

Примечание: Не влияет на экспорт веб-контента из-за ограничений браузера.

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.

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

Принимает одноранговое соединение, выполняющее HTTP-рукопожатие как сервер WebSocket. stream должен быть допустимым потоком TCP, полученным через TCPServer.take_connection(), или потоком TLS, принятым через StreamPeerTLS.accept_stream().

Примечание: Не поддерживается в веб-экспорте из-за ограничений браузеров.

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

Закрывает это WebSocket-соединение.

code — это код состояния закрытия (см. раздел 7.4 RFC 6455 для списка допустимых кодов состояния). Если code отрицательное значение, соединение будет закрыто немедленно без уведомления удаленного узла.

reason — это удобочитаемая причина закрытия соединения. Это может быть любая строка UTF-8 размером менее 123 байт.

Примечание: Для корректного закрытия необходимо продолжать опрос до достижения значения STATE_CLOSED.

Примечание: Веб-экспорт может не поддерживать все коды состояния. Для получения более подробной информации обратитесь к документации для конкретного браузера.

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() (например, во время процесса Node) и проверяйте результат get_ready_state(), чтобы узнать, успешно ли установлено соединение или нет.

Примечание: Чтобы избежать предупреждений о смешанном контенте или ошибок в Интернете, вам, возможно, придется использовать url, который начинается с 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.bufferedAmount, тогда как другие платформы используют внутренний буфер.

State get_ready_state() const 🔗

Возвращает состояние готовности соединения.

String get_requested_url() const 🔗

Возвращает URL, запрошенный этим пиром. URL выводится из url, переданного в connect_to_url(), или из заголовков HTTP при работе в качестве сервера (т. е. при использовании accept_stream()).

String get_selected_protocol() const 🔗

Возвращает выбранный подпротокол WebSocket для данного соединения или пустую строку, если подпротокол еще не выбран.

void poll() 🔗

Обновляет состояние соединения и получает входящие пакеты. Регулярно вызывайте эту функцию, чтобы поддерживать ее в чистом состоянии.

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

Отправляет указанный message, используя желаемый write_mode. При отправке String предпочтительнее использовать send_text().

Error send_text(message: String) 🔗

Отправляет указанный message с использованием текстового режима WebSocket. Предпочитайте этот метод PacketPeer.put_packet() при взаимодействии со сторонним текстовым API (например, при использовании сообщений в формате JSON).

void set_no_delay(enabled: bool) 🔗

Отключить алгоритм Нейгла на базовом сокете TCP (по умолчанию). Для получения дополнительной информации см. StreamPeerTCP.set_no_delay().

Примечание: Недоступно в веб-экспорте.

bool was_string_packet() const 🔗

Возвращает true, если последний полученный пакет был отправлен как текстовая полезная нагрузка. См. WriteMode.