Transport interface. More...

#include <transport.h>

Classes
struct	EnqueueFlags

Public Member Functions
virtual	~Transport ()=default
	Destroy the transport after derived-class shutdown has completed. More...

virtual TransportStatus	Status () const =0
	Status of the transport. More...

virtual std::shared_ptr< Connection >	Start ()=0
	Setup the transport connection. More...

virtual std::shared_ptr< Connection >	Connect (const TransportRemote &remote)=0

virtual void	Close (const std::shared_ptr< Connection > &connection, AppReasonForClose app_reason=AppReasonForClose::kRemoteRequestClose)=0
	Close a transport context. More...

virtual void	CloseStream (const std::shared_ptr< Stream > &stream, StreamOperation operation)=0
	Close a stream. More...

virtual bool	Enqueue (const std::shared_ptr< Connection > &connection, const std::shared_ptr< Stream > &stream, std::shared_ptr< const std::vector< uint8_t >> bytes, uint8_t priority=1, uint32_t ttl_ms=350, EnqueueFlags flags={ true, false, false, false })=0
	Enqueue application data on a stream. More...

virtual void	EnqueueDatagram (const std::shared_ptr< Connection > &connection, std::shared_ptr< const std::vector< uint8_t >> bytes, uint8_t priority=1, uint32_t ttl_ms=350)=0
	Enqueue application data as a datagram. More...

virtual std::shared_ptr< const std::vector< uint8_t > >	Dequeue (const std::shared_ptr< Connection > &connection)=0
	Dequeue datagram application data from transport buffer. More...

virtual int	CloseWebTransportSession (const std::shared_ptr< Connection > &connection, uint32_t error_code, const char *error_msg=nullptr)=0
	Close a WebTransport session with error code and message. More...

virtual int	DrainWebTransportSession (const std::shared_ptr< Connection > &connection)=0
	Drain a WebTransport session gracefully. More...

virtual std::shared_ptr< Stream >	CreateDataStream (const std::shared_ptr< Connection > &connection, uint8_t priority)=0
	Create a unidirectional stream to publish objects on. More...

virtual std::shared_ptr< Stream >	CreateControlStream (const std::shared_ptr< Connection > &connection)=0
	Create the connection's unidirectional outbound control stream. More...

virtual std::shared_ptr< Stream >	CreateRequestStream (const std::shared_ptr< Connection > &connection)=0
	Create a bidirectional request stream. More...

virtual void	Shutdown ()
	Stop network threads and release transport resources. More...

Static Public Member Functions
static std::shared_ptr< Transport >	MakeClientTransport (const TransportRemote &server, const TransportConfig &tcfg, std::shared_ptr< Clock > clock, std::shared_ptr< Logger > logger)
	Create a new client transport based on the remote (server) host/ip. More...

static std::shared_ptr< Transport >	MakeServerTransport (const TransportRemote &server, const TransportConfig &tcfg, std::shared_ptr< Clock > clock, std::shared_ptr< Logger > logger)
	Create a new server transport based on the remote (server) ip and port. More...

Public Attributes
std::function< void(const std::shared_ptr< Connection > &)>	OnNewConnection
	Callback invoked when the transport creates or accepts a connection. More...

std::function< void(const std::shared_ptr< Connection > &)>	OnConnectionClosed
	Callback invoked when a connection closes. More...

Detailed Description

Transport interface.

Implementations own asynchronous network and notification queues. Public operations marshal work to the transport as needed; callbacks are delivered serially on the transport notification thread. Callback implementations must return promptly to avoid delaying unrelated connection and stream events.

Constructor & Destructor Documentation

◆ ~Transport()

virtual quicr::Transport::~Transport ( )

virtualdefault

Destroy the transport after derived-class shutdown has completed.

Member Function Documentation

◆ Close()

virtual void quicr::Transport::Close	(	const std::shared_ptr< Connection > &	connection,
		AppReasonForClose	app_reason = `AppReasonForClose::kRemoteRequestClose`
	)

pure virtual

Close a transport context.

Parameters

connection	Connection to close.
app_reason	Application reason to close the connection

Precondition: connection must refer to a connection created by this transport.

◆ CloseStream()

virtual void quicr::Transport::CloseStream	(	const std::shared_ptr< Stream > &	stream,
		StreamOperation	operation
	)

pure virtual

Close a stream.

Parameters

stream	Stream to close; no-op if null or already closed
operation	Directional stream-close operation.

