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

Eredita: PacketPeer < RefCounted < Object

Una connessione WebSocket.

Descrizione

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.

Proprietà

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

Metodi

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

Enumerazioni

enum WriteMode: 🔗

WriteMode WRITE_MODE_TEXT = 0

Specifica che i messaggi di WebSocket devono essere trasferiti sotto forma di testo (è consentito solo UTF-8 valido).

WriteMode WRITE_MODE_BINARY = 1

Specifica che i messaggi di WebSocket devono essere trasferiti sotto forma binaria (è consentita qualsiasi combinazione di byte).

enum State: 🔗

State STATE_CONNECTING = 0

Il socket è stato creato. La connessione non è ancora aperta.

State STATE_OPEN = 1

La connessione è aperta e pronta a comunicare.

State STATE_CLOSING = 2

La connessione è in fase di chiusura. Ciò significa che una richiesta di chiusura è stata inviata al peer remoto ma la conferma non è stata ricevuta.

State STATE_CLOSED = 3

La connessione è chiusa o non può essere aperta.

Descrizioni delle proprietà

PackedStringArray handshake_headers = PackedStringArray() 🔗

void set_handshake_headers(value: PackedStringArray)
PackedStringArray get_handshake_headers()

Le intestazioni HTTP aggiuntive da inviare durante l'handshake WebSocket.

Nota: Non supportato nelle esportazioni per Web a causa delle restrizioni dei browser.

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

L'intervallo (in secondi) in cui il peer invierà automaticamente frame di controllo "ping" WebSocket. Se impostato su 0, non verrà inviato alcun frame di controllo "ping".

Nota: Non ha alcun effetto nelle esportazioni Web a causa delle restrizioni dei browser.

int inbound_buffer_size = 65535 🔗

void set_inbound_buffer_size(value: int)
int get_inbound_buffer_size()

La dimensione del buffer di input in byte (più o menu la quantità massima di memoria che verrà allocata per i pacchetti in entrata).

int max_queued_packets = 4096 🔗

void set_max_queued_packets(value: int)
int get_max_queued_packets()

La quantità massima di pacchetti che saranno ammessi nelle code di attesa (sia in entrata sia in uscita).

int outbound_buffer_size = 65535 🔗

void set_outbound_buffer_size(value: int)
int get_outbound_buffer_size()

La dimensione del buffer di input in byte (più o meno la quantità massima di memoria che verrà allocata per i pacchetti in uscita).

PackedStringArray supported_protocols = PackedStringArray() 🔗

void set_supported_protocols(value: PackedStringArray)
PackedStringArray get_supported_protocols()

I sotto-protocolli di WebSocket consentiti durante l'handshake di WebSocket.

Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.

Descrizioni dei metodi

Error accept_stream(stream: StreamPeer) 🔗

Accetta una connessione di peer eseguendo l'handshake HTTP come server WebSocket. Il stream deve essere un flusso TCP valido recuperato tramite TCPServer.take_connection(), o un flusso TLS accettato tramite StreamPeerTLS.accept_stream().

Nota: Non supportato nelle esportazioni per Web a causa delle restrizioni dei browser.

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

Si collega all'URL indicato. I certificati TLS saranno verificati contro il nome host durante la connessione utilizzando il protocollo wss://. È possibile passare il parametro opzionale tls_client_options per personalizzare le autorità di certificazione attendibili, o disabilitare la verifica dei nomi comuni. Vedi TLSOptions.client() e TLSOptions.client_unsafe().

Nota: Questo metodo non è bloccante e restituirà @GlobalScope.OK prima che la connessione venga stabilita, a patto che i parametri forniti siano validi e il peer non si trovi in uno stato non valido (ad esempio, già connesso). Chiama regolarmente poll() (ad esempio, durante il processo di un Node) e controlla il risultato di get_ready_state() per sapere se la connessione riesce o fallisce.

Nota: Per evitare avvisi o errori di contenuti misti in Web, potresti dover usare un url che inizia con wss:// (sicuro) invece di ws://. In questo modo, assicurati di utilizzare il nome di dominio completamente qualificato che corrisponde a quello definito nel certificato TLS del server. Non collegare direttamente tramite l'indirizzo IP per le connessioni wss://, in quanto non corrisponde al certificato TLS.

int get_close_code() const 🔗

Restituisce il codice di stato del frame di WebSocket, o -1 quando la connessione non è stata chiusa in maniera pulito. Chiama solo questo metodo quando get_ready_state() restituisce STATE_CLOSED.

String get_close_reason() const 🔗

Restituisce la stringa che rappresenta il motivo di stato di chiusura del frame WebSocket ricevuta. Chiama solo questo metodo quando get_ready_state() restituisce STATE_CLOSED.

String get_connected_host() const 🔗

Restituisce l'indirizzo IP del peer connesso.

Nota: Non disponibile nell'esportazione per Web.

int get_connected_port() const 🔗

Restituisce la porta remota del peer connesso.

Nota: Non disponibile nell'esportazione per Web.

int get_current_outbound_buffered_amount() const 🔗

Restituisce la quantità attuale dei dati nel buffer di websocket in uscita. Nota: Le esportazioni Web utilizzano WebSocket.bufferedAmount, mentre altre piattaforme utilizzano un buffer interno.

State get_ready_state() const 🔗

Restituisce lo stato di disponibilità della connessione.

String get_requested_url() const 🔗

Restituisce l'URL richiesto da questo peer. L'URL deriva dal url passato a connect_to_url() o dalle intestazioni HTTP quando agisce come server (ossia quando si utilizza accept_stream()).

String get_selected_protocol() const 🔗

Restituisce il sotto-protocollo WebSocket selezionato per questa connessione o una stringa vuota se il sotto-protocollo non è stato ancora selezionato.

void poll() 🔗

Aggiorna lo stato di connessione e riceve i pacchetti in arrivo. Chiama questa funzione regolarmente per mantenerla in uno stato pulito.

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

Invia il messaggio message utilizzando la modalità di scrittura desiderata (write_mode). Quando si invia una String, preferisci usare send_text().

Error send_text(message: String) 🔗

Invia il messaggio message utilizzando la modalità di testo WebSocket. Preferisci questo metodo piuttosto che PacketPeer.put_packet() quando interagisci con API basata su testo di terze parti (ad esempio quando si utilizzano messaggi formattati in JSON).

void set_no_delay(enabled: bool) 🔗

Disattiva l'algoritmo di Nagle sul socket TCP sottostante (predefinito). Vedi StreamPeerTCP.set_no_delay() per ulteriori informazioni.

Nota: Non disponibile nell'esportazione per Web.

bool was_string_packet() const 🔗

Restituisce true se l'ultimo pacchetto ricevuto è stato inviato come un payload di testo. Vedi WriteMode.