RTCPeerConnection: setLocalDescription()-Methode
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
Die setLocalDescription()
-Methode der RTCPeerConnection
-Schnittstelle ändert die lokale Beschreibung, die mit der Verbindung verknüpft ist. Diese Beschreibung gibt die Eigenschaften des lokalen 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.
Wenn setLocalDescription()
aufgerufen wird, während bereits eine Verbindung besteht, bedeutet dies, dass eine Neuverhandlung stattfindet (möglicherweise um sich an sich ändernde Netzbedingungen anzupassen). Da Beschreibungen ausgetauscht werden, bis die beiden Partner sich auf eine Konfiguration einigen, wird die mit setLocalDescription()
eingereichte Beschreibung nicht sofort wirksam. Stattdessen bleibt die aktuelle Verbindungskonfiguration bestehen, bis die Verhandlung abgeschlossen ist. Erst dann tritt die vereinbarte Konfiguration in Kraft.
Syntax
setLocalDescription()
setLocalDescription(sessionDescription)
setLocalDescription(sessionDescription, successCallback, errorCallback) // deprecated
Parameter
sessionDescription
Optional-
Ein Objekt, das die Konfiguration angibt, die auf das lokale Ende der Verbindung angewendet werden soll. Es sollte die folgenden Eigenschaften enthalten:
type
Optional-
Ein String, der den Typ der Sitzungsbeschreibung angibt. Wenn Sie nicht explizit eine Sitzungsbeschreibung angeben, versucht die WebRTC-Laufzeitumgebung, dies korrekt zu behandeln. Wenn der Signalisierungszustand einer der folgenden ist:
stable
,have-local-offer
oderhave-remote-pranswer
, erstellt die WebRTC-Laufzeitumgebung automatisch ein neues Angebot und setzt dies als neue lokale Beschreibung. Andernfalls erstelltsetLocalDescription()
eine Antwort, die zur neuen lokalen Beschreibung wird. sdp
Optional-
Ein String, der die SDP enthält, die die Sitzung beschreibt. Wenn
sdp
nicht bereitgestellt wird, wird standardmäßig ein leerer String verwendet. Wenn dertype
"rollback"
ist, musssdp
null oder ein leerer String sein.
Wenn die Beschreibung weggelassen wird, versucht die WebRTC-Laufzeitumgebung automatisch, das Richtige zu tun.
Sie können auch eine tatsächliche Instanz von
RTCSessionDescription
übergeben, aber es gibt keinen Unterschied. Aus diesem Grund ist derRTCSessionDescription
-Konstruktor veraltet.
In älterem Code und Dokumentationen sehen Sie möglicherweise eine callback-basierte Version dieser Funktion, die nicht mehr unterstützt wird und deren Verwendung stark abgeraten wird, da sie in Zukunft entfernt werden soll. Sie sollten vorhandenen Code aktualisieren, um die auf Promise
basierende Version von setLocalDescription()
zu verwenden. Die Parameter für die ältere Form von setLocalDescription()
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 festgelegt wurde. Zu diesem Zeitpunkt kann das Angebot über den Signalisierungsserver an einen Remote-Partner gesendet werden. errorCallback
Veraltet-
Eine Funktion mit der Signatur
RTCPeerConnectionErrorCallback
, die aufgerufen wird, wenn die Beschreibung nicht festgelegt werden kann. Sie erhält ein einzelnesDOMException
-Objekt, das erklärt, warum die Anforderung fehlgeschlagen ist.
Diese veraltete Form der Methode gibt sofort zurück, ohne auf das tatsächliche Setzen zu warten: Im Erfolgsfall wird der successCallback
aufgerufen; im Falle eines Fehlers wird der errorCallback
aufgerufen.
Rückgabewert
Ein Promise
, das erfüllt wird, sobald der Wert von RTCPeerConnection.localDescription
erfolgreich geändert wurde oder abgelehnt wird, wenn die Änderung nicht angewendet werden kann (zum Beispiel, wenn die angegebene Beschreibung mit einem oder beiden der Partner in der Verbindung nicht kompatibel ist). Der Erfüllungs-Handler des Promises erhält keine Eingabeparameter.
Hinweis: Der Prozess, Beschreibungen zu ändern, umfasst tatsächlich Zwischenstufen, die von der WebRTC-Schicht verarbeitet werden, um sicherzustellen, dass eine aktive Verbindung geändert werden kann, ohne die Verbindung zu verlieren, wenn die Änderung nicht erfolgreich ist. Weitere Details zu diesem Prozess finden Sie unter Ausstehende und aktuelle Beschreibungen auf der WebRTC-Konnektivitätsseite.
Veraltete Ausnahmen
Bei Verwendung der veralteten, callback-basierten Version von setLocalDescription()
können die folgenden Ausnahmen auftreten:
InvalidStateError
DOMException
Veraltet-
Wird ausgelöst, wenn der
signalingState
der Verbindung"closed"
ist, was darauf hindeutet, dass die Verbindung derzeit nicht geöffnet ist, sodass keine Verhandlung stattfinden kann. InvalidSessionDescriptionError
DOMException
Veraltet-
Wird ausgelöst, wenn der
sessionDescription
-Parameter ungültig ist.
Beispiele
Implizite Beschreibungen
Einer der Vorteile der parameterfreien Form von setLocalDescription()
ist, dass Sie damit Ihren Verhandlungscode erheblich vereinfachen können. So sieht Ihr Event-Handler für das negotiationneeded
-Ereignis größtenteils aus. Fügen Sie einfach den Signalisierungsserver-Code hinzu, der hier durch den Aufruf von signalRemotePeer()
dargestellt wird.
pc.addEventListener("negotiationneeded", async (event) => {
await pc.setLocalDescription();
signalRemotePeer({ description: pc.localDescription });
});
Abgesehen vom Fehlerhandling war das schon fast alles!
Eigenes Angebot oder eigene Antwort bereitstellen
Das Beispiel unten zeigt die Implementierung eines Handlers für das negotiationneeded
-Ereignis, der explizit ein Angebot erstellt, anstatt setLocalDescription()
dies übernehmen zu lassen.
async function handleNegotiationNeededEvent() {
try {
const offer = await pc.createOffer();
pc.setLocalDescription(offer);
signalRemotePeer({ description: pc.localDescription });
} catch (err) {
window.reportError(err);
}
}
Dies beginnt mit der Erstellung eines Angebots durch den Aufruf von createOffer()
; wenn dies erfolgreich ist, rufen wir setLocalDescription()
auf. Wir können dann das neu erstellte Angebot durch den Signalisierungsserver zum anderen Partner senden, was hier durch den Aufruf einer Funktion namens signalRemotePeer()
erfolgt.
Spezifikationen
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-peerconnection-setlocaldescription |
Browser-Kompatibilität
BCD tables only load in the browser