DiesetRemoteDescription()-Methode derRTCPeerConnection-Schnittstelle setzt die angegebene Sitzungsbeschreibung als das aktuelle Angebot oder die aktuelle Antwort des entfernten Peers fest.Die Beschreibung gibt die Eigenschaften des entfernten Endes der Verbindung an, einschließlich des Medienformats.Die Methode nimmt einen einzigen Parameter—die Sitzungsbeschreibung—und gibt einPromise zurück, das erfüllt wird, sobald die Beschreibung asynchron geändert wurde.

Diese Methode wird in der Regel aufgerufen, nachdem ein Angebot oder eine Antwort von einem anderen Peer über den Signalisierungs-Server empfangen wurde.Beachten Sie, dass wennsetRemoteDescription() aufgerufen wird, während bereits eine Verbindung besteht, eine Neuverhandlung im Gange ist (möglicherweise um sich an ändernde Netzwerkbedingungen anzupassen).

Da Beschreibungen ausgetauscht werden, bis sich die beiden Peers auf eine Konfiguration einigen, wird die durch den Aufruf vonsetRemoteDescription() übermittelte Beschreibung nicht sofort wirksam.Stattdessen bleibt die aktuelle Verbindungskonfiguration bestehen, bis die Verhandlung abgeschlossen ist.Erst dann tritt die vereinbarte Konfiguration in Kraft.

Syntax

setRemoteDescription(sessionDescription)// deprecatedsetRemoteDescription(sessionDescription, successCallback, errorCallback)

Parameter

sessionDescription

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

type

Ein String, der den Typ der Sitzungsbeschreibung angibt. SieheRTCSessionDescription.type.

sdpOptional

Ein String, der das SDP beschreibt, das die Sitzung beschreibt. Falls sdp nicht bereitgestellt wird, ist der Standard ein leerer String. Wenntype"rollback" ist, musssdp null oder ein leerer String sein. SieheRTCSessionDescription.sdp.

Es kann auch eine tatsächliche Instanz vonRTCSessionDescription übergeben werden, aber es gibt keinen Unterschied. Aus diesem Grund ist derRTCSessionDescription-Konstruktor veraltet.

In älterem Code und Dokumentation kann eine rückrufbasierte Version dieser Funktion verwendet werden.Diese ist veraltet und die Verwendung wirdstark abgeraten.Sie sollten vorhandenen Code aktualisieren, um diePromise-basierte Version vonsetRemoteDescription() zu verwenden.Die Parameter für die ältere Form vonsetRemoteDescription() sind unten beschrieben, um beim Aktualisieren von vorhandenem Code zu helfen.

successCallbackVeraltet

Eine JavaScript-Function, die keine Eingabeparameter akzeptiert und aufgerufen wird, sobald die Beschreibung erfolgreich gesetzt wurde.Zu diesem Zeitpunkt kann das Angebot über den Signalisierungs-Server an einen entfernten Peer gesendet werden.

errorCallbackVeraltet

Eine Funktion, die der SignaturRTCPeerConnectionErrorCallback entspricht und aufgerufen wird, wenn die Beschreibung nicht gesetzt werden kann.Es wird ein einzelnesDOMException-Objekt übergeben, das erklärt, warum die Anfrage fehlgeschlagen ist.

Diese veraltete Form der Methode gibt instantan zurück, ohne auf das tatsächliche Setzen zu warten: im Erfolgsfall wird dersuccessCallback aufgerufen; im Fehlerfall wird dererrorCallback aufgerufen.

Rückgabewert

EinPromise, das erfüllt wird, sobald der Wert derremoteDescription der Verbindung erfolgreich geändert wurde, oder abgelehnt wird, wenn die Änderung nicht angewendet werden kann (zum Beispiel, wenn die angegebene Beschreibung mit einem oder beiden Peers der Verbindung inkompatibel ist).Der Fulfillment-Handler des Promise erhält keine Eingabeparameter.

Ausnahmen

Die folgenden Ausnahmen werden dem Rejection-Handler für das vonsetRemoteDescription() zurückgegebene Promise gemeldet:

InvalidAccessErrorDOMException

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

InvalidStateErrorDOMException

Wird zurückgegeben, wenn dieRTCPeerConnection geschlossen ist oder sich in einem Zustand befindet, der nicht mit dem angegebenentype der Beschreibung kompatibel ist.Zum Beispiel wird diese Ausnahme ausgelöst, wenn dertyperollback ist und der Signalisierungszustand einer vonstable,have-local-pranswer oderhave-remote-pranswer ist, da Sie eine Verbindung, die entweder vollständig hergestellt ist oder sich im Endstadium ihrer Verbindung befindet, nicht zurücksetzen können.

