RTCPeerConnection

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.

Das RTCPeerConnection-Interface repräsentiert eine WebRTC-Verbindung zwischen dem lokalen Computer und einem entfernten Peer. Es bietet Methoden, um sich mit einem entfernten Peer zu verbinden, die Verbindung zu pflegen und zu überwachen sowie die Verbindung zu schließen, wenn sie nicht mehr benötigt wird.

EventTarget RTCPeerConnection

Konstruktor

RTCPeerConnection()

Gibt eine neue RTCPeerConnection zurück, die eine Verbindung zwischen dem lokalen Gerät und einem entfernten Peer darstellt.

Instanzeigenschaften

Erbt auch Eigenschaften von EventTarget.

canTrickleIceCandidates Nur lesbar

Gibt einen booleschen Wert zurück, der anzeigt, ob der entfernte Peer trickle ICE-Kandidaten akzeptieren kann.

connectionState Nur lesbar

Zeigt den aktuellen Zustand der Peer-Verbindung an, indem einer der folgenden Zeichenfolgen zurückgegeben wird: new, connecting, connected, disconnected, failed oder closed.

currentLocalDescription Nur lesbar

Gibt ein RTCSessionDescription-Objekt zurück, das das lokale Ende der Verbindung beschreibt, wie es zuletzt erfolgreich ausgehandelt wurde, seitdem diese RTCPeerConnection die Verhandlung und Verbindung mit einem entfernten Peer abgeschlossen hat. Ebenfalls enthalten ist eine Liste aller ICE-Kandidaten, die vom ICE-Agenten seit dem ersten Start des Angebots oder der Antwort, die durch die Beschreibung dargestellt wird, möglicherweise bereits generiert wurden.

currentRemoteDescription Nur lesbar

Gibt ein RTCSessionDescription-Objekt zurück, das das entfernte Ende der Verbindung beschreibt, wie es zuletzt erfolgreich ausgehandelt wurde, seitdem diese RTCPeerConnection die Verhandlung und Verbindung mit einem entfernten Peer abgeschlossen hat. Ebenfalls enthalten ist eine Liste aller ICE-Kandidaten, die vom ICE-Agenten seit dem ersten Start des Angebots oder der Antwort, die durch die Beschreibung dargestellt wird, möglicherweise bereits generiert wurden.

iceConnectionState Nur lesbar

Gibt einen Zeichenfolgenwert zurück, der den Zustand des ICE-Agenten angibt, der mit dieser RTCPeerConnection verbunden ist. Es kann einer der folgenden Werte sein: new, checking, connected, completed, failed, disconnected oder closed.

iceGatheringState Nur lesbar

Gibt eine Zeichenfolge zurück, die den ICE-Sammlung-Zustand der Verbindung beschreibt. Damit können Sie beispielsweise erkennen, wann die Sammlung von ICE-Kandidaten abgeschlossen ist. Mögliche Werte sind: new, gathering oder complete.

localDescription Nur lesbar

Gibt ein RTCSessionDescription-Objekt zurück, das die Sitzung für das lokale Ende der Verbindung beschreibt. Wenn es noch nicht gesetzt wurde, wird null zurückgegeben.

peerIdentity Nur lesbar

Gibt ein Promise zurück, das zu einer RTCIdentityAssertion aufgelöst wird, die eine Zeichenfolge enthält, die den entfernten Peer identifiziert. Sobald dieses Versprechen erfolgreich aufgelöst wurde, ist die resultierende Identität die Ziel-Peer-Identität und ändert sich während der gesamten Verbindung nicht.

pendingLocalDescription Nur lesbar

Gibt ein RTCSessionDescription-Objekt zurück, das eine anstehende Konfigurationsänderung für das lokale Ende der Verbindung beschreibt. Dies beschreibt nicht die Verbindung, wie sie derzeit besteht, sondern wie sie in naher Zukunft aussehen könnte.

pendingRemoteDescription Nur lesbar

Gibt ein RTCSessionDescription-Objekt zurück, das eine anstehende Konfigurationsänderung für das entfernte Ende der Verbindung beschreibt. Dies beschreibt nicht die Verbindung, wie sie derzeit besteht, sondern wie sie in naher Zukunft aussehen könnte.

remoteDescription Nur lesbar

Gibt ein RTCSessionDescription-Objekt zurück, das die Sitzung, einschließlich Konfigurations- und Medieninformationen, für das entfernte Ende der Verbindung beschreibt. Wenn dies noch nicht gesetzt wurde, wird null zurückgegeben.

sctp Nur lesbar

Gibt ein RTCSctpTransport-Objekt zurück, das die SCTP-Transportschicht beschreibt, über die SCTP-Daten gesendet und empfangen werden. Wenn SCTP nicht ausgehandelt wurde, ist dieser Wert null.

