RTCPeerConnection: Methode setRemoteDescription()

Syntax

setRemoteDescription(sessionDescription)

// deprecated
setRemoteDescription(sessionDescription, successCallback, errorCallback)

Parameter

sessionDescription

Ein Objekt, das das aktuelle Angebot oder die aktuelle Antwort des entfernten Peers angibt. Es sollte die folgenden Eigenschaften enthalten:

type

Ein String, der den Typ der Sitzungsbeschreibung angibt. Siehe RTCSessionDescription.type.

sdp Optional

Ein String mit dem SDP, das die Sitzung beschreibt. Wenn sdp nicht angegeben wird, ist der Standardwert ein leerer String. Wenn type "rollback" ist, muss sdp null oder ein leerer String sein. Siehe RTCSessionDescription.sdp.

Sie können auch eine Instanz von RTCSessionDescription übergeben; das macht jedoch keinen Unterschied. Aus diesem Grund ist der Konstruktor RTCSessionDescription veraltet.

In älterem Code und älterer Dokumentation finden Sie möglicherweise eine Callback-basierte Version dieser Funktion. Diese ist veraltet, und von ihrer Verwendung wird dringend abgeraten. Sie sollten vorhandenen Code aktualisieren und stattdessen die auf Promise basierende Version von setRemoteDescription() verwenden. Die Parameter der älteren Form von setRemoteDescription() sind im Folgenden beschrieben, um die Aktualisierung vorhandenen Codes zu erleichtern.

successCallback

Eine JavaScript-Function ohne Eingabeparameter, die aufgerufen wird, sobald die Beschreibung erfolgreich festgelegt wurde. Zu diesem Zeitpunkt kann das Angebot über den Signalisierungsserver an einen entfernten Peer gesendet werden.

errorCallback

Eine Funktion mit der Signatur RTCPeerConnectionErrorCallback, die aufgerufen wird, wenn die Beschreibung nicht festgelegt werden kann. Ihr wird ein einzelnes DOMException-Objekt übergeben, das erklärt, warum die Anfrage fehlgeschlagen ist.

Diese veraltete Form der Methode gibt sofort einen Wert zurück, ohne darauf zu warten, dass die Beschreibung tatsächlich festgelegt wird: Bei Erfolg wird successCallback aufgerufen, bei einem Fehler errorCallback.

Rückgabewert

Ein Promise, das erfüllt wird, sobald der Wert von remoteDescription der Verbindung erfolgreich geändert wurde. Es wird zurückgewiesen, wenn die Änderung nicht angewendet werden kann (beispielsweise, wenn die angegebene Beschreibung mit einem oder beiden Peers der Verbindung nicht kompatibel ist). Der Handler für die Erfüllung des Promise erhält keine Eingabeparameter.

Ausnahmen

Die folgenden Ausnahmen werden an den Handler für die Zurückweisung des von setRemoteDescription() zurückgegebenen Promise übergeben:

InvalidAccessError DOMException

Wird zurückgegeben, wenn der Inhalt der Beschreibung ungültig ist.

InvalidStateError DOMException

Wird zurückgegeben, wenn RTCPeerConnection geschlossen ist oder sich in einem Zustand befindet, der nicht mit dem type der angegebenen Beschreibung kompatibel ist. Diese Ausnahme wird beispielsweise ausgelöst, wenn type den Wert rollback hat und der Signalisierungszustand stable, have-local-pranswer oder have-remote-pranswer ist. Eine Verbindung kann nicht zurückgesetzt werden, wenn sie bereits vollständig hergestellt ist oder kurz vor dem Abschluss des Verbindungsaufbaus steht.

OperationError DOMException

Wird zurückgegeben, wenn ein Fehler auftritt, der keiner der hier genannten Ausnahmen entspricht. Dazu gehören Fehler bei der Identitätsprüfung.

RTCError

Wird mit dem Wert sdp-syntax-error für errorDetail zurückgegeben, wenn das durch RTCSessionDescription.sdp angegebene SDP ungültig ist. Die Eigenschaft sdpLineNumber des Fehlerobjekts gibt die Zeilennummer innerhalb des SDP an, in der der Syntaxfehler erkannt wurde.