Exceptions

std::invalid_argument if operation is invalid for the stream direction.

◆ CloseWebTransportSession()

virtual int quicr::Transport::CloseWebTransportSession	(	const std::shared_ptr< Connection > &	connection,
		uint32_t	error_code,
		const char *	error_msg = `nullptr`
	)

pure virtual

Close a WebTransport session with error code and message.

Sends a CLOSE_WEBTRANSPORT_SESSION capsule to gracefully close the WebTransport session. This is only valid for connections using WebTransport over HTTP/3. For raw QUIC connections, this method has no effect.

The close session message allows the application to provide:

An error code to indicate the reason for closure
An optional error message string for debugging

After sending the close session message, the WebTransport session will be terminated and all associated streams will be cleaned up. This is typically used when the application wants to explicitly close the session due to an error condition or when normal session termination is required.

Parameters

connection	WebTransport connection to close.
error_code	WebTransport error code (application-defined)
error_msg	Optional error message string (can be nullptr)

Returns: 0 on success, -1 on failure (e.g., not a WebTransport connection)

◆ Connect()

virtual std::shared_ptr<Connection> quicr::Transport::Connect ( const TransportRemote & remote )

pure virtual

◆ CreateControlStream()

virtual std::shared_ptr<Stream> quicr::Transport::CreateControlStream ( const std::shared_ptr< Connection > & connection )

pure virtual

Create the connection's unidirectional outbound control stream.

Carries no flow: control messages are not a track, and the stream's metrics are reported against the stream itself.

Parameters

connection Connection that owns the stream.

Returns: Handle to the created stream, which the caller holds for the life of the connection.

◆ CreateDataStream()

virtual std::shared_ptr<Stream> quicr::Transport::CreateDataStream	(	const std::shared_ptr< Connection > &	connection,
		uint8_t	priority
	)

pure virtual

Create a unidirectional stream to publish objects on.

Parameters

connection	The connection for the stream.
priority	Priority of the stream

Returns: Handle to the created stream. Hold it for as long as the stream is being written to, rather than looking it up per object.

◆ CreateRequestStream()

virtual std::shared_ptr<Stream> quicr::Transport::CreateRequestStream ( const std::shared_ptr< Connection > & connection )

pure virtual

Create a bidirectional request stream.

One request is carried per stream, in both directions, so it has nothing to share state with and carries no flow.

Parameters

connection Connection that owns the stream.

Returns: Handle to the created stream, which the caller holds for the life of the request.

◆ Dequeue()

virtual std::shared_ptr<const std::vector<uint8_t> > quicr::Transport::Dequeue ( const std::shared_ptr< Connection > & connection )

pure virtual

Dequeue datagram application data from transport buffer.

Removes the next received datagram from the connection's receive queue.

Parameters

connection Identifying the connection

Returns: Shared immutable datagram bytes, or null if no datagram is queued.

◆ DrainWebTransportSession()

virtual int quicr::Transport::DrainWebTransportSession ( const std::shared_ptr< Connection > & connection )

pure virtual

Drain a WebTransport session gracefully.

Sends a DRAIN_WEBTRANSPORT_SESSION capsule to indicate that the peer should finish sending any pending data and then close the session. This is a more graceful shutdown compared to CloseWebTransportSession, allowing both peers to complete ongoing operations before closure.

The drain message signals to the peer that:

No new operations should be started
Existing operations should be completed
The session will be closed after all pending data is sent

This is typically used during normal application shutdown when you want to ensure all data is properly flushed before closing the connection.

Only valid for WebTransport connections. For raw QUIC connections, this method has no effect.

Parameters

connection WebTransport connection to drain.

Returns: 0 on success, -1 on failure (e.g., not a WebTransport connection)

◆ Enqueue()

virtual bool quicr::Transport::Enqueue	(	const std::shared_ptr< Connection > &	connection,
		const std::shared_ptr< Stream > &	stream,
		std::shared_ptr< const std::vector< uint8_t >>	bytes,
		uint8_t	priority = `1`,
		uint32_t	ttl_ms = `350`,
		EnqueueFlags	flags = `{ true, false, false, false }`
	)

pure virtual

Enqueue application data on a stream.

Add data to the stream's transmit queue, to be sent when the stream is next able to.

Parameters

connection	Connection to send from
stream	Stream to send on
bytes	Data to send/write
priority	Priority of the object, range should be 0 - 255
ttl_ms	The age the object should exist in queue in milliseconds
flags	Flags for stream and queue handling on enqueue of object

