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.
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
oderclosed
. currentLocalDescription
Nur lesbar-
Gibt ein
RTCSessionDescription
-Objekt zurück, das das lokale Ende der Verbindung beschreibt, wie es zuletzt erfolgreich ausgehandelt wurde, seitdem dieseRTCPeerConnection
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 dieseRTCPeerConnection
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
oderclosed
. 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
odercomplete
. 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, wirdnull
zurückgegeben. peerIdentity
Nur lesbar-
Gibt ein
Promise
zurück, das zu einerRTCIdentityAssertion
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, wirdnull
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 Wertnull
. 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
oderclosed
.
Statische Methoden
RTCPeerConnection.generateCertificate()
-
Erstellt ein X.509-Zertifikat und den entsprechenden privaten Schlüssel und gibt ein
Promise
zurück, das mit dem neuenRTCCertificate
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 einemRTCRtpSender
und einemRTCRtpReceiver
, 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, wennsignalingState
nichtclosed
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 angegebenenMediaStreamTrack
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 vongetSenders()
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 bestimmtenMediaStreamTrack
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 stattdessenremoveTrack()
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 auftrack
-Ereignisse achten; eines wird für jedenMediaStreamTrack
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 aufremovetrack
-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
- https://github.com/jesup/nightly-gupshup/blob/master/static/js/chat.js
- Erste Schritte mit WebRTC
- TutorRoom: Node.js HTML Videoaufnahme, Peer-to-Peer-Video- und Dateifreigabeanwendung (Quelle auf GitHub)