TypeError

Wird zurückgegeben, wenn bei sessionDescription die Eigenschaft type fehlt oder überhaupt kein Beschreibungsparameter angegeben wurde.

Bei Verwendung der veralteten Callback-basierten Version von setRemoteDescription() können die folgenden Ausnahmen auftreten:

InvalidStateError

Der signalingState der Verbindung ist "closed". Das bedeutet, dass die Verbindung derzeit nicht geöffnet ist und daher keine Aushandlung stattfinden kann.

InvalidSessionDescriptionError

Der Parameter sessionDescription ist ungültig.

Hinweise zur Verwendung

Wenn Sie setRemoteDescription() aufrufen, prüft der ICE-Agent, ob sich RTCPeerConnection im signalingState stable oder have-remote-offer befindet. Diese Zustände zeigen an, dass entweder eine bestehende Verbindung neu ausgehandelt wird oder ein Angebot, das bei einem früheren Aufruf von setRemoteDescription() angegeben wurde, durch das neue Angebot ersetzt werden soll. In beiden Fällen befindet sich der Aushandlungsprozess am Anfang, und das Angebot wird als entfernte Beschreibung festgelegt.

Wenn sich die Verbindung dagegen mitten in einer laufenden Aushandlung befindet und ein Angebot an setRemoteDescription() übergeben wird, beginnt der ICE-Agent automatisch ein ICE-Rollback, um die Verbindung in einen stabilen Signalisierungszustand zurückzuführen. Sobald das Rollback abgeschlossen ist, legt er das angegebene Angebot als entfernte Beschreibung fest. Damit beginnt eine neue Aushandlung, deren Ausgangspunkt das neu festgelegte Angebot ist.

Zu Beginn der neuen Aushandlung mit dem neu festgelegten Angebot ist der lokale Peer nun der Angerufene, auch wenn er zuvor der Anrufer war. Statt eine Ausnahme auszulösen, verringert dieses Verhalten die Zahl möglicher Fehler. Außerdem vereinfacht es die Verarbeitung eingehender Angebote: Sie müssen den Angebots- und Antwortprozess nicht unterschiedlich behandeln, je nachdem, ob der lokale Peer Anrufer oder Angerufener ist.

Beispiele

Hier sehen Sie eine Funktion, die ein vom entfernten Peer empfangenes Angebot verarbeitet. Dieser Code stammt aus dem Beispiel und dem Tutorial im Artikel Signalisierung und Videoanrufe. Dort finden Sie weitere Einzelheiten und eine ausführlichere Erklärung der Abläufe.

function handleOffer(msg) {
  createMyPeerConnection();

  myPeerConnection
    .setRemoteDescription(msg.description)
    .then(() => navigator.mediaDevices.getUserMedia(mediaConstraints))
    .then((stream) => {
      document.getElementById("local_video").srcObject = stream;
      return myPeerConnection.addStream(stream);
    })
    .then(() => myPeerConnection.createAnswer())
    .then((answer) => myPeerConnection.setLocalDescription(answer))
    .then(() => {
      // Send the answer to the remote peer using the signaling server
    })
    .catch(handleGetUserMediaError);
}

Nachdem wir unsere RTCPeerConnection erstellt und als myPeerConnection gespeichert haben, übergeben wir die im empfangenen Angebot enthaltene Beschreibung aus der Nachricht msg direkt an setRemoteDescription(). So teilen wir der WebRTC-Schicht des User Agents mit, welche Konfiguration der Anrufer vorgeschlagen hat. Wenn der Handler für die Erfüllung unseres Promise aufgerufen wird und damit anzeigt, dass dies geschehen ist, erstellen wir einen Stream und fügen ihn der Verbindung hinzu. Anschließend erstellen wir eine SDP-Antwort und rufen setLocalDescription() auf, um sie als Konfiguration für unsere Seite des Anrufs festzulegen, bevor wir die Antwort an den Anrufer weiterleiten.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• WebRTC
• RTCPeerConnection.remoteDescription, RTCPeerConnection.pendingRemoteDescription, RTCPeerConnection.currentRemoteDescription
• RTCSessionDescription