Exceptions

std::invalid_argument If a null connection, stream, or receive only stream is passed.

Returns: False if the stream's TX direction has closed, so the data could not be enqueued.

◆ EnqueueDatagram()

virtual void quicr::Transport::EnqueueDatagram	(	const std::shared_ptr< Connection > &	connection,
		std::shared_ptr< const std::vector< uint8_t >>	bytes,
		uint8_t	priority = `1`,
		uint32_t	ttl_ms = `350`
	)

pure virtual

Enqueue application data as a datagram.

The datagram queue belongs to the connection, so datagrams from every track share it and are ordered against each other by priority alone.

Parameters

connection	Connection to send from
bytes	Data to send/write
priority	Priority of the object, range should be 0 - 255
ttl_ms	The age the object should exist in queue in milliseconds

Exceptions

std::invalid_argument If connection ptr is null.

◆ MakeClientTransport()

static std::shared_ptr<Transport> quicr::Transport::MakeClientTransport	(	const TransportRemote &	server,
		const TransportConfig &	tcfg,
		std::shared_ptr< Clock >	clock,
		std::shared_ptr< Logger >	logger
	)

static

Create a new client transport based on the remote (server) host/ip.

Parameters

server	Transport remote server information
tcfg	Transport configuration
clock	Shared pointer to the tick service to use
logger	Shared pointer to logger

Returns: Shared ownership of the created transport.

Exceptions

std::runtime_error	if `server` selects an unsupported protocol.
std::runtime_error	if the QUIC/TLS configuration cannot be initialized.

◆ MakeServerTransport()

static std::shared_ptr<Transport> quicr::Transport::MakeServerTransport	(	const TransportRemote &	server,
		const TransportConfig &	tcfg,
		std::shared_ptr< Clock >	clock,
		std::shared_ptr< Logger >	logger
	)

static

Create a new server transport based on the remote (server) ip and port.

Server mode automatically supports BOTH raw QUIC (ALPN: moq-00) and WebTransport (ALPN: h3) simultaneously. The transport mode for each connection is determined dynamically based on the ALPN negotiated with each client during the TLS handshake.

Parameters

server	Transport remote server information (server.proto is ignored)
tcfg	Transport configuration
clock	Shared pointer to tick service
logger	Shared pointer to logger

Returns: Shared ownership of the created transport.

Exceptions

std::runtime_error if the QUIC/TLS configuration cannot be initialized.

◆ Shutdown()

virtual void quicr::Transport::Shutdown ( )

inlinevirtual

Stop network threads and release transport resources.

Note: Implementations should permit repeated calls. No callbacks should be expected after shutdown completes.

◆ Start()

virtual std::shared_ptr<Connection> quicr::Transport::Start ( )

pure virtual

Setup the transport connection.

In server mode this will create the listening socket and will start listening on the socket for new connections. In client mode this will initiate a connection to the remote/server.

Returns: Client connection, or the server listener's connection object as defined by the implementation.

◆ Status()

virtual TransportStatus quicr::Transport::Status ( ) const

pure virtual

Status of the transport.

Return the status of the transport. In server mode, the transport will reflect the status of the listening socket. In client mode it will reflect the status of the server connection.

Returns: Current transport lifecycle state.

Member Data Documentation

◆ OnConnectionClosed

std::function<void(const std::shared_ptr<Connection>&)> quicr::Transport::OnConnectionClosed

Callback invoked when a connection closes.

Runs on the transport notification thread after transport closure processing.

◆ OnNewConnection

std::function<void(const std::shared_ptr<Connection>&)> quicr::Transport::OnNewConnection

Callback invoked when the transport creates or accepts a connection.

Runs on the transport notification thread. The callback receives shared ownership of the connection for the duration of the call.

The documentation for this class was generated from the following file:

include/quicr/transport.h

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Transport()

Member Function Documentation

◆ Close()

◆ CloseStream()

◆ CloseWebTransportSession()

◆ Connect()

◆ CreateControlStream()

◆ CreateDataStream()

◆ CreateRequestStream()

◆ Dequeue()

◆ DrainWebTransportSession()

◆ Enqueue()

◆ EnqueueDatagram()

◆ MakeClientTransport()

◆ MakeServerTransport()

◆ Shutdown()

◆ Start()

◆ Status()

Member Data Documentation

◆ OnConnectionClosed

◆ OnNewConnection