OperationErrorDOMException

Wird zurückgegeben, wenn ein Fehler nicht mit den hier angegebenen übereinstimmt. Dies schließt Identitätsvalidierungsfehler ein.

RTCErrorDOMException

Wird mit demerrorDetail aufsdp-syntax-error gesetzt, wenn das vonRTCSessionDescription.sdp angegebeneSDP nicht gültig ist.DiesdpLineNumber-Eigenschaft des Fehlerobjekts gibt die Zeilennummer innerhalb des SDP an, bei der der Syntaxfehler erkannt wurde.

TypeError

Wird zurückgegeben, wenn dersessionDescription dietype-Eigenschaft fehlt oder gar kein Beschreibungsparameter bereitgestellt wurde.

Bei der Verwendung der veralteten, rückrufbasierten Version vonsetRemoteDescription() können folgende Ausnahmen auftreten:

InvalidStateErrorVeraltet

DersignalingState der Verbindung ist"closed", was anzeigt, dass die Verbindung derzeit nicht geöffnet ist, sodass keine Verhandlung stattfinden kann.

InvalidSessionDescriptionErrorVeraltet

Der ParametersessionDescription ist ungültig.

Nutzungshinweise

Wenn SiesetRemoteDescription() aufrufen, prüft der ICE-Agent, ob sich dieRTCPeerConnection entweder imstable oderhave-remote-offersignalingState befindet.Diese Zustände zeigen an, dass entweder eine bestehende Verbindung neu verhandelt wird oder dass ein zuvor durch einen früheren Aufruf vonsetRemoteDescription() angegebenes Angebot durch das neue Angebot ersetzt werden soll.In beiden Fällen befinden wir uns am Beginn des Verhandlungsprozesses, und das Angebot wird als die entfernte Beschreibung gesetzt.

Andererseits, wenn wir uns mitten in einer laufenden Verhandlung befinden und ein Angebot ansetRemoteDescription() übergeben wird, beginnt der ICE-Agent automatisch mit einem ICE-Rollback, um die Verbindung in einen stabilen Signalisierungszustand zu versetzen, und setzt dann, sobald der Rollback abgeschlossen ist, die entfernte Beschreibung auf das angegebene Angebot.Dies beginnt eine neue Verhandlungssitzung, mit dem neu etablierten Angebot als Startpunkt.

Beim Start der neuen Verhandlung mit dem neu etablierten Angebot ist das lokale Gegenüber jetzt das angerufene Endgerät, selbst wenn es zuvor der Anrufer war.Dies geschieht anstelle eines Auslösens einer Ausnahme, wodurch die Anzahl der potenziellen Fehler verringert wird, die auftreten können, und vereinfacht die Verarbeitung, die durchgeführt werden muss, wenn Sie ein Angebot erhalten, indem die Notwendigkeit eliminiert wird, den Angebot-/Antwortprozess unterschiedlich zu behandeln, je nachdem, ob das lokale Gegenüber der Anrufer oder der Angerufene ist.

Beispiele

Hier sehen wir eine Funktion, die ein Angebot bearbeitet, das vom entfernten Peer empfangen wurde.Dieser Code ist abgeleitet von dem Beispiel und der Anleitung im ArtikelSignalisierung und Videotelefonie; einen Blick in diesen Artikel lohnt sich für genauere Details und eine ausführlichere Erklärung, was vor sich geht.

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 unsereRTCPeerConnection erstellt und sie alsmyPeerConnection gespeichert haben, übergeben wir die in der empfangenen Angebotsnachricht enthaltene Beschreibung,msg, direkt ansetRemoteDescription(), um der WebRTC-Schicht des Benutzeragents mitzuteilen, welche Konfiguration der Anrufer vorgeschlagen hat.Wenn unser Promise-Erfüllungshandler aufgerufen wird, der anzeigt, dass dies geschehen ist, erstellen wir einen Stream, fügen ihn der Verbindung hinzu, erstellen dann eine SDP-Antwort und rufensetLocalDescription() auf, um diese als Konfiguration am Ende unseres Anrufs zu setzen, bevor wir diese Antwort an den Anrufer weiterleiten.

Spezifikationen

Browser-Kompatibilität

Siehe auch

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