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 in ein 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 sorgt für eine langsamere Übertragung (wenn auch schneller als mit WebSockets) als Datagrams, ist jedoch in Situationen erforderlich, in denen Zuverlässigkeit und Reihenfolge wichtig sind, wie z.B. bei Chat-Anwendungen.
Die relative Reihenfolge, in der die in die Warteschlange gestellten Bytes aus den erstellten Streams geleert werden, kann mit der sendOrder-Option spezifiziert werden. Wenn gesetzt, werden die in der Warteschlange befindlichen Bytes in Streams mit einer höheren Sendepriorität garantiert vor den in der Warteschlange befindlichen Bytes für Streams mit einer niedrigeren Sendepriorität gesendet. Wenn die Ordnungsnummer nicht gesetzt 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 Sendeordnung zuerst gesendet werden, sie möglicherweise nicht zuerst ankommen.
Syntax
createUnidirectionalStream()
createUnidirectionalStream(options)
Parameter
optionsOptional-
Ein Objekt, das die folgenden Eigenschaften haben kann:
sendOrderOptional-
Ein Ganzzahlwert, der die Sendepriorität dieses Streams relativ zu anderen Streams angibt, für die der Wert gesetzt wurde. In Warteschlangen befindliche Bytes werden zuerst für Streams gesendet, die einen höheren Wert haben. Wenn nicht gesetzt, hängt die Sendeordnung von der Implementierung ab.
Rückgabewert
Ein Promise, das sich in ein WebTransportSendStream-Objekt auflöst (dies ist ein WritableStream).
Ausnahmen
InvalidStateErrorDOMException-
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. Von hier aus können Sie einen Writer erhalten, um das Schreiben von Daten in den Stream zu ermöglichen und diese an den Server zu senden.
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.
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 der Verwendung von abort() kann der Browser alle ausstehenden Daten, die noch nicht gesendet wurden, verwerfen.
// …
const stream = await transport.createUnidirectionalStream();
const writer = stream.getWriter();
// …
writer.write(data1);
writer.write(data2);
await writer.abort();
// Not all the data may have been written.
Spezifikationen
| Specification |
|---|
| WebTransport # dom-webtransport-createunidirectionalstream |