WebTransport: createBidirectionalStream()-Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die createBidirectionalStream()-Methode der WebTransport-Schnittstelle öffnet asynchron und gibt einen bidirektionalen Stream zurück.

Die Methode gibt ein Promise zurück, das zu einem WebTransportBidirectionalStream-Objekt führt, welches readable- und writable-Eigenschaften hat, die verwendet werden können, um zuverlässig vom Server zu lesen und zu schreiben. "Zuverlässig" bedeutet, dass Übertragung und Reihenfolge der Daten garantiert werden. Dies bietet eine langsamere Lieferung (wenn auch schneller als mit WebSockets) als datagrams, ist jedoch in Situationen notwendig, in denen Zuverlässigkeit und Reihenfolge wichtig sind, wie bei Chat-Anwendungen.

Die relative Reihenfolge, in der die in erstellten Streams eingereihten Bytes geleert werden, kann mit der sendOrder-Option festgelegt werden. Ist sie gesetzt, werden eingereihte Bytes in Streams mit einer höheren Sendereihenfolge garantiert vor den in Streams mit einer niedrigeren Sendereihenfolge gesendeten Bytes gesendet. Falls die Ordnungsnummer nicht festgelegt ist, hängt die Reihenfolge, in der Bytes gesendet werden, von der Implementierung ab. Beachten Sie jedoch, dass selbst wenn Bytes aus Streams mit höherer Sendereihenfolge zuerst gesendet werden, sie möglicherweise nicht zuerst ankommen.

Syntax

js
createBidirectionalStream()
createBidirectionalStream(options)

Parameter

options Optional

Ein Objekt, das die folgenden Eigenschaften haben kann:

sendOrder Optional

Ein ganzzahliger Wert, der die Sendepriorität dieses Streams relativ zu anderen Streams angibt, für die der Wert festgelegt wurde. Eingereihte Bytes werden zuerst für Streams mit einem höheren Wert gesendet. Wenn nicht festgelegt, hängt die Sendereihenfolge von der Implementierung ab.

Rückgabewert

Ein Promise, das zu einem WebTransportBidirectionalStream-Objekt führt.

Ausnahmen

InvalidStateError DOMException

Wird ausgelöst, wenn createBidirectionalStream() aufgerufen wird, während das WebTransport geschlossen oder fehlgeschlagen ist.

Beispiele

Eine anfängliche Funktion wird verwendet, um Referenzen zu den WebTransportBidirectionalStream.readable- und WebTransportBidirectionalStream.writable-Eigenschaften zu erhalten. Diese sind Referenzen zu Instanzen von WebTransportReceiveStream und WebTransportSendStream, die lesbare und beschreibbare Streams sind, die zum Lesen von und Schreiben an den Server verwendet werden können.

js
async function setUpBidirectional() {
  const stream = await transport.createBidirectionalStream({
    sendOrder: "596996858",
  });
  // stream is a WebTransportBidirectionalStream
  // stream.readable is a ReadableStream
  const readable = stream.readable;
  // stream.writable is a WritableStream
  const writable = stream.writable;

  // ...
}

Das Lesen vom WebTransportReceiveStream kann dann wie folgt erfolgen:

js
async function readData(readable) {
  const reader = readable.getReader();
  while (true) {
    const { value, done } = await reader.read();
    if (done) {
      break;
    }
    // value is a Uint8Array.
    console.log(value);
  }
}

Und das Schreiben am WebTransportSendStream kann so erfolgen:

js
async function writeData(writable) {
  const writer = writable.getWriter();
  const data1 = new Uint8Array([65, 66, 67]);
  const data2 = new Uint8Array([68, 69, 70]);
  writer.write(data1);
  writer.write(data2);
}

Spezifikationen

Specification
WebTransport
# dom-webtransport-createbidirectionalstream

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch