Struct quiche::h3::Connection

pub struct Connection { /* fields omitted */ }

An HTTP/3 connection.

Implementations

impl Connection

pub fn with_transport(
    conn: &mut Connection,
    config: &Config
) -> Result<Connection>

Creates a new HTTP/3 connection using the provided QUIC connection.

This will also initiate the HTTP/3 handshake with the peer by opening all control streams (including QPACK) and sending the local settings.

pub fn send_request<T: NameValue>(
    &mut self,
    conn: &mut Connection,
    headers: &[T],
    fin: bool
) -> Result<u64>

Sends an HTTP/3 request.

The request is encoded from the provided list of headers without a body, and sent on a newly allocated stream. To include a body, set fin as false and subsequently call send_body() with the same conn and the stream_id returned from this method.

On success the newly allocated stream ID is returned.

The StreamBlocked error is returned when the underlying QUIC stream doesn’t have enough capacity for the operation to complete. When this happens the application should retry the operation once the stream is reported as writable again.

pub fn send_response<T: NameValue>(
    &mut self,
    conn: &mut Connection,
    stream_id: u64,
    headers: &[T],
    fin: bool
) -> Result<()>

Sends an HTTP/3 response on the specified stream with default priority.

This method sends the provided headers without a body. To include a body, set fin as false and subsequently call send_body() with the same conn and stream_id.

The StreamBlocked error is returned when the underlying QUIC stream doesn’t have enough capacity for the operation to complete. When this happens the application should retry the operation once the stream is reported as writable again.

pub fn send_response_with_priority<T: NameValue>(
    &mut self,
    conn: &mut Connection,
    stream_id: u64,
    headers: &[T],
    priority: &str,
    fin: bool
) -> Result<()>

Sends an HTTP/3 response on the specified stream with specified priority.

The StreamBlocked error is returned when the underlying QUIC stream doesn’t have enough capacity for the operation to complete. When this happens the application should retry the operation once the stream is reported as writable again.

pub fn send_body(
    &mut self,
    conn: &mut Connection,
    stream_id: u64,
    body: &[u8],
    fin: bool
) -> Result<usize>

Sends an HTTP/3 body chunk on the given stream.

On success the number of bytes written is returned, or Done if no bytes could be written (e.g. because the stream is blocked).

Note that the number of written bytes returned can be lower than the length of the input buffer when the underlying QUIC stream doesn’t have enough capacity for the operation to complete.

When a partial write happens (including when Done is returned) the application should retry the operation once the stream is reported as writable again.

pub fn dgram_enabled_by_peer(&self, conn: &Connection) -> bool

Returns whether the peer enabled HTTP/3 DATAGRAM frame support.

Support is signalled by the peer’s SETTINGS, so this method always returns false until they have been processed using the poll() method.

pub fn send_dgram(
    &mut self,
    conn: &mut Connection,
    flow_id: u64,
    buf: &[u8]
) -> Result<()>

Sends an HTTP/3 DATAGRAM with the specified flow ID.

pub fn recv_dgram(
    &mut self,
    conn: &mut Connection,
    buf: &mut [u8]
) -> Result<(usize, u64, usize)>

Reads a DATAGRAM into the provided buffer.

Applications should call this method whenever the poll() method returns a Datagram event.

On success the DATAGRAM data is returned, with length and Flow ID and length of the Flow ID.

Done is returned if there is no data to read.

BufferTooShort is returned if the provided buffer is too small for the data.

pub fn dgram_max_writable_len(
    &self,
    conn: &Connection,
    flow_id: u64
) -> Option<usize>

Returns the maximum HTTP/3 DATAGRAM payload that can be sent.

pub fn recv_body(
    &mut self,
    conn: &mut Connection,
    stream_id: u64,
    out: &mut [u8]
) -> Result<usize>

Reads request or response body data into the provided buffer.

Applications should call this method whenever the poll() method returns a Data event.

On success the amount of bytes read is returned, or Done if there is no data to read.

pub fn poll(&mut self, conn: &mut Connection) -> Result<(u64, Event)>

Processes HTTP/3 data received from the peer.

On success it returns an Event and an ID, or Done when there are no events to report.

Note that all events are edge-triggered, meaning that once reported they will not be reported again by calling this method again, until the event is re-armed.

The events Headers, Data and Finished return a stream ID, which is used in methods recv_body(), send_response() or send_body().

The event Datagram returns a dummy value of 0, this should be ignored by the application.

The event GoAway returns an ID that depends on the connection role. A client receives the largest processed stream ID. A server receives the the largest permitted push ID.

If an error occurs while processing data, the connection is closed with the appropriate error code, using the transport’s close() method.

pub fn send_goaway(&mut self, conn: &mut Connection, id: u64) -> Result<()>

Sends a GOAWAY frame to initiate graceful connection closure.

When quiche is used in the server role, the id parameter is the stream ID of the highest processed request. This can be any valid ID between 0 and 2^62-4. However, the ID cannot be increased. Failure to satisfy these conditions will return an error.

This method does not close the QUIC connection. Applications are required to call close() themselves.