RTCPeerConnection: addIceCandidate() Methode

candidate Optional

Ein RTCIceCandidate-Objekt oder ein Objekt, das die folgenden Eigenschaften hat:

candidate Optional

Ein String, der die Eigenschaften des Kandidaten beschreibt, direkt entnommen aus dem SDP-Attribut "candidate". Der Kandidaten-String gibt die Netzwerkkonnektivitätsinformationen für den Kandidaten an. Wenn der candidate ein Leerstring ("") ist, wurde das Ende der Kandidatenliste erreicht; dieser Kandidat ist als "end-of-candidates"-Marker bekannt.

Die Syntax des Kandidaten-Strings wird in RFC 5245, Abschnitt 15.1 beschrieben. Für eine a-line (Attributzeile), die so aussieht:

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host

wird der entsprechende Wert des candidate-Strings lauten:

"candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host"`

Der user agent bevorzugt immer Kandidaten mit der höchsten priority, wenn sonst alles gleich ist. Im obigen Beispiel beträgt die Priorität 2043278322. Die Attribute sind alle durch ein einzelnes Leerzeichen getrennt und in einer bestimmten Reihenfolge. Die vollständige Liste der Attribute für diesen Beispielkandidaten ist:

• foundation = 4234997325
• component = "rtp" (die Zahl 1 wird in diesen String kodiert; 2 wird zu "rtcp")
• protocol = "udp"
• priority = 2043278322
• ip = "192.0.2.172"
• port = 44323
• type = "host"

Zusätzliche Informationen finden Sie in RTCIceCandidate.candidate.

Hinweis: Zur Abwärtskompatibilität mit älteren Versionen der WebRTC-Spezifikation akzeptiert der Konstruktor diesen String auch direkt als Argument.

sdpMid Optional

Ein String, der das Identifizierungstoken des Medienstreams enthält, mit dem der Kandidat verknüpft ist, oder null, wenn kein zugeordneter Medienstream vorhanden ist. Der Standardwert ist null.

Zusätzliche Informationen finden Sie in RTCIceCandidate.sdpMid.

sdpMLineIndex Optional

Eine Zahleneigenschaft, die den nullbasierten Index der m-line enthält, mit der der Kandidat innerhalb der SDP der Medienbeschreibung verknüpft ist, oder null, wenn keine solche Zuordnung besteht. Der Standardwert ist null.

Zusätzliche Informationen finden Sie in RTCIceCandidate.sdpMLineIndex.

usernameFragment Optional

Ein String, der das Benutzernamensfragment enthält (normalerweise in Kurzform als "ufrag" oder "ice-ufrag" bezeichnet). Dieses Fragment, zusammen mit dem ICE-Passwort ("ice-pwd"), identifiziert eindeutig eine einzelne laufende ICE-Interaktion (einschließlich jeglicher Kommunikation mit dem STUN-Server).

Der String wird von WebRTC zu Beginn der Sitzung generiert. Er kann bis zu 256 Zeichen lang sein, und mindestens 24 Bits müssen Zufallsdaten enthalten. Er hat keinen Standardwert und ist nicht vorhanden, es sei denn, er wird explizit gesetzt.

Zusätzliche Informationen finden Sie in RTCIceCandidate.usernameFragment.

Die Methode wirft eine TypeError-Ausnahme, wenn sowohl sdpMid als auch sdpMLineIndex null sind.

Der Inhalt des Objekts sollte aus einer Nachricht konstruiert werden, die über den Signalisierungskanal empfangen wurde und einen neu empfangenen ICE-Kandidaten beschreibt, der bereit ist, an den lokalen ICE-Agenten übermittelt zu werden.

Wenn kein candidate-Objekt angegeben wird oder sein Wert null ist, wird ein End-of-Candidates-Signal unter Verwendung der end-of-candidates a-line an den Remote-Peer gesendet, formatiert wie folgt:

a=end-of-candidates

In älterem Code und Dokumentationen können Sie eine Callback-basierte Version dieser Funktion sehen. Diese ist veraltet, und ihre Verwendung wird dringend abgeraten. Sie sollten vorhandenen Code aktualisieren, um die Promise-basierte Version von addIceCandidate() stattdessen zu verwenden. Die Parameter der älteren Form von addIceCandidate() sind unten beschrieben, um beim Aktualisieren vorhandenen Codes zu helfen.

successCallback Veraltet

Eine Funktion, die aufgerufen wird, wenn der ICE-Kandidat erfolgreich hinzugefügt wurde. Diese Funktion erhält keine Eingabeparameter und gibt keinen Wert zurück.

failureCallback Veraltet

Eine Funktion, die aufgerufen wird, wenn der Versuch, den ICE-Kandidaten hinzuzufügen, fehlschlägt. Sie erhält als Eingabe ein DOMException-Objekt, das beschreibt, warum der Fehler aufgetreten ist.

Ein Promise, das erfüllt wird, wenn der Kandidat erfolgreich von dem ICE-Agenten zur Beschreibung des Remote-Peers hinzugefügt wurde. Das Promise erhält keine Eingabeparameter.

Wenn ein Fehler beim Versuch auftritt, den ICE-Kandidaten hinzuzufügen, wird das von dieser Methode zurückgegebene Promise abgelehnt und gibt einen der unten aufgeführten Fehler als name-Attribut im angegebenen DOMException-Objekt zurück, das an den Ablehnungs-Handler übergeben wird.

TypeError

Wird zurückgegeben, wenn sowohl sdpMid als auch sdpMLineIndex des angegebenen Kandidaten null sind.

InvalidStateError DOMException

Wird zurückgegeben, wenn die RTCPeerConnection derzeit keinen Remote-Peer hat (remoteDescription ist null).

OperationError DOMException

Wird in einer der folgenden Situationen zurückgegeben:

• Der angegebene Wert für sdpMid ist nicht-null und stimmt nicht mit der Medienbeschreibungs-ID einer Medienbeschreibung in der remoteDescription überein.
• Der angegebene Wert von sdpMLineIndex ist größer oder gleich der Anzahl der in der Remote-Beschreibung enthaltenen Medienbeschreibungen.
• Das angegebene ufrag stimmt nicht mit dem ufrag-Feld in einer der in Betracht gezogenen Remote-Beschreibungen überein.
• Einer oder mehrere Werte im candidate-String sind ungültig oder konnten nicht analysiert werden.
• Jeglicher Versuch, den Kandidaten hinzuzufügen, schlägt aus irgendeinem Grund fehl.

Dieses Code-Snippet zeigt, wie Sie ICE-Kandidaten über einen beliebigen Signalisierungskanal signalisieren können.

// This example assumes that the other peer is using a signaling channel as follows:
//
// pc.onicecandidate = (event) => {
//   if (event.candidate) {
//     signalingChannel.send(JSON.stringify({ice: event.candidate})); // "ice" is arbitrary
//   } else {
//     // All ICE candidates have been sent
//   }
// }

signalingChannel.onmessage = (receivedString) => {
  const message = JSON.parse(receivedString);
  if (message.ice) {
    // A typical value of ice here might look something like this:
    //
    // {candidate: "candidate:0 1 UDP 2122154243 192.0.2.43 53421 typ host", sdpMid: "0", …}
    //
    // Pass the whole thing to addIceCandidate:

    pc.addIceCandidate(message.ice).catch((e) => {
      console.log(`Failure during addIceCandidate(): ${e.name}`);
    });
  } else {
    // handle other things you might be signaling, like sdp
  }
};

Der letzte Kandidat, der auf diese Weise vom Remote-Peer signalisiert wird, ist ein spezieller Kandidat, der das Ende der Kandidaten signalisiert. Aus Interesse kann das Ende der Kandidaten manuell wie folgt angegeben werden:

pc.addIceCandidate({ candidate: "" });

In den meisten Fällen müssen Sie jedoch nicht ausdrücklich nach diesem suchen, da die Ereignisse, die die RTCPeerConnection steuern, dies für Sie erledigen und die entsprechenden Ereignisse senden werden.

• WebRTC API
• Signalisierung und Videoanrufe
• Einführung in WebRTC-Protokolle
• WebRTC-Konnektivität
• Lebensdauer einer WebRTC-Sitzung