WebTransport: Methode createUnidirectionalStream()

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 createUnidirectionalStream()-Methode der WebTransport-Schnittstelle öffnet asynchron einen unidirektionalen Stream.

Die Methode gibt ein Promise zurück, das zu einem WritableStream-Objekt aufgelöst wird, welches verwendet werden kann, um zuverlässig Daten an den Server zu schreiben.

"Zuverlässig" bedeutet, dass Übertragung und Reihenfolge der Daten garantiert sind. Dies führt zu einer langsameren Übertragung (wenn auch schneller als mit WebSockets) als bei datagrams, ist aber erforderlich in Situationen, in denen Zuverlässigkeit und Reihenfolge wichtig sind, wie z.B. in Chat-Anwendungen.

Die relative Reihenfolge, in der die in Warteschlange stehenden Bytes von den erstellten Streams geleert werden, kann über die sendOrder-Option angegeben werden. Wenn sie gesetzt ist, werden in Streams mit einer höheren Sendepriorität die in Warteschlange stehenden Bytes garantiert vor denen von Streams mit niedrigerer Sendepriorität gesendet. Wenn die Ordnungsnummer nicht festgelegt ist, hängt die Reihenfolge, in der Bytes gesendet werden, von der Implementierung ab. Es ist jedoch zu beachten, dass selbst wenn Bytes von Streams mit höherer Sendepriorität zuerst gesendet werden, sie möglicherweise nicht zuerst ankommen.

Syntax

js
createUnidirectionalStream()
createUnidirectionalStream(options)

Parameter

options Optional

Ein Objekt, das die folgenden Eigenschaften haben kann:

sendOrder Optional

Ein ganzzahliger Wert, der die Sendepriorität dieses Streams im Vergleich zu anderen Streams für die der Wert gesetzt wurde, angibt. In Warteschlange stehende Bytes werden zuerst für Streams gesendet, die einen höheren Wert haben. Wenn nicht gesetzt, hängt die Sendereihenfolge von der Implementierung ab.

Rückgabewert

Ein Promise, das auf ein WebTransportSendStream-Objekt aufgelöst wird (dies ist ein WritableStream).

Ausnahmen

InvalidStateError DOMException

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

Beispiele

Verwenden Sie die createUnidirectionalStream()-Methode, um eine Referenz zu einem WritableStream zu erhalten. Daraus können Sie einen Schreiber erhalten, um das Schreiben von Daten in den Stream und das Senden an den Server zu ermöglichen.

Verwenden Sie die close()-Methode des resultierenden WritableStreamDefaultWriter, um die zugehörige HTTP/3-Verbindung zu schließen. Der Browser versucht, alle ausstehenden Daten zu senden, bevor die zugehörige Verbindung tatsächlich geschlossen wird.

js
async function writeData() {
  const stream = await transport.createUnidirectionalStream({
    sendOrder: "596996858",
  });
  const writer = stream.getWriter();
  const data1 = new Uint8Array([65, 66, 67]);
  const data2 = new Uint8Array([68, 69, 70]);
  writer.write(data1);
  writer.write(data2);

  try {
    await writer.close();
    console.log("All data has been sent.");
  } catch (error) {
    console.error(`An error occurred: ${error}`);
  }
}

Sie können auch WritableStreamDefaultWriter.abort() verwenden, um den Stream abrupt zu beenden. Bei Verwendung von abort() kann es sein, dass der Browser alle ausstehenden Daten verwirft, die noch nicht gesendet wurden.

js
// ...

const stream = await transport.createUnidirectionalStream();
const writer = stream.getWriter();

// ...

writer.write(...);
writer.write(...);
await writer.abort();
// Not all the data may have been written.

Spezifikationen

Specification
WebTransport
# dom-webtransport-createunidirectionalstream

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch