Struct quiche::Connection

pub struct Connection { /* fields omitted */ }

A QUIC connection.

Methods

impl Connection

pub fn recv(&mut self, buf: &mut [u8]) -> Result<usize>

Processes QUIC packets received from the peer.

On success the number of bytes processed from the input buffer is returned, or Done. On error the connection will be closed by calling close() with the appropriate error code.

Coalesced packets will be processed as necessary.

Note that the contents of the input buffer buf might be modified by this function due to, for example, in-place decryption.

Examples:

loop {
    let read = socket.recv(&mut buf).unwrap();

    let read = match conn.recv(&mut buf[..read]) {
        Ok(v) => v,

        Err(quiche::Error::Done) => {
            // Done reading.
            break;
        },

        Err(e) => {
            // An error occurred, handle it.
            break;
        },
    };
}

pub fn send(&mut self, out: &mut [u8]) -> Result<usize>

Writes a single QUIC packet to be sent to the peer.

On success the number of bytes processed from the input buffer is returned, or Done.

Examples:

loop {
    let write = match conn.send(&mut out) {
        Ok(v) => v,

        Err(quiche::Error::Done) => {
            // Done writing.
            break;
        },

        Err(e) => {
            // An error occurred, handle it.
            break;
        },
    };

    socket.send(&out[..write]).unwrap();
}

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

Reads contiguous data from a stream into the provided slice.

The slice must be sized by the caller and will be populated up to its capacity.

On success the amount of bytes read and a flag indicating the fin state is returned as a tuple, or Done if there is no data to read.

Examples:

while let Ok((read, fin)) = conn.stream_recv(stream_id, &mut buf) {
    println!("Got {} bytes on stream {}", read, stream_id);
}

pub fn stream_send(
    &mut self,
    stream_id: u64,
    buf: &[u8],
    fin: bool
) -> Result<usize>

Writes data to a stream.

On success the number of bytes written is returned.

Examples:

conn.stream_send(stream_id, b"hello", true)?;

pub fn stream_shutdown(
    &mut self,
    stream_id: u64,
    direction: Shutdown,
    _err: u64
) -> Result<()>

Shuts down reading or writing from/to the specified stream.

When the direction argument is set to Shutdown::Read, outstanding data in the stream's receive buffer is dropped, and no additional data is added to it. Data received after calling this method is still validated and ACKed but not stored, and stream_recv() will not return it to the application.

When the direction argument is set to Shutdown::Write, outstanding data in the stream's send buffer is dropped, and no additional data is added to it. Data passed to stream_send() after calling this method will be ignored.

pub fn stream_finished(&self, stream_id: u64) -> bool

Returns true if all the data has been read from the specified stream.

This instructs the application that all the data received from the peer on the stream has been read, and there won't be anymore in the future.

Basically this returns true when the peer either set the fin flag for the stream, or sent RESET_STREAM.

Important traits for Readable<'a>

impl<'a> Iterator for Readable<'a> type Item = u64;

pub fn readable(&mut self) -> Readable

Creates an iterator over streams that have outstanding data to read.

Examples:

// Iterate over readable streams.
let streams: Vec<u64> = conn.readable().collect();

for stream_id in streams {
    // Stream is readable, read until there's no more data.
    while let Ok((read, fin)) = conn.stream_recv(stream_id, &mut buf) {
        println!("Got {} bytes on stream {}", read, stream_id);
    }
}

pub fn timeout(&self) -> Option<Duration>

Returns the amount of time until the next timeout event.

Once the given duration has elapsed, the on_timeout() method should be called. A timeout of None means that the timer should be disarmed.

pub fn on_timeout(&mut self)

Processes a timeout event.

If no timeout has occurred it does nothing.

pub fn close(&mut self, app: bool, err: u16, reason: &[u8]) -> Result<()>

Closes the connection with the given error and reason.

The app parameter specifies whether an application close should be sent to the peer. Otherwise a normal connection close is sent.

Returns Done if the connection had already been closed.

Note that the connection will not be closed immediately. An application should continue calling recv(), send() and timeout() as normal, until the is_closed() method returns true.

pub fn trace_id(&self) -> &str

Returns a string uniquely representing the connection.

This can be used for logging purposes to differentiate between multiple connections.

pub fn application_proto(&self) -> &[u8]

Returns the negotiated ALPN protocol.

If no protocol has been negotiated, the returned value is empty.

pub fn is_established(&self) -> bool

Returns true if the connection handshake is complete.

pub fn is_resumed(&self) -> bool

Returns true if the connection is resumed.

pub fn is_closed(&self) -> bool

Returns true if the connection is closed.

If this returns true, the connection object can be dropped.

pub fn stats(&self) -> Stats

Collects and returns statistics about the connection.