WebTransport: Methode createUnidirectionalStream()
Eingeschränkt verfügbar
Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.
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 Methode createUnidirectionalStream() der Schnittstelle WebTransport öffnet asynchron einen unidirektionalen Stream.
Die Methode gibt ein Promise zurück, das mit einem WritableStream-Objekt erfüllt wird. Mit diesem Objekt können Daten zuverlässig an den Server geschrieben werden.
„Zuverlässig“ bedeutet, dass die Übertragung und die Reihenfolge der Daten garantiert sind. Dadurch ist die Übertragung langsamer als mit datagrams (wenn auch schneller als mit WebSockets). Diese Zuverlässigkeit ist jedoch in Situationen erforderlich, in denen die vollständige Übertragung und die richtige Reihenfolge wichtig sind, beispielsweise bei Chat-Anwendungen.
Die relative Reihenfolge, in der Daten aus erstellten Streams gesendet werden, kann mit der Option sendOrder festgelegt werden. Ist sie gesetzt, werden ausstehende Daten aus Streams mit einem höheren sendOrder-Wert garantiert vor ausstehenden Daten aus Streams mit einem niedrigeren Wert gesendet. Ist kein Wert festgelegt, hängt die Sendereihenfolge von der Implementierung ab. Beachten Sie jedoch, dass Daten aus Streams mit einem höheren sendOrder-Wert nicht unbedingt zuerst ankommen, auch wenn sie zuerst gesendet werden.
Syntax
createUnidirectionalStream()
createUnidirectionalStream(options)
Parameter
optionsOptional-
Ein Objekt, das die folgenden Eigenschaften haben kann:
sendOrderOptional-
Eine Ganzzahl, die die Sendepriorität dieses Streams relativ zu anderen Streams angibt, für die ein Wert festgelegt wurde. Ausstehende Daten aus Streams mit einem höheren Wert werden zuerst gesendet. Ist kein Wert festgelegt, hängt die Sendereihenfolge von der Implementierung ab.
Rückgabewert
Ein Promise, das mit einem WebTransportSendStream-Objekt erfüllt wird (einem WritableStream).
Ausnahmen
InvalidStateErrorDOMException-
Wird ausgelöst, wenn
createUnidirectionalStream()aufgerufen wird, während die WebTransport-Verbindung geschlossen oder fehlgeschlagen ist.
Beispiele
Verwenden Sie die Methode createUnidirectionalStream(), um eine Referenz auf einen WritableStream zu erhalten. Darüber können Sie einen Writer abrufen, um Daten in den Stream zu schreiben und an den Server zu senden.
Verwenden Sie die Methode close() des resultierenden WritableStreamDefaultWriter, um den Stream zu schließen. Der Browser versucht, vor dem Schließen des Streams alle ausstehenden Daten zu senden.
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 der Browser ausstehende Daten verwerfen, die noch nicht gesendet wurden.
// …
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
| Spezifikation |
|---|
| WebTransport # dom-webtransport-createunidirectionalstream |