RTCPeerConnection: icecandidate-Ereignis

Syntax

Verwenden Sie den Ereignisnamen in addEventListener():

addEventListener("icecandidate", (event) => { })

Alternativ können Sie ihn der Ereignishandler-Eigenschaft der Schnittstelle zuweisen:

onicecandidate = (event) => { }

Ereignistyp

Ein RTCPeerConnectionIceEvent. Erbt von Event.

Beschreibung

Es gibt drei Gründe, aus denen das icecandidate-Ereignis auf einer RTCPeerConnection ausgelöst wird.

Einen neuen Kandidaten übermitteln

Die meisten icecandidate-Ereignisse werden ausgelöst, um anzuzeigen, dass ein neuer Kandidat gesammelt wurde. Dieser Kandidat muss über den Signalisierungskanal, den Ihr Code verwaltet, an den entfernten Peer übermittelt werden.

rtcPeerConnection.onicecandidate = (event) => {
  if (event.candidate !== null) {
    sendCandidateToRemotePeer(event.candidate);
  } else {
    /* there are no more candidates coming during this negotiation */
  }
};

Nach Empfang des Kandidaten fügt der entfernte Peer ihn seinem Kandidatenpool hinzu, indem er addIceCandidate() aufruft und dabei den candidate-String übergibt, den Sie über den Signalisierungsserver weitergeleitet haben.

Das Ende einer Kandidatengeneration anzeigen

Wenn einer ICE-Aushandlungssitzung für einen bestimmten RTCIceTransport keine weiteren Kandidaten mehr zur Verfügung stehen, ist das Sammeln für eine Generation von Kandidaten abgeschlossen. Dies wird durch ein icecandidate-Ereignis angezeigt, dessen candidate-String leer ist ("").

Sie sollten dieses Ereignis wie jeden gewöhnlichen Kandidaten an den entfernten Peer übermitteln, wie oben unter Einen neuen Kandidaten übermitteln beschrieben. So erhält auch der entfernte Peer die Benachrichtigung über das Ende der Kandidaten. Wie Sie im Code des vorherigen Abschnitts sehen, wird jeder Kandidat an den anderen Peer gesendet, auch wenn sein Kandidaten-String leer ist. Nur Kandidaten, bei denen die candidate-Eigenschaft des Ereignisses null ist, werden nicht über die Signalisierungsverbindung weitergeleitet.

Die Anzeige des Kandidatenendes ist in Abschnitt 9.3 des Trickle-ICE-Spezifikationsentwurfs beschrieben (beachten Sie, dass sich die Abschnittsnummer mit weiteren Entwurfsfassungen der Spezifikation ändern kann).

Anzeigen, dass das ICE-Sammeln abgeschlossen ist

Sobald alle ICE-Transporte das Sammeln von Kandidaten beendet haben und der Wert von iceGatheringState des RTCPeerConnection-Objekts zu complete gewechselt ist, wird ein icecandidate-Ereignis gesendet, bei dem candidate auf null gesetzt ist.

Dieses Signal dient der Abwärtskompatibilität und muss nicht an den entfernten Peer weitergeleitet werden. Deshalb prüft das obige Codebeispiel vor dem Weiterleiten des Kandidaten, ob event.candidate den Wert null hat.

Wenn Sie besondere Aktionen ausführen müssen, sobald keine weiteren Kandidaten mehr zu erwarten sind, sollten Sie stattdessen den ICE-Sammelzustand anhand von icegatheringstatechange-Ereignissen beobachten:

pc.addEventListener("icegatheringstatechange", (ev) => {
  switch (pc.iceGatheringState) {
    case "new":
      /* gathering is either just starting or has been reset */
      break;
    case "gathering":
      /* gathering has begun or is ongoing */
      break;
    case "complete":
      /* gathering has ended */
      break;
  }
});

Wie dieses Beispiel zeigt, informiert Sie das icegatheringstatechange-Ereignis darüber, dass der Wert der Eigenschaft iceGatheringState der RTCPeerConnection aktualisiert wurde. Hat der Wert nun complete, wissen Sie, dass das ICE-Sammeln gerade beendet wurde.

Dieser Ansatz ist zuverlässiger, als die einzelnen ICE-Nachrichten nach einem Hinweis auf das Ende der ICE-Sitzung zu durchsuchen.

Beispiele

Dieses Beispiel erstellt einen einfachen Handler für das icecandidate-Ereignis. Er verwendet eine Funktion namens sendMessage(), um über den Signalisierungsserver eine Antwort an den entfernten Peer zu erstellen und zu senden.

Zunächst ein Beispiel mit addEventListener():

pc.addEventListener("icecandidate", (ev) => {
  if (ev.candidate !== null) {
    sendMessage({
      type: "new-ice-candidate",
      candidate: ev.candidate,
    });
  }
});

Sie können die Ereignishandler-Eigenschaft onicecandidate auch direkt setzen. Beachten Sie jedoch, dass dadurch gegebenenfalls andere über onicecandidate hinzugefügte Ereignislistener ersetzt werden:

pc.onicecandidate = (ev) => {
  if (ev.candidate !== null) {
    sendMessage({
      type: "new-ice-candidate",
      candidate: ev.candidate,
    });
  }
};

Spezifikationen

Browser-Kompatibilität

Siehe auch

• WebRTC-API
• Signalisierung und Videoanrufe