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 written to the output buffer is returned, or Done if there was nothing to write.

The application should call send() multiple times until Done is returned, indicating that there are no more packets to send. It is recommended that send() be called in the following cases:

• When the application receives QUIC packets from the peer (that is, any time recv() is also called).

• When the connection timer expires (that is, any time on_timeout() is also called).

• When the application sends data to the peer (for examples, any time stream_send() or stream_shutdown() are called).

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, or Done if no data was written (e.g. because the stream has no capacity).

Note that in order to avoid buffering an infinite amount of data in the stream's send buffer, streams are only allowed to buffer outgoing data up to the amount that the peer allows it to send (that is, up to the stream's outgoing flow control capacity).

This means that the number of written bytes returned can be lower than the length of the input buffer when the stream doesn't have enough capacity for the operation to complete. The application should retry the operation once the stream is reported as writable again.

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_capacity(&self, stream_id: u64) -> Result<usize>

Returns the stream's send capacity in bytes.

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.

pub fn stream_init_application_data<T>(
    &mut self,
    stream_id: u64,
    data: T
) -> Result<()> where
    T: Any, 

Initializes the stream's application data.

This can be used by applications to store per-stream information without having to maintain their own stream map.

Stream data can only be initialized once. Additional calls to this method will return Done.

pub fn stream_application_data(
    &mut self,
    stream_id: u64
) -> Option<&mut dyn Any>

Returns the stream's application data, if any was initialized.

This returns a reference to the application data that was initialized by calling stream_init_application_data().

pub fn readable(&self) -> StreamIter

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

Note that the iterator will only include streams that were readable at the time the iterator itself was created (i.e. when readable() was called). To account for newly readable streams, the iterator needs to be created again.

Examples:

// Iterate over readable streams.
for stream_id in conn.readable() {
    // 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 writable(&self) -> StreamIter

Returns an iterator over streams that can be written to.

A "writable" stream is a stream that has enough flow control capacity to send data to the peer. To avoid buffering an infinite amount of data, streams are only allowed to buffer outgoing data up to the amount that the peer allows to send.

Note that the iterator will only include streams that were writable at the time the iterator itself was created (i.e. when writable() was called). To account for newly writable streams, the iterator needs to be created again.

Examples:

// Iterate over writable streams.
for stream_id in conn.writable() {
    // Stream is writable, write some data.
    if let Ok(written) = conn.stream_send(stream_id, &buf, false) {
        println!("Written {} bytes on stream {}", written, 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: u64, 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 peer_cert(&self) -> Option<Vec<u8>>

Returns the peer's leaf certificate (if any) as a DER-encoded buffer.

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_in_early_data(&self) -> bool

Returns true if the connection has a pending handshake that has progressed enough to send or receive early data.

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.