RTCPeerConnection: createDataChannel()-Methode
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 createDataChannel()
-Methode der RTCPeerConnection
-Schnittstelle erstellt einen neuen Kanal, der mit dem entfernten Peer verbunden ist, über den Daten jeglicher Art übertragen werden können. Dies kann nützlich sein für Nebenkanalinhalte, wie Bilder, Dateitransfer, Text-Chat, Spielaktualisierungspakete und so weiter.
Wenn der neue Datenkanal der erste ist, der zur Verbindung hinzugefügt wird, wird eine Neuverhandlung gestartet, indem ein negotiationneeded
-Ereignis ausgelöst wird.
Syntax
createDataChannel(label)
createDataChannel(label, options)
Parameter
label
-
Ein menschenlesbarer Name für den Kanal. Diese Zeichenfolge darf nicht länger als 65.535 Bytes sein.
options
Optional-
Ein Objekt, das Konfigurationsoptionen für den Datenkanal bereitstellt. Es kann die folgenden Felder enthalten:
ordered
Optional-
Gibt an, ob Nachrichten auf dem
RTCDataChannel
in der gleichen Reihenfolge ankommen müssen, in der sie gesendet wurden (true
), oder ob sie außer der Reihenfolge ankommen dürfen (false
). Standard:true
. maxPacketLifeTime
Optional-
Die maximale Anzahl von Millisekunden, die Versuche zur Übertragung einer Nachricht im unzuverlässigen Modus dauern dürfen. Obwohl dieser Wert eine 16-Bit-Zahl ohne Vorzeichen ist, kann jeder Benutzeragent ihn auf das Maximum begrenzen, das er für angemessen hält. Standard:
null
. maxRetransmits
Optional-
Die maximale Anzahl von Versuchen, die der Benutzeragent unternehmen sollte, um eine Nachricht, die im unzuverlässigen Modus beim ersten Versuch fehlschlägt, erneut zu senden. Obwohl dieser Wert eine 16-Bit-Zahl ohne Vorzeichen ist, kann jeder Benutzeragent ihn auf das Maximum begrenzen, das er für angemessen hält. Standard:
null
. protocol
Optional-
Der Name des auf dem
RTCDataChannel
verwendeten Subprotokolls, falls vorhanden; andernfalls der leere String (""
). Standard: leerer String (""
). Diese Zeichenfolge darf nicht länger als 65.535 Bytes sein. negotiated
Optional-
Standardmäßig (
false
) werden Datenkanäle im Inband-Modus verhandelt, wobei eine SeitecreateDataChannel
aufruft und die andere Seite dasRTCDataChannelEvent
-Ereignis mit demondatachannel
-Ereignishandler abhört. Alternativ können sie (true
) außerhalb des Bands gehandelt werden, wobei beide SeitencreateDataChannel
mit einer vereinbarten ID aufrufen. Standard:false
. id
Optional-
Eine 16-Bit-numerische ID für den Kanal; erlaubte Werte sind 0 bis 65534. Wenn Sie diese Option nicht angeben, wählt der Benutzeragent eine ID für Sie aus.
Hinweis: Diese Optionen repräsentieren die durch Skript einstellbare Teilmenge der Eigenschaften auf der RTCDataChannel
-Schnittstelle.
Rückgabewert
Ein neues RTCDataChannel
-Objekt mit dem angegebenen label
, konfiguriert unter Verwendung der durch options
angegebenen Optionen, falls dieser Parameter enthalten ist; andernfalls werden die oben aufgelisteten Standardwerte festgelegt.
Ausnahmen
InvalidStateError
DOMException
-
Wird ausgelöst, wenn die
RTCPeerConnection
geschlossen ist. TypeError
-
Wird in den folgenden Situationen ausgelöst:
- Die
label
- und/oderprotocol
-Zeichenfolge ist zu lang; diese dürfen nicht länger als 65.535 Bytes (Bytes, nicht Zeichen) sein. - Die
id
ist 65535. Obwohl dies ein gültiger Wert ohne Vorzeichen für 16-Bit ist, ist er fürid
nicht erlaubt.
- Die
SyntaxError
DOMException
-
Wird ausgelöst, wenn sowohl für
maxPacketLifeTime
als auch fürmaxRetransmits
Werte angegeben wurden. Sie dürfen nur für eine dieser Optionen einen nicht-null
-Wert angeben. ResourceInUse
DOMException
-
Wird ausgelöst, wenn eine
id
angegeben wurde, die jedoch bereits von einem anderenRTCDataChannel
verwendet wird. OperationError
DOMException
-
Wird ausgelöst, wenn entweder die angegebene
id
bereits verwendet wird oder wenn keineid
angegeben wurde und die WebRTC-Schicht keine ID automatisch generieren konnte, da alle IDs verwendet werden.
Beispiele
Dieses Beispiel zeigt, wie Sie einen Datenkanal erstellen und Handler für die open
- und message
-Ereignisse einrichten, um Nachrichten darauf zu senden und zu empfangen (der Einfachheit halber wird angenommen, dass onnegotiationneeded
eingerichtet ist).
// Offerer side
const pc = new RTCPeerConnection(options);
const channel = pc.createDataChannel("chat");
channel.onopen = (event) => {
channel.send("Hi you!");
};
channel.onmessage = (event) => {
console.log(event.data);
};
// Answerer side
const pc = new RTCPeerConnection(options);
pc.ondatachannel = (event) => {
const channel = event.channel;
channel.onopen = (event) => {
channel.send("Hi back!");
};
channel.onmessage = (event) => {
console.log(event.data);
};
};
Alternativ kann eine symmetrischere Verhandlung außerhalb des Bandes verwendet werden, wobei eine vereinbarte ID (hier 0) verwendet wird:
// Both sides
const pc = new RTCPeerConnection(options);
const channel = pc.createDataChannel("chat", { negotiated: true, id: 0 });
channel.onopen = (event) => {
channel.send("Hi!");
};
channel.onmessage = (event) => {
console.log(event.data);
};
Für ein gründlicheres Beispiel, das zeigt, wie die Verbindung und der Kanal hergestellt werden, siehe Ein einfaches RTCDataChannel-Beispiel.
Spezifikationen
Specification |
---|
WebRTC: Real-Time Communication in Browsers # dom-peerconnection-createdatachannel |
Browser-Kompatibilität
BCD tables only load in the browser