signalingState Nur lesbar

Gibt eine Zeichenfolge zurück, die den Zustand des Signalisierungsprozesses am lokalen Ende der Verbindung beim Verbinden oder Wiederverbinden mit einem anderen Peer beschreibt. Es ist einer der folgenden Werte: stable, have-local-offer, have-remote-offer, have-local-pranswer, have-remote-pranswer oder closed.

Statische Methoden

RTCPeerConnection.generateCertificate()

Erstellt ein X.509-Zertifikat und den entsprechenden privaten Schlüssel und gibt ein Promise zurück, das mit dem neuen RTCCertificate aufgelöst wird, sobald es generiert wurde.

Instanzmethoden

Erbt auch Methoden von EventTarget.

addIceCandidate()

Fügt einen neuen entfernten Kandidaten zur RTCPeerConnection-Remote-Beschreibung hinzu, die den Zustand des entfernten Endes der Verbindung beschreibt.

addTrack()

Fügt einen neuen MediaStreamTrack zum Satz der Tracks hinzu, die an den anderen Peer übertragen werden.

addTransceiver()

Erstellt einen neuen RTCRtpTransceiver und fügt ihn dem Satz von Transceivern hinzu, die mit der Verbindung verbunden sind. Jeder Transceiver repräsentiert einen bidirektionalen Datenstrom, mit einem RTCRtpSender und einem RTCRtpReceiver, die damit verbunden sind.

close()

Schließt die aktuelle Peer-Verbindung.

createAnswer()

Leitet die Erstellung einer SDP-Antwort auf ein Angebot ein, das von einem entfernten Peer während der Angebot/Antwort-Verhandlung einer WebRTC-Verbindung empfangen wurde. Die Antwort enthält Informationen über bereits an die Sitzung angehängte Medien, vom Browser unterstützte Codecs und Optionen sowie bereits gesammelte ICE-Kandidaten.

createDataChannel()

Leitet die Erstellung eines neuen Kanals ein, der mit dem entfernten Peer verknüpft ist, über den jede Art von Daten übertragen werden kann. Dies kann nützlich sein für Back-Channel-Inhalte wie Bilder, Dateitransfer, Text-Chat, Spiel-Update-Pakete usw.

createOffer()

Leitet die Erstellung eines SDP-Angebots für den Zweck ein, eine neue WebRTC-Verbindung zu einem entfernten Peer zu starten. Das SDP-Angebot enthält Informationen über bereits an die WebRTC-Sitzung angehängte MediaStreamTrack-Objekte, vom Browser unterstützte Codecs und Optionen sowie bereits gesammelte ICE-Kandidaten, die über den Signalisierungskanal an einen potenziellen Peer gesendet werden sollen, um eine Verbindung anzufordern oder die Konfiguration einer bestehenden Verbindung zu aktualisieren.

getConfiguration()

Gibt ein Objekt zurück, das die aktuelle Konfiguration der Verbindung angibt.

getIdentityAssertion()

Leitet das Sammeln einer Identitätszusicherung ein und gibt ein Promise zurück, das in eine als Zeichenfolge codierte Identitätszusicherung aufgelöst wird. Dies hat nur dann eine Wirkung, wenn signalingState nicht closed ist.

getReceivers()

Gibt ein Array von RTCRtpReceiver-Objekten zurück, von denen jedes einen RTP-Empfänger darstellt.

getSenders()

Gibt ein Array von RTCRtpSender-Objekten zurück, von denen jedes den RTP-Sender repräsentiert, der für die Übertragung der Daten eines Tracks verantwortlich ist.

getStats()

Gibt ein Promise zurück, das mit Daten aufgelöst wird, die Statistiken entweder über die gesamte Verbindung oder über den angegebenen MediaStreamTrack bereitstellen.

getTransceivers()

Gibt eine Liste aller RTCRtpTransceiver-Objekte zurück, die zum Senden und Empfangen von Daten auf der Verbindung verwendet werden.

removeTrack()

Teilt dem lokalen Ende der Verbindung mit, das Senden von Medien von dem angegebenen Track zu stoppen, ohne den entsprechenden RTCRtpSender tatsächlich aus der Liste der Sender zu entfernen, wie sie von getSenders() berichtet wird. Wenn der Track bereits gestoppt ist oder sich nicht in der Sendeliste der Verbindung befindet, hat diese Methode keine Wirkung.

restartIce()

Ermöglicht es, das Sammeln von ICE-Kandidaten an beiden Enden der Verbindung leicht neu zu starten. Dies vereinfacht den Prozess, indem dieselbe Methode sowohl vom Anrufer als auch vom Empfänger verwendet werden kann, um einen ICE-Neustart auszulösen.

