TsgcQUICServer › TsgcQUICServerStream

TsgcQUICServerStream Class

Wraps one additional QUIC stream on a connection, besides the default data stream.

Introduction

A QUIC connection multiplexes many independent streams. TsgcQUICServerConnection keeps its first peer-opened bidirectional stream as a single default data stream, the one WriteData writes to. Every other stream on the connection, whether opened by the peer or by the server, is tracked as a TsgcQUICServerStream in the connection's Streams list.

You obtain an instance in one of two ways:

1. Call OpenStream to create a server-initiated stream. It returns the wrapper.

2. Call aConnection.FindStreamById(aStreamId) with the stream id reported by OnQUICStreamData, to get the wrapper for a stream the peer opened.

Pass the wrapper to WriteStreamData to send bytes on that specific stream.

Lifetime. The wrapper is owned by the connection's Streams list and frees its OpenSSL stream handle when destroyed. Never free it yourself. The transport removes and frees a stream when the peer concludes it or it errors, so do not cache the reference across events, look it up by id with FindStreamById instead.

Additional streams are only tracked in multi-stream mode. A plain QUIC server ignores extra peer streams unless AlwaysMultiStream is True. TsgcHTTP3Server sets it for you, because HTTP/3 needs the peer's control and QPACK streams.

Declaration

TsgcQUICServerStream = class
public
  property SSL: PSSL read FSSL write FSSL;
  property StreamId: Int64 read FStreamId write FStreamId;
  property Unidirectional: Boolean read FUnidirectional write FUnidirectional;
  property Incoming: Boolean read FIncoming write FIncoming;
end;

Properties

Name	Type	Description
`StreamId`	`Int64`	The QUIC stream id assigned by the transport, as reported by OpenSSL. `-1` when the id could not be read. This is the value OnQUICStreamData reports and the key `FindStreamById` matches on.
`Unidirectional`	`Boolean`	`True` for a one-way stream, `False` for a bidirectional one. For accepted peer streams the transport derives this from bit `0x02` of the stream id, which QUIC reserves to mark unidirectional streams. For server-opened streams it is the `aUnidirectional` argument you passed to `OpenStream`.
`Incoming`	`Boolean`	`True` when the peer opened the stream, `False` when the server opened it via `OpenStream`. The transport reads a stream only when it is incoming or bidirectional, so a server-opened unidirectional stream is write-only and never raises `OnQUICStreamData`.
`SSL`	`PSSL`	The raw OpenSSL handle for this stream. Exposed for advanced interoperability. Do not free it, the wrapper owns it and frees it in its destructor.

Remarks

This class is a thin wrapper around an OpenSSL QUIC stream. It has no methods of its own, writing is done through WriteStreamData on the server and reading is delivered through OnQUICStreamData.

This class is currently available in the Delphi/C++Builder implementation only. The .NET implementation has no multi-stream server surface, so it has no TsgcQUICServerStream, no OpenStream and no WriteStreamData.

Example


// open a server-initiated bidirectional stream and write to it
procedure TfrmServer.OnQUICConnectEvent(Sender: TObject; const aConnection: TsgcQUICServerConnection);
var
  oStream: TsgcQUICServerStream;
begin
  oStream := oServer.OpenStream(aConnection, False);
  if Assigned(oStream) then
  begin
    Log('opened stream id ' + IntToStr(oStream.StreamId));
    oServer.WriteStreamData(oStream, TEncoding.UTF8.GetBytes('hello on my own stream'));
  end;
end;

// answer on the same stream the peer used
procedure TfrmServer.OnQUICStreamDataEvent(Sender: TObject; const aConnection: TsgcQUICServerConnection;
  aStreamId: Int64; aUnidirectional: Boolean; const aData: TBytes);
var
  oStream: TsgcQUICServerStream;
begin
  if aUnidirectional then
    Exit; // cannot write back on a peer unidirectional stream
  oStream := aConnection.FindStreamById(aStreamId);
  if Assigned(oStream) then
    oServer.WriteStreamData(oStream, aData);
end;

Requirements

Requirement	Detail
Edition	All-Access edition.
Compiler define	QUIC ships disabled. Uncomment `{$DEFINE SGC_PACK_HTTP3}` in the All-Access block of `sgcVer.inc`, it is delivered as `{.$DEFINE SGC_PACK_HTTP3}`. That in turn defines `SGC_QUIC`, but only when `SGC_INDY_LIB` is defined.
Unit	`sgcQUIC_Server`
OpenSSL	OpenSSL 3.5 or later, required.
Availability	Delphi/C++Builder only.

Back to TsgcQUICServer