RTCPeerConnection: Methode createDataChannel()

Syntax

createDataChannel(label)
createDataChannel(label, options)

Parameter

label

Ein für Menschen lesbarer Name für den Kanal. Diese Zeichenfolge darf nicht länger als 65.535 Byte sein.

options Optional

Ein Objekt, das Konfigurationsoptionen für den Datenkanal bereitstellt. Es kann die folgenden Felder enthalten:

ordered Optional

Gibt an, ob Nachrichten, die über den RTCDataChannel gesendet werden, in derselben Reihenfolge an ihrem Ziel eintreffen müssen, in der sie gesendet wurden (true), oder ob sie in anderer Reihenfolge eintreffen dürfen (false). Standard: true.

maxPacketLifeTime Optional

Die maximale Anzahl von Millisekunden, die Übertragungsversuche für eine Nachricht im unzuverlässigen Modus dauern dürfen. Obwohl dieser Wert eine vorzeichenlose 16-Bit-Zahl ist, kann jeder User-Agent ihn auf einen als angemessen erachteten Höchstwert begrenzen. Standard: null.

maxRetransmits Optional

Die maximale Anzahl von Versuchen, die der User-Agent unternehmen soll, um eine Nachricht erneut zu übertragen, deren erste Übertragung im unzuverlässigen Modus fehlgeschlagen ist. Obwohl dieser Wert eine vorzeichenlose 16-Bit-Zahl ist, kann jeder User-Agent ihn auf einen als angemessen erachteten Höchstwert begrenzen. Standard: null.

protocol Optional

Der Name des Subprotokolls, das gegebenenfalls auf dem RTCDataChannel verwendet wird; andernfalls die leere Zeichenfolge (""). Standard: leere Zeichenfolge (""). Diese Zeichenfolge darf nicht länger als 65.535 Byte sein.

negotiated Optional

Standardmäßig (false) werden Datenkanäle In-Band ausgehandelt, wobei eine Seite createDataChannel aufruft und die andere Seite mithilfe des Event-Handlers ondatachannel auf das Ereignis RTCDataChannelEvent wartet. Alternativ (true) können sie Out-of-Band ausgehandelt werden, wobei beide Seiten createDataChannel mit einer vereinbarten ID aufrufen. Standard: false.

id Optional

Eine numerische 16-Bit-ID für den Kanal; zulässige Werte sind 0 bis 65534. Wenn Sie diese Option nicht angeben, wählt der User-Agent eine ID für Sie aus.

Rückgabewert

Ein neues RTCDataChannel-Objekt mit dem angegebenen label, das mithilfe der durch options angegebenen Optionen konfiguriert wird, falls dieser Parameter enthalten ist; andernfalls werden die oben aufgeführten Standardwerte festgelegt.

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn RTCPeerConnection geschlossen ist.

TypeError

Wird in den folgenden Situationen ausgelöst:

• Die Zeichenfolge für Label und/oder Protokoll ist zu lang; diese dürfen nicht länger als 65.535 Byte sein (Byte statt Zeichen).
• Die id ist 65535. Obwohl dies ein gültiger vorzeichenloser 16-Bit-Wert ist, ist er kein zulässiger Wert für id.

SyntaxError DOMException

Wird ausgelöst, wenn für sowohl die Optionen maxPacketLifeTime als auch maxRetransmits Werte angegeben wurden. Sie dürfen nur für eine dieser Optionen einen Wert ungleich null angeben.

ResourceInUse DOMException

Wird ausgelöst, wenn eine id angegeben wurde, aber ein anderer RTCDataChannel bereits denselben Wert verwendet.

OperationError DOMException

Wird ausgelöst, wenn entweder die angegebene id bereits verwendet wird oder, falls keine id angegeben wurde, die WebRTC-Schicht keine ID automatisch generieren konnte, weil alle IDs verwendet werden.

Beispiele

Dieses Beispiel zeigt, wie ein Datenkanal erstellt und Handler für die Ereignisse open und message eingerichtet werden, um darüber Nachrichten zu senden und zu empfangen (der Kürze halber wird im Beispiel 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 Out-of-Band-Aushandlung mit einer vereinbarten ID verwendet werden (hier 0):

// 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);
};

Ein ausführlicheres Beispiel, das zeigt, wie die Verbindung und der Kanal hergestellt werden, finden Sie unter Ein einfaches RTCDataChannel-Beispiel.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• RTCDataChannel
• Ein einfaches RTCDataChannel-Beispiel
• RTCPeerConnection