RTCPeerConnection: Methode createOffer()

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 dies auf true. Dadurch enthält das zurückgegebene Angebot andere Anmeldedaten als die bereits vorhandenen. Wenn Sie anschließend das zurückgegebene Angebot anwenden, wird ICE neu gestartet. Geben Sie false an, um dieselben Anmeldedaten beizubehalten und ICE daher nicht neu zu starten. Der Standardwert ist false. Erwägen Sie statt der Verwendung dieser Option den Aufruf von RTCPeerConnection.restartIce(), wodurch dieses Flag beim nächsten Aufruf von createOffer() automatisch gesetzt wird.

offerToReceiveAudio Optional

Bietet zusätzliche Kontrolle über die Richtung von Audio. Beispielsweise kann es verwendet werden, um sicherzustellen, dass Audio empfangen werden kann, unabhängig davon, ob Audio gesendet wird oder nicht.

offerToReceiveVideo Optional

Bietet zusätzliche Kontrolle über die Richtung von Video. 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 in älterer Dokumentation sehen Sie möglicherweise eine callback-basierte Version dieser Funktion. Diese ist veraltet, und von ihrer Verwendung wird dringend abgeraten. Sie sollten vorhandenen Code aktualisieren, um stattdessen die auf Promise basierende Version von createOffer() zu verwenden. Die Parameter der älteren Form von createOffer() werden unten beschrieben, um die Aktualisierung vorhandenen Codes zu erleichtern.

successCallback

Eine Callback-Funktion, der ein einzelnes RTCSessionDescription-Objekt übergeben wird, das das neu erstellte Angebot beschreibt.

errorCallback

Eine Callback-Funktion, der ein einzelnes DOMException-Objekt übergeben wird, das erklärt, warum die Anforderung zum Erstellen eines Angebots fehlgeschlagen ist.

options Optional

Ein optionales Objekt, das die für das Angebot angeforderten Optionen bereitstellt.

Rückgabewert

Ein Promise, das mit einem Objekt erfüllt wird, das dieselben Eigenschaften wie ein RTCSessionDescription-Objekt enthält:

type

Ein String, dessen Wert "offer" ist.

sdp

Ein String, der das SDP mit der Beschreibung des generierten Angebots enthält und an den Remote-Peer übermittelt werden soll.

Ausnahmen

Diese Ausnahmen werden durch die Ablehnung des zurückgegebenen Promise zurückgegeben. Ihr Handler für Ablehnungen sollte die empfangene Ausnahme untersuchen, um festzustellen, welche aufgetreten ist.

InvalidStateError DOMException

Wird zurückgegeben, wenn RTCPeerConnection geschlossen ist.

NotReadableError DOMException

Wird zurückgegeben, wenn kein Zertifikat oder Satz von Zertifikaten zur Absicherung der Verbindung bereitgestellt wurde und createOffer() kein neues erstellen konnte. Da alle WebRTC-Verbindungen abgesichert sein müssen, führt dies zu einem Fehler.

OperationError DOMException

Wird zurückgegeben, wenn die Untersuchung des Systemzustands zur Bestimmung der Ressourcenverfügbarkeit für die Generierung des Angebots aus irgendeinem Grund fehlgeschlagen ist.

Beispiele

Hier sehen wir einen Handler für das Ereignis negotiationneeded, der das Angebot erstellt und es über einen Signalisierungskanal an das Remote-System sendet.

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 nach erfolgreicher Erstellung wird das lokale Ende der RTCPeerConnection durch Übergabe des Angebots an setLocalDescription() entsprechend konfiguriert. Das Angebot wird dabei durch ein Objekt in derselben Form wie RTCSessionDescription dargestellt. Danach wird das Angebot über den Signalisierungskanal an das Remote-System gesendet; in diesem Fall mithilfe einer benutzerdefinierten Funktion namens sendToServer(). Die Implementierung des Signalisierungsservers ist unabhängig von der WebRTC-Spezifikation. Daher spielt es keine Rolle, wie das Angebot gesendet wird, solange sowohl der Aufrufer als auch der potenzielle Empfänger dieselbe Methode verwenden.

Verwenden Sie Promise.catch(), um Fehler abzufangen und zu behandeln.

Das vollständige Beispiel, aus dem dieses Snippet stammt, finden Sie unter Signalisierung und Videoanrufe. Es hilft Ihnen zu verstehen, wie der Signalisierungscode hier funktioniert.

Spezifikationen

Browser-Kompatibilität