RTCPeerConnection: icecandidate Ereignis

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

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

onicecandidate = (event) => {};

Ein RTCPeerConnectionIceEvent. Erbt von Event.

Ein RTCPeerConnectionIceEvent, das ein Event ist, implementiert auch die folgende Eigenschaft.

RTCPeerConnectionIceEvent.candidate Schreibgeschützt

Gibt den RTCIceCandidate an, der den mit dem Ereignis verbundenen Kandidaten enthält. Dies wird der leere String sein, wenn das Ereignis anzeigt, dass keine weiteren Kandidaten in dieser Generation erwartet werden, oder null, wenn das gesamte ICE-Sammeln auf allen Transporten abgeschlossen ist.

Es gibt drei Gründe, warum das icecandidate Ereignis bei einer 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 entfernten Peer übermittelt werden.

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

Der entfernte Peer wird, nachdem er den Kandidaten erhalten hat, den Kandidaten seinem Kandidatenpool hinzufügen, indem er addIceCandidate() aufruft und den candidate String übergibt, den Sie über den Signalisierungsserver weitergeleitet haben.

Wenn eine ICE-Verhandlungssitzung keine Kandidaten mehr vorschlagen kann für einen gegebenen RTCIceTransport, hat sie das Sammeln für eine Generation von Kandidaten abgeschlossen. Dies wird durch ein icecandidate Ereignis angezeigt, dessen candidate String leer ist ("").

Sie sollten dies an den entfernten Peer übermitteln, genauso wie jeden Standardkandidaten, wie oben unter Teilen eines neuen Kandidaten beschrieben. Dies stellt sicher, dass der entfernte Peer ebenfalls die End-of-Candidates-Benachrichtigung erhält. Wie Sie im Code im vorherigen Abschnitt sehen, wird jeder Kandidat an den anderen Peer gesendet, einschließlich solcher, die möglicherweise einen leeren Kandidatenstring haben. Nur Kandidaten, für die die Eigenschaft candidate des Ereignisses null ist, werden nicht über die Signalisierungsverbindung weitergeleitet.

Die End-of-Candidates-Anzeige wird in Abschnitt 9.3 des Trickle ICE Entwurfsspezifikations beschrieben (beachten Sie, dass sich die Abschnittsnummer ändern kann, da die Spezifikation durch wiederholte Entwürfe geht).

Sobald alle ICE-Transporte das Sammeln von Kandidaten beendet haben und der Wert des RTCPeerConnection Objekts iceGatheringState den Übergang zu complete gemacht hat, wird ein icecandidate Ereignis mit dem Wert candidate auf null gesetzt gesendet.

Dieses Signal existiert aus Gründen der Abwärtskompatibilität und muss nicht an den entfernten Peer weitergeleitet werden (weshalb der oben gezeigte Code überprüft, ob event.candidate null ist, bevor der Kandidat weitergesendet wird).

Wenn Sie besondere Aktionen ausführen müssen, wenn keine weiteren Kandidaten erwartet werden, ist es viel besser, den Status des ICE-Sammelns 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 das ICE-Sammeln gerade beendet wurde.

Dies ist ein zuverlässigerer Ansatz, als die einzelnen ICE-Meldungen auf eine zu überprüfen, die anzeigt, dass die ICE-Sitzung 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 mit addEventListener():

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

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

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

• WebRTC API
• Signalisierung und Videoanrufe