RTCPeerConnection: Methode setRemoteDescription()
Die setRemoteDescription()
-Methode der Schnittstelle RTCPeerConnection
setzt die angegebene Sitzungsbeschreibung als aktuelles Angebot oder Antwort des entfernten Peers.
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 ein Promise
zurück, das erfüllt wird, sobald die Beschreibung asynchron geändert wurde.
Dies wird normalerweise aufgerufen, nachdem man ein Angebot oder eine Antwort von einem anderen Peer über den Signalisierungsserver erhalten hat.
Beachten Sie, dass, wenn setRemoteDescription()
aufgerufen wird, während bereits eine Verbindung besteht, dies bedeutet, dass eine Neuverhandlung im Gange ist (möglicherweise um sich an sich ändernde Netzwerkbedingungen anzupassen).
Da Beschreibungen ausgetauscht werden, bis sich die beiden Peers auf eine Konfiguration einigen, tritt die durch den Aufruf von setRemoteDescription()
übermittelte Beschreibung nicht sofort in Kraft.
Stattdessen bleibt die aktuelle Verbindungskonfiguration bestehen, bis die Verhandlung abgeschlossen ist.
Erst dann tritt die vereinbarte Konfiguration in Kraft.
Syntax
setRemoteDescription(sessionDescription)
// deprecated
setRemoteDescription(sessionDescription, successCallback, errorCallback)
Parameter
sessionDescription
-
Ein Objekt, das das aktuelle Angebot oder die Antwort des entfernten Peers spezifiziert. Es sollte die folgenden Eigenschaften enthalten:
type
-
Ein String, der den Typ der Sitzungsbeschreibung angibt. Siehe
RTCSessionDescription.type
. sdp
Optional-
Ein String, der das SDP beschreibt, welches die Sitzung beschreibt. Wenn sdp nicht angegeben wird, wird ein leerer String als Standard verwendet. Wenn
type
"rollback"
ist, musssdp
null oder ein leerer String sein. SieheRTCSessionDescription.sdp
.
Es ist auch möglich, eine tatsächliche Instanz von
RTCSessionDescription
zu übergeben, aber es gibt keinen Unterschied. Aus diesem Grund ist der Konstruktor vonRTCSessionDescription
veraltet.
In älterem Code und Dokumentationen können Sie eine auf Rückrufen basierende Version dieser Funktion sehen.
Diese ist veraltet und ihre Verwendung wird dringend abgeraten.
Sie sollten bestehenden Code aktualisieren, um die auf dem Promise
basierende Version von setRemoteDescription()
zu verwenden.
Die Parameter der älteren Form von setRemoteDescription()
sind unten beschrieben, um bei der Aktualisierung vorhandenen Codes zu helfen.
successCallback
Veraltet-
Eine JavaScript-
Function
, die keine Eingabeparameter akzeptiert und aufgerufen wird, sobald die Beschreibung erfolgreich gesetzt wurde. Zu diesem Zeitpunkt kann das Angebot über den Signalisierungsserver an einen entfernten Peer gesendet werden. errorCallback
Veraltet-
Eine Funktion mit der Signatur
RTCPeerConnectionErrorCallback
, die 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 sofort zurück, ohne auf die tatsächliche Einstellung zu warten: Im Erfolgsfall wird der successCallback
aufgerufen; im Fehlerfall der errorCallback
.
Rückgabewert
Ein Promise
, das erfüllt wird, sobald der Wert der remoteDescription
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 nicht kompatibel ist).
Der Fulfillment-Handler des Promises erhält keine Eingabeparameter.
Hinweis: Der Prozess des Änderns von Beschreibungen umfasst tatsächlich Zwischenschritte, die von der WebRTC-Schicht behandelt werden, um sicherzustellen, dass eine aktive Verbindung geändert werden kann, ohne die Verbindung zu verlieren, wenn die Änderung nicht erfolgreich ist. Siehe Ausstehende und aktuelle Beschreibungen auf der WebRTC-Konnektivitätsseite für weitere Details zu diesem Prozess.
Ausnahmen
Die folgenden Ausnahmen werden dem Ablehnungshandler für das von setRemoteDescription()
zurückgegebene Promise gemeldet:
InvalidAccessError
DOMException
-
Wird zurückgegeben, wenn der Inhalt der Beschreibung ungültig ist.
InvalidStateError
DOMException
-
Wird zurückgegeben, wenn die
RTCPeerConnection
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 dertype
rollback
ist und sich der Signalzustand im Zustandstable
,have-local-pranswer
oderhave-remote-pranswer
befindet, da eine Verbindung, die entweder vollständig hergestellt oder sich im letzten Schritt der Verbindung befindet, nicht zurückgerollt werden kann. OperationError
DOMException
-
Wird zurückgegeben, wenn ein Fehler auftritt, der nicht zu den hier angegebenen gehört. Dies schließt Fehler bei der Identitätsvalidierung ein.
RTCError
DOMException
-
Wird zurückgegeben, wenn das
errorDetail
aufsdp-syntax-error
gesetzt ist, wenn das vonRTCSessionDescription.sdp
spezifizierte SDP ungültig ist. DiesdpLineNumber
-Eigenschaft des Fehlerobjekts gibt die Zeilennummer innerhalb des SDP an, an der der Syntaxfehler entdeckt wurde. TypeError
-
Wird zurückgegeben, wenn die
sessionDescription
die Eigenschafttype
fehlt oder überhaupt kein Beschreibungsparameter angegeben wurde.
Bei Verwendung der veralteten rückrufbasierten Version von setRemoteDescription()
können folgende Ausnahmen auftreten:
InvalidStateError
Veraltet-
Der
signalingState
der Verbindung ist"closed"
, was darauf hindeutet, dass die Verbindung derzeit nicht geöffnet ist, sodass keine Verhandlung stattfinden kann. InvalidSessionDescriptionError
Veraltet-
Der
sessionDescription
-Parameter ist ungültig.
Verwendungshinweise
Wenn Sie setRemoteDescription()
aufrufen, überprüft der ICE-Agent, ob sich die RTCPeerConnection
entweder im stable
oder have-remote-offer
signalingState
befindet.
Diese Zustände zeigen an, dass entweder eine bestehende Verbindung neu verhandelt wird oder ein Angebot, das durch einen früheren Aufruf von setRemoteDescription()
angegeben wurde, durch das neue Angebot ersetzt werden soll.
In beiden Fällen befinden wir uns zu Beginn des Verhandlungsprozesses, und das Angebot wird als Remote-Beschreibung gesetzt.
Wenn wir uns hingegen mitten in einer laufenden Verhandlung befinden und ein Angebot in setRemoteDescription()
übergeben wird, beginnt der ICE-Agent automatisch mit einem ICE-Rollback, um die Verbindung in einen stabilen Signalzustand zurückzubringen und setzt anschließend nach Abschluss des Rollbacks die Remote-Beschreibung auf das angegebene Angebot.
Dies beginnt eine neue Verhandlungssitzung, wobei das neu aufgestellte Angebot der Ausgangspunkt ist.
Beim Start der neuen Verhandlung mit dem neu aufgestellten Angebot ist der lokale Peer jetzt der Angerufene, auch wenn er zuvor der Anrufer war. Dies geschieht anstatt eine Ausnahme auszulösen und reduziert dadurch die Anzahl potenzieller Fehler, die auftreten können, und vereinfacht die Verarbeitung, die Sie durchführen müssen, wenn Sie ein Angebot erhalten, indem die Notwendigkeit eliminiert wird, den Angebot/Antwort-Prozess abhängig davon unterschiedlich zu behandeln, ob der lokale Peer der Anrufer oder der Angerufene ist.
Hinweis: Frühere Implementierungen von WebRTC hätten eine Ausnahme ausgelöst, wenn außerhalb eines stable
- oder have-remote-offer
-Zustands ein Angebot gesetzt wurde.
Beispiele
Hier sehen wir eine Funktion, die ein vom entfernten Peer erhaltenes Angebot verarbeitet. Dieser Code ist abgeleitet von dem Beispiel und Tutorial im Artikel Signalisierung und Videotelefonie; sehen Sie sich das an, um weitere Details und eine eingehendere Erklärung zu erhalten, 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 unsere RTCPeerConnection
erstellt und sie als myPeerConnection
gespeichert haben, übergeben wir die in der empfangenen Angebotsnachricht, msg
, enthaltene Beschreibung direkt an setRemoteDescription()
, um die WebRTC-Schicht des Benutzeragenten darüber zu informieren, welche Konfiguration der Anrufer vorschlägt zu verwenden.
Wenn unser Promise-Erfüllungshandler aufgerufen wird und anzeigt, dass dies geschehen ist, erstellen wir einen Stream, fügen ihn zur Verbindung hinzu, erstellen dann eine SDP-Antwort und rufen setLocalDescription()
auf, um diese als Konfiguration an unserem Ende des Anrufs zu setzen, bevor wir diese Antwort an den Anrufer weiterleiten.
Spezifikationen
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-peerconnection-setremotedescription |
Browser-Kompatibilität
BCD tables only load in the browser