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...

WebRTCPeerConnection

Eredita: RefCounted < Object

Ereditato da: WebRTCPeerConnectionExtension

Interfaccia per una connessione di peer via WebRTC.

Descrizione

A WebRTC connection between the local computer and a remote peer. Provides an interface to connect, maintain, and monitor the connection.

Setting up a WebRTC connection between two peers may not seem a trivial task, but it can be broken down into 3 main steps:

• The peer that wants to initiate the connection (A from now on) creates an offer and sends it to the other peer (B from now on).

• B receives the offer, generates an answer, and sends it to A.

• A and B then generate and exchange ICE candidates with each other.

After these steps, the connection should be established. Refer to the linked tutorials for details.

Tutorial

• WebRTC documentation

• API Multigiocatore di alto livello

Metodi

Error	add_ice_candidate(media: String, index: int, name: String)
void	close()
WebRTCDataChannel	create_data_channel(label: String, options: Dictionary = {})
Error	create_offer()
ConnectionState	get_connection_state() const
GatheringState	get_gathering_state() const
SignalingState	get_signaling_state() const
Error	initialize(configuration: Dictionary = {})
Error	poll()
void	set_default_extension(extension_class: StringName) static
Error	set_local_description(type: String, sdp: String)
Error	set_remote_description(type: String, sdp: String)

---

Segnali

data_channel_received(channel: WebRTCDataChannel) 🔗

Emesso quando viene ricevuto un nuovo canale in banda, ossia quando il canale è stato creato con negotiated: false (predefinito).

L'oggetto sarà un'istanza di WebRTCDataChannel. È necessario mantenere un riferimento ad esso o sarà chiuso automaticamente. Vedi create_data_channel().

---

ice_candidate_created(media: String, index: int, name: String) 🔗

Emesso quando viene creato un nuovo candidato ICE. I tre parametri dovrebbero essere trasmessi al peer remoto sul server di segnalazione.

---

session_description_created(type: String, sdp: String) 🔗

Emesso dopo una chiamata avvenuta con successo a create_offer() o set_remote_description() (quando genera una risposta). I parametri dovrebbero essere passati a set_local_description() su questo oggetto, e inviati al peer remoto sul server di segnalazione.

---

Enumerazioni

enum ConnectionState: 🔗

ConnectionState STATE_NEW = 0

La connessione è nuova, i canali di dati e un'offerta possono essere creati in questo stato.

ConnectionState STATE_CONNECTING = 1

Il peer si sta collegando, l'ICE è in corso, nessuno dei trasporti ha fallito.

ConnectionState STATE_CONNECTED = 2

Il peer è collegato, tutti i trasporti ICE sono collegati.

ConnectionState STATE_DISCONNECTED = 3

Almeno un trasporto ICE è scollegato.

ConnectionState STATE_FAILED = 4

Uno o più dei trasporti ICE hanno fallito.

ConnectionState STATE_CLOSED = 5

La connessione per i peer è chiusa (dopo aver chiamato close() per esempio).

---

enum GatheringState: 🔗

GatheringState GATHERING_STATE_NEW = 0

La connessione per i peer è stata appena creata e non ha ancora effettuato niente per il network.

GatheringState GATHERING_STATE_GATHERING = 1

L'agente ICE è in fase di raccolta dei candidati per la connessione.

GatheringState GATHERING_STATE_COMPLETE = 2

L'agente ICE ha finito di raccogliere candidati. Se succede qualcosa che richiede la raccolta di nuovi candidati, come ad esempio una nuova interfaccia che viene aggiunta o l'aggiunta di un nuovo server ICE, lo stato tornerà a riunirsi per raccogliere quei candidati.

---

enum SignalingState: 🔗

SignalingState SIGNALING_STATE_STABLE = 0

Non esiste uno scambio continuo di offerte e risposte in corso. Ciò può significare che la WebRTCPeerConnection è nuova (STATE_NEW) o che la negoziazione è completa e una connessione è stata stabilita (STATE_CONNECTED).

SignalingState SIGNALING_STATE_HAVE_LOCAL_OFFER = 1

Il peer locale ha chiamato set_local_description(), passando un SDP che rappresenta un'offerta (solitamente creata chiamando create_offer()), e l'offerta è stata applicata con successo.

SignalingState SIGNALING_STATE_HAVE_REMOTE_OFFER = 2

Il peer remoto ha creato un'offerta e utilizzato il server di segnalazione per consegnarla al peer locale, che ha impostato l'offerta come descrizione remota chiamando set_remote_description().

SignalingState SIGNALING_STATE_HAVE_LOCAL_PRANSWER = 3

L'offerta inviata dal peer remoto è stata applicata e una risposta è stata creata e applicata chiamando set_local_description(). Questa risposta provvisoria descrive i formati multimediali supportati e simili, ma potrebbe non avere una serie completa di candidati ICE inclusi. Ulteriori candidati saranno consegnati separatamente in seguito.

SignalingState SIGNALING_STATE_HAVE_REMOTE_PRANSWER = 4

Una risposta provvisoria è stata ricevuta e applicata con successo in risposta a un'offerta precedentemente inviata e stabilita chiamando set_local_description().

