RTCPeerConnection: icecandidate Ereignis

Verwenden Sie den Ereignisnamen in Methoden wie addEventListener() oder setzen Sie eine Ereignishandler-Eigenschaft.

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

onicecandidate = (event) => { }

Ein RTCPeerConnectionIceEvent. Erbt von Event.

Ein RTCPeerConnectionIceEvent ist ein Event, daher implementiert dieses Ereignis auch die folgende Eigenschaft.

RTCPeerConnectionIceEvent.candidate Schreibgeschützt

Gibt den RTCIceCandidate an, der den mit dem Ereignis assoziierten Kandidaten enthält. Dies wird der leere String sein, wenn das Ereignis anzeigt, dass keine weiteren Kandidaten in dieser Generation vorkommen, oder null, wenn alle ICE-Sammlungen auf allen Transporten abgeschlossen sind.

Es gibt drei Gründe, warum das icecandidate Ereignis auf einem RTCPeerConnection ausgelöst wird.

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

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

Der Remote-Peer wird, nachdem er den Kandidaten erhalten hat, den Kandidaten zu seinem Kandidatenpool hinzufügen, indem er addIceCandidate() aufruft und den von Ihnen über den Signalisierungsserver übermittelten candidate String übergibt.

Wenn eine ICE Aushandlungs-Session keine Kandidaten mehr für einen bestimmten RTCIceTransport vorschlagen kann, ist die Sammlung für eine Generation von Kandidaten abgeschlossen. Dies wird durch ein icecandidate Ereignis angezeigt, dessen candidate String leer ist ("").

Sie sollten dies an den Remote-Peer genauso wie einen normalen Kandidaten übermitteln, wie oben unter Teilen eines neuen Kandidaten beschrieben. Dies stellt sicher, dass der Remote-Peer auch die Benachrichtigung über das Ende der Kandidaten erhält. Wie Sie im letzten Abschnitt im Code sehen, wird jeder Kandidat an den anderen Peer gesendet, einschließlich solcher, die möglicherweise einen leeren Kandidaten-String haben. Nur Kandidaten, für die die candidate Eigenschaft des Ereignisses null ist, werden nicht über die Signalisierungsverbindung weitergeleitet.

Die Anzeige des Endes der Kandidaten ist in Abschnitt 9.3 des Trickel-ICE-Entwurfsspezifikations beschrieben (beachten Sie, dass sich die Abschnittsnummer ändern kann, da die Spezifikation fortlaufend überarbeitet wird).

Sobald alle ICE-Transporte das Sammeln von Kandidaten abgeschlossen haben und der Wert des RTCPeerConnection Objekts iceGatheringState auf complete übergegangen ist, wird ein icecandidate Ereignis mit dem Wert candidate auf null gesetzt.

Dieses Signal existiert für Zwecke der Rückwärtskompatibilität und muss nicht weiter an den Remote-Peer übermittelt werden (weshalb der obige Code-Schnipsel prüft, ob event.candidate null ist, bevor der Kandidat weitergeleitet wird).

Wenn Sie spezielle Aktionen ausführen müssen, wenn keine weiteren Kandidaten erwartet werden, ist es viel zuverlässiger, den Status der ICE-Sammlung zu beobachten, indem Sie auf icegatheringstatechange Ereignisse achten:

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 Sie in diesem Beispiel sehen, lässt Sie das icegatheringstatechange Ereignis wissen, wann der Wert der RTCPeerConnection Eigenschaft iceGatheringState aktualisiert wurde. Wenn dieser Wert jetzt complete ist, wissen Sie, dass die ICE-Sammlung gerade beendet wurde.

Dies ist ein zuverlässigerer Ansatz als das Prüfen der einzelnen ICE-Nachrichten, um zu erkennen, dass die ICE-Session beendet ist.

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

Zuerst ein Beispiel unter Verwendung von addEventListener():

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

Sie können die onicecandidate Ereignishandler-Eigenschaft auch direkt setzen:

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

• WebRTC API
• Signalisierung und Videoanrufe