RTCPeerConnection: Methode createOffer()
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 createOffer()
-Methode der RTCPeerConnection
-Schnittstelle initiiert die Erstellung eines SDP-Angebots, um eine neue WebRTC-Verbindung zu einem entfernten Peer zu starten.
Das SDP-Angebot enthält Informationen über alle bereits an die WebRTC-Sitzung angehängten MediaStreamTrack
-Objekte, die von dem Browser unterstützten Codecs und Optionen sowie alle vom ICE-Agenten bereits gesammelten Kandidaten, um diese über den Signalisierungskanal an einen potenziellen Peer zu senden, um eine Verbindung anzufordern oder die Konfiguration einer bestehenden Verbindung zu aktualisieren.
Syntax
createOffer()
createOffer(options)
createOffer(successCallback, failureCallback) // deprecated
createOffer(successCallback, failureCallback, options) // deprecated
Parameter
options
Optional-
Ein Objekt, das die folgenden für das Angebot angeforderten Optionen bereitstellt:
iceRestart
Optional-
Um ICE bei einer aktiven Verbindung neu zu starten, setzen Sie diesen Wert auf
true
. Dies führt dazu, dass das zurückgegebene Angebot andere Anmeldeinformationen hat als die bereits vorhandenen. Wenn Sie dann das zurückgegebene Angebot anwenden, wird ICE neu gestartet. Geben Siefalse
an, um die gleichen Anmeldeinformationen beizubehalten und ICE daher nicht neu zu starten. Der Standardwert istfalse
. offerToReceiveAudio
Optional Veraltet-
Bietet zusätzliche Kontrolle über die Richtung des Audios. Beispielsweise kann es verwendet werden, um sicherzustellen, dass Audio empfangen werden kann, unabhängig davon, ob Audio gesendet wird oder nicht.
offerToReceiveVideo
Optional Veraltet-
Bietet zusätzliche Kontrolle über die Richtung des Videos. Beispielsweise kann es verwendet werden, um sicherzustellen, dass Video empfangen werden kann, unabhängig davon, ob Video gesendet wird oder nicht.
Veraltete Parameter
In älterem Code und Dokumentation kann eine rückrufbasierte Version dieser Funktion zu sehen sein.
Diese ist veraltet und die Verwendung wird dringend abgeraten.
Sie sollten jeden vorhandenen Code aktualisieren, um die auf Promise
basierte Version von createOffer()
zu verwenden.
Die Parameter für die ältere Form von createOffer()
sind unten beschrieben, um bei der Aktualisierung vorhandener Codes zu helfen.
successCallback
Veraltet-
Eine Rückruffunktion, die ein einzelnes
RTCSessionDescription
-Objekt erhält, das das neu erstellte Angebot beschreibt. errorCallback
Veraltet-
Eine Rückruffunktion, die ein einzelnes
DOMException
-Objekt erhält, das erklärt, warum die Anforderung zur Erstellung eines Angebots fehlgeschlagen ist. options
Optional-
Ein optionales Objekt, das die für das Angebot angeforderten Optionen bereitstellt.
Rückgabewert
Ein Promise
, der mit einem Objekt erfüllt wird, das die gleichen Eigenschaften wie ein RTCSessionDescription
-Objekt enthält:
Ausnahmen
Diese Ausnahmen werden zurückgegeben, indem das zurückgegebene Promise abgelehnt wird. Ihr Ablehnungshandler sollte die empfangene Ausnahme prüfen, um festzustellen, welche aufgetreten ist.
InvalidStateError
DOMException
-
Zurückgegeben, wenn die
RTCPeerConnection
geschlossen ist. NotReadableError
DOMException
-
Zurückgegeben, wenn kein Zertifikat oder eine Gruppe von Zertifikaten zur Sicherung der Verbindung bereitgestellt wurde und
createOffer()
nicht in der Lage war, ein neues zu erstellen. Da alle WebRTC-Verbindungen gesichert sein müssen, führt dies zu einem Fehler. OperationError
DOMException
-
Zurückgegeben, wenn die Prüfung des Systemstatus zur Bestimmung der Ressourcenvorhandenheit aus irgendeinem Grund fehlschlug.
Beispiele
Hier sehen wir einen Handler für das negotiationneeded
-Ereignis, das das Angebot erstellt und über einen Signalisierungskanal an das entfernte System sendet.
Hinweis: Beachten Sie, dass dies Teil des Signalisierungsprozesses ist, dessen Transportschicht ein Implementierungsdetail ist, das vollständig Ihnen überlassen ist.
In diesem Fall wird eine WebSocket-Verbindung verwendet, um eine JSON-Nachricht mit einem type
-Feld und dem Wert "video-offer" an den anderen Peer zu senden.
Der Inhalt des an die sendToServer()
-Funktion übergebenen Objekts sowie alles andere im Erfüllungshandler des Versprechens hängt völlig von Ihrem Design ab.
myPeerConnection
.createOffer()
.then((offer) => myPeerConnection.setLocalDescription(offer))
.then(() => {
sendToServer({
name: myUsername,
target: targetUsername,
type: "video-offer",
sdp: myPeerConnection.localDescription,
});
})
.catch((reason) => {
// An error occurred, so handle the failure to connect
});
In diesem Code wird das Angebot erstellt und bei Erfolg wird das lokale Ende der RTCPeerConnection
so konfiguriert, dass es übereinstimmt, indem das Angebot (welches durch ein Objekt in der gleichen Form wie RTCSessionDescription
dargestellt wird) in setLocalDescription()
übergeben wird.
Sobald das erledigt ist, wird das Angebot über den Signalisierungskanal an das entfernte System gesendet; in diesem Fall durch die Verwendung einer benutzerdefinierten Funktion namens sendToServer()
.
Die Implementierung des Signalisierungsservers ist unabhängig von der WebRTC-Spezifikation, sodass es keine Rolle spielt, wie das Angebot gesendet wird, solange Anrufer und potenzieller Empfänger das gleiche Verfahren verwenden.
Verwenden Sie Promise.catch()
, um Fehler abzufangen und zu behandeln.
Siehe Signaling und Videotelefonie für das vollständige Beispiel, aus dem dieses Snippet stammt; dies wird Ihnen helfen zu verstehen, wie der Signalisierungscode hier funktioniert.
Spezifikationen
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-createoffer |
Browser-Kompatibilität
BCD tables only load in the browser