RTCPeerConnection: Methode addIceCandidate()

candidate Optional

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

candidate Optional

Eine Zeichenfolge, die die Eigenschaften des Kandidaten beschreibt, direkt aus dem SDP-Attribut "candidate" entnommen. Die Kandidatenzeichenfolge spezifiziert die Netzwerkkonnektivitätsinformationen für den Kandidaten. Wenn der candidate eine leere Zeichenkette ("") ist, wurde das Ende der Kandidatenliste erreicht; dieser Kandidat ist als "Ende-der-Kandidaten"-Marker bekannt.

Die Syntax der Kandidatenzeichenfolge 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 der candidate-Zeichenfolge sein:

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

Der User-Agent bevorzugt immer Kandidaten mit der höchsten priority, wenn alles andere gleich ist. Im obigen Beispiel ist 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 diese Zeichenkette kodiert; 2 wird zu "rtcp")
• protocol = "udp"
• priority = 2043278322
• ip = "192.0.2.172"
• port = 44323
• type = "host"

Weitere Informationen finden Sie in RTCIceCandidate.candidate.

Hinweis: Für die Abwärtskompatibilität mit älteren Versionen der WebRTC-Spezifikation akzeptiert der Konstruktor diese Zeichenkette auch direkt als Argument.

sdpMid Optional

Eine Zeichenfolge, die das Identifikations-Tag des Medienstroms enthält, mit dem der Kandidat verknüpft ist, oder null, wenn kein zugehöriger Medienstrom vorhanden ist. Der Standardwert ist null.

Weitere Informationen finden Sie in RTCIceCandidate.sdpMid.

sdpMLineIndex Optional

Eine Zahlen-Eigenschaft, die den null-basierten Index der m-line enthält, mit der der Kandidat im SDP der Medienbeschreibung verknüpft ist, oder null, wenn keine solche Verknüpfung vorhanden ist. Der Standardwert ist null.

Weitere Informationen finden Sie in RTCIceCandidate.sdpMLineIndex.

usernameFragment Optional

Eine Zeichenfolge, die das Benutzernamen-Fragment enthält (in der Regel als "ufrag" oder "ice-ufrag" abgekürzt). Dieses Fragment, zusammen mit dem ICE-Passwort ("ice-pwd"), identifiziert eindeutig eine einzelne laufende ICE-Interaktion (einschließlich der Kommunikation mit dem STUN-Server).

Die Zeichenfolge wird von WebRTC zu Beginn der Sitzung erzeugt. Sie kann bis zu 256 Zeichen lang sein und mindestens 24 Bit müssen zufällige Daten enthalten. Sie hat keinen Standardwert und ist nicht vorhanden, außer sie wird explizit gesetzt.

Weitere 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 erstellt werden, die über den Signalisierungskanal empfangen wurde und einen neu empfangenen ICE-Kandidaten beschreibt, der an den lokalen ICE-Agenten geliefert werden soll.

Wenn kein candidate-Objekt angegeben ist oder dessen Wert null ist, wird ein Ende-der-Kandidaten-Signal an den Remote-Peer mit der end-of-candidates a-line gesendet, die wie folgt formatiert ist:

a=end-of-candidates

In älterem Code und Dokumentation könnte eine rückrufbasierte Version dieser Funktion zu sehen sein. Diese wurde veraltet und ihre Verwendung ist stark abzuraten. Sie sollten vorhandenen Code aktualisieren, um die auf Promise basierende Version von addIceCandidate() zu verwenden. Die Parameter für die ältere Form von addIceCandidate() sind unten beschrieben, um bei der Aktualisierung 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 das Hinzufügen des ICE-Kandidaten fehlschlägt. Sie erhält 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 Remote-Beschreibung des Remote-Peers hinzugefügt wurde. Das Versprechen erhält keine Eingabeparameter.

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

TypeError

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

InvalidStateError DOMException

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

OperationError DOMException

Wird in einer der folgenden Situationen zurückgegeben:

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

Dieses Codebeispiel zeigt, wie ICE-Kandidaten über einen beliebigen Signalisierungskanal signalisiert werden.

// 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 anzeigt. Aus Interesse kann Ende-der-Kandidaten wie folgt manuell angezeigt werden:

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

In den meisten Fällen müssen Sie jedoch nicht explizit danach suchen, da die Ereignisse, die die RTCPeerConnection ansteuern, dies für Sie erledigen und die entsprechenden Ereignisse senden werden.

• WebRTC API
• Signalisierung und Videotelefonie
• Einführung in die WebRTC-Protokolle
• WebRTC-Konnektivität
• Lebenszeit einer WebRTC-Sitzung