setConfiguration()

Setzt die aktuelle Konfiguration der Verbindung basierend auf den in dem angegebenen Objekt enthaltenen Werten. Damit können Sie die von der Verbindung verwendeten ICE-Server ändern und welche Transport-Richtlinien verwendet werden sollen.

setIdentityProvider()

Setzt den Identitätsanbieter (IdP) auf das im Parameter angegebene Tripel: seinen Namen, das Protokoll für die Kommunikation mit ihm und einen Benutzernamen. Das Protokoll und der Benutzername sind optional.

setLocalDescription()

Ändert die mit der Verbindung verbundene lokale Beschreibung. Diese Beschreibung spezifiziert die Eigenschaften des lokalen Endes der Verbindung, einschließlich des Medienformats. Es gibt ein Promise zurück, das erfüllt wird, sobald die Beschreibung asynchron geändert wurde.

setRemoteDescription()

Setzt die angegebene Sitzungsbeschreibung als aktuelles Angebot oder Antwort des entfernten Peers. Die Beschreibung spezifiziert die Eigenschaften des entfernten Endes der Verbindung, einschließlich des Medienformats. Es gibt ein Promise zurück, das erfüllt wird, sobald die Beschreibung asynchron geändert wurde.

Veraltete Methoden

addStream() Veraltet Nicht standardisiert

Fügt einen MediaStream als lokale Quelle für Audio oder Video hinzu. Anstelle dieser veralteten Methode sollten Sie für jeden Track, den Sie an den entfernten Peer senden möchten, addTrack() verwenden.

createDTMFSender() Veraltet Nicht standardisiert

Erstellt einen neuen RTCDTMFSender, der mit einem bestimmten MediaStreamTrack verbunden ist, und der in der Lage ist, DTMF-Telefonie-Signalisierung über die Verbindung zu senden.

removeStream() Veraltet Nicht standardisiert

Entfernt einen MediaStream als lokale Quelle für Audio oder Video. Da diese Methode veraltet ist, sollten Sie stattdessen removeTrack() verwenden.

Ereignisse

Hören Sie auf diese Ereignisse mit addEventListener() oder indem Sie einen Ereignis-Listener auf die oneventname-Eigenschaft dieses Interfaces zuweisen.

connectionstatechange

Gesendet, wenn sich der allgemeine Konnektivitätsstatus der RTCPeerConnection ändert.

datachannel

Gesendet, wenn der entfernte Peer einen RTCDataChannel zur Verbindung hinzufügt.

icecandidate

Gesendet, um anzufordern, dass der angegebene Kandidat an den entfernten Peer übertragen wird.

icecandidateerror

An die Verbindung gesendet, wenn während des Sammelns von ICE-Kandidaten ein Fehler auftritt. Das Ereignis beschreibt den Fehler.

iceconnectionstatechange

Gesendet, wenn sich der Zustand der ICE-Verbindung ändert, z. B. wenn sie unterbrochen wird.

icegatheringstatechange

Gesendet, wenn sich der Sammlungszustand der ICE-Schicht, der durch iceGatheringState reflektiert wird, ändert. Dies zeigt an, ob die ICE-Verhandlung noch nicht begonnen hat (new), ob mit dem Sammeln von Kandidaten begonnen wurde (gathering) oder ob sie abgeschlossen ist (complete).

negotiationneeded

Gesendet, wenn die Verhandlung oder Neuverhandlung der ICE-Verbindung durchgeführt werden muss; dies kann sowohl beim erstmaligen Öffnen einer Verbindung als auch bei notwendiger Anpassung an sich ändernde Netzwerkbedingungen geschehen. Der Empfänger sollte darauf reagieren, indem er ein Angebot erstellt und es an den anderen Peer sendet.

signalingstatechange

Gesendet, wenn sich der Signalisierungszustand der ICE-Verbindung ändert.

track

Gesendet, nachdem ein neuer Track zu einer der RTCRtpReceiver-Instanzen hinzugefügt wurde, die die Verbindung umfassen.

Veraltete Ereignisse

addstream Veraltet Nicht standardisiert

Gesendet, wenn ein neuer MediaStream zur Verbindung hinzugefügt wurde. Anstatt auf dieses veraltete Ereignis zu achten, sollten Sie auf track-Ereignisse achten; eines wird für jeden MediaStreamTrack gesendet, der zur Verbindung hinzugefügt wird.

removestream Veraltet Nicht standardisiert

Gesendet, wenn ein MediaStream von der Verbindung entfernt wird. Anstatt auf dieses veraltete Ereignis zu achten, sollten Sie auf removetrack-Ereignisse auf jedem Stream achten.

Spezifikationen

Specification
WebRTC: Real-Time Communication in Browsers
# interface-definition

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch