RTCPeerConnection: Methode createOffer()

Syntax

createOffer()
createOffer(options)

createOffer(successCallback, failureCallback) // deprecated
createOffer(successCallback, failureCallback, options) // deprecated

Parameter

options Optional

Ein Objekt mit den folgenden Optionen für das Angebot:

iceRestart Optional

Setzen Sie diese Option auf true, um ICE für eine aktive Verbindung neu zu starten. Dadurch enthält das zurückgegebene Angebot andere Anmeldedaten als die bisher verwendeten. Wenn Sie das zurückgegebene Angebot anschließend anwenden, wird ICE neu gestartet. Geben Sie false an, um dieselben Anmeldedaten beizubehalten und ICE nicht neu zu starten. Der Standardwert ist false. Statt diese Option zu verwenden, sollten Sie RTCPeerConnection.restartIce() aufrufen. Dadurch wird dieses Flag beim nächsten Aufruf von createOffer() automatisch gesetzt.

offerToReceiveAudio Optional

Bietet zusätzliche Kontrolle über die Richtung der Audioübertragung. Damit lässt sich beispielsweise sicherstellen, dass Audio empfangen werden kann, unabhängig davon, ob Audio gesendet wird.

offerToReceiveVideo Optional

Bietet zusätzliche Kontrolle über die Richtung der Videoübertragung. Damit lässt sich beispielsweise sicherstellen, dass Video empfangen werden kann, unabhängig davon, ob Video gesendet wird.

Veraltete Parameter

In älterem Code und älterer Dokumentation finden Sie möglicherweise eine Callback-basierte Version dieser Funktion. Sie ist veraltet, und von ihrer Verwendung wird dringend abgeraten. Aktualisieren Sie bestehenden Code, sodass er stattdessen die Promise-basierte Version von createOffer() verwendet. Die Parameter der älteren Form von createOffer() sind nachfolgend beschrieben, um Ihnen die Aktualisierung bestehenden Codes zu erleichtern.

successCallback

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

errorCallback

Eine Callback-Funktion, an die ein einzelnes DOMException-Objekt übergeben wird, das erklärt, warum die Erstellung des Angebots fehlgeschlagen ist.

options Optional

Ein optionales Objekt mit Optionen für das Angebot.

Rückgabewert

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

type

Eine Zeichenfolge mit dem Wert "offer".

sdp

Eine Zeichenfolge mit der SDP, die das erzeugte Angebot beschreibt und an den entfernten Peer übermittelt werden soll.

Ausnahmen

Diese Ausnahmen werden zurückgegeben, indem das zurückgegebene Promise abgelehnt wird. Prüfen Sie im Handler für die Ablehnung die empfangene Ausnahme, um festzustellen, welche aufgetreten ist.

InvalidStateError DOMException

Wird zurückgegeben, wenn die RTCPeerConnection geschlossen ist.

NotReadableError DOMException

Wird zurückgegeben, wenn zur Absicherung der Verbindung kein Zertifikat beziehungsweise keine Zertifikate bereitgestellt wurden und createOffer() kein neues Zertifikat erstellen konnte. Da alle WebRTC-Verbindungen abgesichert sein müssen, führt dies zu einem Fehler.

OperationError DOMException

Wird zurückgegeben, wenn die Prüfung des Systemzustands zur Bestimmung der verfügbaren Ressourcen für die Erstellung des Angebots aus irgendeinem Grund fehlgeschlagen ist.

Beispiele

Hier sehen Sie einen Handler für das Ereignis negotiationneeded, der das Angebot erstellt und über einen Signalisierungskanal an das entfernte 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. Sobald dies erfolgreich abgeschlossen ist, wird die lokale Seite der RTCPeerConnection entsprechend konfiguriert, indem das Angebot – dargestellt durch ein Objekt mit derselben Struktur wie RTCSessionDescription – an setLocalDescription() übergeben wird. Anschließend wird das Angebot über den Signalisierungskanal an das entfernte System gesendet, in diesem Fall mithilfe einer benutzerdefinierten Funktion namens sendToServer(). Die Implementierung des Signalisierungsservers ist unabhängig von der WebRTC-Spezifikation. Es spielt daher keine Rolle, wie das Angebot gesendet wird, solange sowohl der Aufrufer als auch der potenzielle Empfänger denselben Signalisierungsmechanismus verwenden.

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

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

Spezifikationen

Browser-Kompatibilität