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
Hereda: PacketPeer < RefCounted < Object
Una conexión WebSocket.
Descripción
This class represents WebSocket connection, and can be used as a WebSocket client (RFC 6455-compliant) or as a remote peer of a WebSocket server.
You can send WebSocket binary frames using PacketPeer.put_packet(), and WebSocket text frames using send() (prefer text frames when interacting with text-based API). You can check the frame type of the last packet via was_string_packet().
To start a WebSocket client, first call connect_to_url(), then regularly call poll() (e.g. during Node process). You can query the socket state via get_ready_state(), get the number of pending packets using PacketPeer.get_available_packet_count(), and retrieve them via 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("Packet: ", socket.get_packet())
elif state == WebSocketPeer.STATE_CLOSING:
# Keep polling to achieve proper close.
pass
elif state == WebSocketPeer.STATE_CLOSED:
var code = socket.get_close_code()
var reason = socket.get_close_reason()
print("WebSocket closed with code: %d, reason %s. Clean: %s" % [code, reason, code != -1])
set_process(false) # Stop processing.
To use the peer as part of a WebSocket server refer to accept_stream() and the online tutorial.
Propiedades
|
||
|
||
|
||
|
||
|
||
|
Métodos
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 |
Enumeraciones
enum WriteMode: 🔗
WriteMode WRITE_MODE_TEXT = 0
Especifica que los mensajes de WebSockets deben ser transferidos como carga de texto (sólo se permite el UTF-8 válido).
WriteMode WRITE_MODE_BINARY = 1
Especifica que los mensajes de WebSockets deben ser transferidos como carga binaria (se permite cualquier combinación de bytes).
enum State: 🔗
State STATE_CONNECTING = 0
El socket ha sido creado. La conexión aún no está abierta.
State STATE_OPEN = 1
La conexión está abierta y lista para comunicarse.
State STATE_CLOSING = 2
La conexión está en proceso de cierre. Esto significa que se ha enviado una solicitud de cierre al par remoto, pero no se ha recibido la confirmación.
State STATE_CLOSED = 3
La conexión está cerrada o no se pudo abrir.
Descripciones de Propiedades
PackedStringArray handshake_headers = PackedStringArray() 🔗
void set_handshake_headers(value: PackedStringArray)
PackedStringArray get_handshake_headers()
Las cabeceras HTTP adicionales que se enviarán durante el establecimiento de comunicación de WebSocket.
Nota: No soportado en las exportaciones Web debido a las restricciones de los navegadores.
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 🔗
El intervalo (en segundos) en el que el par enviará automáticamente tramas de control "ping" de WebSocket. Cuando se establece en 0, no se enviarán tramas de control "ping".
Nota: No tiene efecto en las exportaciones Web debido a las restricciones del navegador.
int inbound_buffer_size = 65535 🔗
El tamaño del búfer de entrada en bytes (aproximadamente la cantidad máxima de memoria que se asignará para los paquetes entrantes).
int max_queued_packets = 4096 🔗
La cantidad máxima de paquetes que se permitirán en las colas (tanto de entrada como de salida).
int outbound_buffer_size = 65535 🔗
El tamaño del búfer de entrada en bytes (aproximadamente la cantidad máxima de memoria que se asignará para los paquetes salientes).
PackedStringArray supported_protocols = PackedStringArray() 🔗
void set_supported_protocols(value: PackedStringArray)
PackedStringArray get_supported_protocols()
Los subprotocolos de WebSocket permitidos durante el establecimiento de comunicación de WebSocket.
Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.
Descripciones de Métodos
Error accept_stream(stream: StreamPeer) 🔗
Acepta una conexión de par que realiza el establecimiento de comunicación HTTP como un servidor WebSocket. El stream debe ser un flujo TCP válido recuperado a través de TCPServer.take_connection(), o un flujo TLS aceptado a través de StreamPeerTLS.accept_stream().
Nota: No compatible con las exportaciones Web debido a las restricciones de los navegadores.
void close(code: int = 1000, reason: String = "") 🔗
Closes this WebSocket connection.
code is the status code for the closure (see RFC 6455 section 7.4 for a list of valid status codes). If code is negative, the connection will be closed immediately without notifying the remote peer.
reason is the human-readable reason for closing the connection. It can be any UTF-8 string that's smaller than 123 bytes.
Note: To achieve a clean closure, you will need to keep polling until STATE_CLOSED is reached.
Note: The Web export might not support all status codes. Please refer to browser-specific documentation for more details.
Error connect_to_url(url: String, tls_client_options: TLSOptions = null) 🔗
Conecta a la URL dada. Los certificados TLS se verificarán con el nombre de host al conectarse mediante el protocolo wss://. Puedes pasar el parámetro opcional tls_client_options para personalizar las autoridades de certificación de confianza, o desactivar la verificación del nombre común. Véase TLSOptions.client() y TLSOptions.client_unsafe().
Nota: Este método no es bloqueante, y devolverá @GlobalScope.OK antes de que se establezca la conexión, siempre y cuando los parámetros proporcionados sean válidos y el par no esté en un estado inválido (por ejemplo, ya conectado). Llama regularmente a poll() (por ejemplo, durante el proceso de Node) y comprueba el resultado de get_ready_state() para saber si la conexión tiene éxito o falla.
Nota: Para evitar avisos o errores de contenido mixto en la Web, es posible que tengas que utilizar una url que comience con wss:// (seguro) en lugar de ws://. Al hacerlo, asegúrate de utilizar el nombre de dominio completo que coincida con el definido en el certificado TLS del servidor. No te conectes directamente a través de la dirección IP para las conexiones wss://, ya que no coincidirá con el certificado TLS.
Devuelve el código de estado del frame de cierre de WebSocket recibido, o -1 cuando la conexión no se cerró limpiamente. Solo llama a este método cuando get_ready_state() devuelve STATE_CLOSED.
String get_close_reason() const 🔗
Devuelve la string de motivo del estado del frame de cierre de WebSocket recibido. Solo llama a este método cuando get_ready_state() devuelve STATE_CLOSED.
String get_connected_host() const 🔗
Devuelve la dirección IP del par conectado.
Nota: No disponible en la exportación Web.
int get_connected_port() const 🔗
Devuelve el puerto remoto del par conectado.
Nota: No disponible en la exportación Web.
int get_current_outbound_buffered_amount() const 🔗
Devuelve la cantidad actual de datos en el búfer de websocket de salida. Nota: Las exportaciones Web usan WebSocket.bufferedAmount, mientras que otras plataformas usan un búfer interno.
State get_ready_state() const 🔗
Devuelve el estado de preparación de la conexión.
String get_requested_url() const 🔗
Devuelve la URL solicitada por este par. La URL se deriva de la url pasada a connect_to_url() o de las cabeceras HTTP cuando se actúa como servidor (es decir, cuando se utiliza accept_stream()).
String get_selected_protocol() const 🔗
Devuelve el subprotocolo WebSocket seleccionado para esta conexión o una string vacía si el subprotocolo aún no se ha seleccionado.
void poll() 🔗
Actualiza el estado de la conexión y recibe los paquetes entrantes. Llama a esta función regularmente para mantenerla en un estado limpio.
Error send(message: PackedByteArray, write_mode: WriteMode = 1) 🔗
Envía el message dado utilizando el write_mode deseado. Cuando se envía una String, es preferible utilizar send_text().
Error send_text(message: String) 🔗
Envía el message dado utilizando el modo de texto WebSocket. Es preferible este método a PacketPeer.put_packet() cuando se interactúa con una API de terceros basada en texto (por ejemplo, cuando se utilizan mensajes con formato JSON).
void set_no_delay(enabled: bool) 🔗
Desactiva el algoritmo de Nagle en el socket TCP subyacente (por defecto). Véase StreamPeerTCP.set_no_delay() para obtener más información.
Nota: No disponible en la exportación Web.
bool was_string_packet() const 🔗
Devuelve true si el último paquete recibido fue enviado como una carga de texto. Véase WriteMode.