SignalingState SIGNALING_STATE_CLOSED = 5

La WebRTCPeerConnection è stata chiusa.

---

Descrizioni dei metodi

Error add_ice_candidate(media: String, index: int, name: String) 🔗

Aggiunge un candidato ICE generato da un peer remoto (e ricevuto sul server di segnalazione). Vedi ice_candidate_created.

---

void close() 🔗

Chiude la connessione di peer e tutti i canali di dati associati ad esso.

Nota: Non puoi riutilizzare questo oggetto per una nuova connessione a meno che non chiami initialize().

---

WebRTCDataChannel create_data_channel(label: String, options: Dictionary = {}) 🔗

Restituisce un nuovo WebRTCDataChannel (o null in caso di errore) con l'etichetta label e opzionalmente configurato tramite il dizionario options. Questo metodo può essere chiamato solo quando la connessione è nello stato STATE_NEW.

Ci sono due modi per creare un canale funzionante di dati: chiamare create_data_channel() solo su uno dei peer e ascoltare data_channel_received sull'altro, oppure chiamare create_data_channel() su entrambi i peer, con gli stessi valori e l'opzione "negotiated" impostata su true.

Le options valide sono:

{
    "negotiated": true, # Se impostato su true (default off), significa che il canale è negoziato fuori banda. Anche "id" deve essere impostato. "data_channel_received" non verrà chiamato.
    "id": 1, # Se "negotiated" è true, questo valore deve essere impostato sullo stesso valore su entrambi i peer.

    # È possibile specificare solo uno tra "maxRetransmits" e "maxPacketLifeTime", non entrambi. Rendono il canale inaffidabile (ma anche più veloce in tempo reale).
    "maxRetransmits": 1, # Specifica il numero massimo di tentativi che il peer farà per ritrasmettere i pacchetti se non vengono riconosciuti.
    "maxPacketLifeTime": 100, # Specifica la quantità massima di tempo prima di rinunciare alle ritrasmissioni di pacchetti non riconosciuti (in millisecondi).
    "ordered": true, # In modalità non affidabile (ad esempio, è impostato "maxRetransmits" o "maxPacketLifetime"), "ordered" (true per impostazione predefinita) specifica se deve essere applicato l'ordinamento dei pacchetti.

    "protocol": "my-custom-protocol", # Una stringa di sottoprotocollo personalizzata per questo canale.
}

Nota: È necessario mantenere un riferimento ai canali creati in questo modo, altrimenti verranno chiusi.

---

Error create_offer() 🔗

Crea una nuova offerta SDP per avviare una connessione WebRTC con un peer remoto. Almeno un WebRTCDataChannel deve essere stato creato prima di chiamare questo metodo.

Se questa funzione restituisce @GlobalScope.OK, session_description_created verrà chiamato quando la sessione è pronta per essere inviata.

---

ConnectionState get_connection_state() const 🔗

Restituisce lo stato della connessione.

---

GatheringState get_gathering_state() const 🔗

Restituisce lo stato di raccolta ICE (GatheringState) della connessione. Ciò consente di rilevare, ad esempio, quando la raccolta dei candidati ICE è terminata.

---

SignalingState get_signaling_state() const 🔗

Restituisce lo stato di segnalazione sul lato locale della connessione mentre si collega o si riconnette a un altro peer.

---

Error initialize(configuration: Dictionary = {}) 🔗

Reinizializza questa connessione peer, chiudendo qualsiasi connessione precedentemente attiva, e torna allo stato STATE_NEW. È possibile passare un dizionario di opzioniconfiguration per configurare la connessione peer.

Le opzioni valide per configuration sono:

{
    "iceServers": [
        {
            "urls": [ "stun:stun.example.com:3478" ], # Uno o più server STUN.
        },
        {
            "urls": [ "turn:turn.example.com:3478" ], # Uno o più server TURN.
            "username": "a_username", # Nome utente facoltativo per il server TURN.
            "credential": "a_password", # Password facoltativa per il server TURN.
        }
    ]
}

---

Error poll() 🔗

Chiama frequentemente questo metodo (ad esempio in Node._process() o Node._physics_process()) per ricevere correttamente i segnali.

---

void set_default_extension(extension_class: StringName) static 🔗

Imposta il extension_class come il WebRTCPeerConnectionExtension predefinito, che è restituito quando si crea un nuovo WebRTCPeerConnection.

---

Error set_local_description(type: String, sdp: String) 🔗

Imposta la descrizione SDP del locale peer. Questo dovrebbe essere chiamato in risposta a session_description_created.

Dopo aver chiamato questa funzione, il peer inizierà a emettere ice_candidate_created (a meno che non venga restituito un Error diverso da @GlobalScope.OK).

---

Error set_remote_description(type: String, sdp: String) 🔗

Imposta la descrizione SDP del peer remoto. Questo dovrebbe essere chiamato con i valori generati da un peer remoto e ricevuti sul server di segnalazione.

Se type è "offer" il peer emetterà session_description_created con la risposta appropriata.

Se type è "risposta" il peer inizierà a emettere ice_candidate_created.