Struct quiche::Connection[][src]

pub struct Connection { /* fields omitted */ }

A QUIC connection.

Implementations

impl Connection[src]

pub fn set_keylog(&mut self, writer: Box<dyn Write + Send + Sync>)[src]

Sets keylog output to the designated Writer.

This needs to be called as soon as the connection is created, to avoid missing some early logs.

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

Processes QUIC packets received from the peer.

On success the number of bytes processed from the input buffer is returned. 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(e) => {
            // An error occurred, handle it.
            break;
        },
    };
}

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

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)>
[src]

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>
[src]

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).

In addition, if the peer has signalled that it doesn’t want to receive any more data from this stream by sending the STOP_SENDING frame, the StreamStopped error will be returned instead of any data.

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.

Applications should call this method only after the handshake is completed (whenever is_established() returns true) or during early data if enabled (whenever is_in_early_data() returns true).

Examples:

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

pub fn stream_priority(
    &mut self,
    stream_id: u64,
    urgency: u8,
    incremental: bool
) -> Result<()>
[src]

Sets the priority for a stream.

A stream’s priority determines the order in which stream data is sent on the wire (streams with lower priority are sent first). Streams are created with a default priority of 127.

The target stream is created if it did not exist before calling this method.

pub fn stream_shutdown(
    &mut self,
    stream_id: u64,
    direction: Shutdown,
    err: u64
) -> Result<()>
[src]

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. In addition, a STOP_SENDING frame will be sent to the peer to signal it to stop sending data.

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>[src]

Returns the stream’s send capacity in bytes.

If the specified stream doesn’t exist (including when it has already been completed and closed), the InvalidStreamState error will be returned.

In addition, if the peer has signalled that it doesn’t want to receive any more data from this stream by sending the STOP_SENDING frame, the StreamStopped error will be returned.

pub fn stream_readable(&self, stream_id: u64) -> bool[src]

Returns true if the stream has data that can be read.

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

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 peer_streams_left_bidi(&self) -> u64[src]

Returns the number of bidirectional streams that can be created before the peer’s stream count limit is reached.

This can be useful to know if it’s possible to create a bidirectional stream without trying it first.

pub fn peer_streams_left_uni(&self) -> u64[src]

Returns the number of unidirectional streams that can be created before the peer’s stream count limit is reached.

This can be useful to know if it’s possible to create a unidirectional stream without trying it first.

pub fn stream_init_application_data<T>(
    &mut self,
    stream_id: u64,
    data: T
) -> Result<()> where
    T: Any + Send + Sync
[src]

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>
[src]

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ⓘ

Notable traits for StreamIter

impl Iterator for StreamIter type Item = u64;
[src]

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ⓘ

Notable traits for StreamIter

impl Iterator for StreamIter type Item = u64;
[src]

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 max_send_udp_payload_size(&self) -> usize[src]

Returns the maximum possible size of egress UDP payloads.

This is the maximum size of UDP payloads that can be sent, and depends on both the configured maximum send payload size of the local endpoint (as configured with set_max_send_udp_payload_size()), as well as the transport parameter advertised by the remote peer.

Note that this value can change during the lifetime of the connection, but should remain stable across consecutive calls to send().

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

Reads the first received DATAGRAM.

On success the DATAGRAM’s data is returned along with its size.

Done is returned if there is no data to read.

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

Examples:

let mut dgram_buf = [0; 512];
while let Ok((len)) = conn.dgram_recv(&mut dgram_buf) {
    println!("Got {} bytes of DATAGRAM", len);
}

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

Reads the first received DATAGRAM without removing it from the queue.

On success the DATAGRAM’s data is returned along with the actual number of bytes peeked. The requested length cannot exceed the DATAGRAM’s actual length.

Done is returned if there is no data to read.

BufferTooShort is returned if the provided buffer is smaller the number of bytes to peek.

pub fn dgram_recv_front_len(&self) -> Option<usize>[src]

Returns the length of the first stored DATAGRAM.

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

Sends data in a DATAGRAM frame.

Done is returned if no data was written. InvalidState is returned if the peer does not support DATAGRAM. BufferTooShort is returned if the DATAGRAM frame length is larger than peer’s supported DATAGRAM frame length. Use dgram_max_writable_len() to get the largest supported DATAGRAM frame length.

Note that there is no flow control of DATAGRAM frames, so in order to avoid buffering an infinite amount of frames we apply an internal limit.

Examples:

conn.dgram_send(b"hello")?;

pub fn dgram_purge_outgoing<F: Fn(&[u8]) -> bool>(&mut self, f: F)[src]

Purges queued outgoing DATAGRAMs matching the predicate.

In other words, remove all elements e such that f(&e) returns true.

Examples:

conn.dgram_send(b"hello")?;
conn.dgram_purge_outgoing(&|d: &[u8]| -> bool { d[0] == 0 });

pub fn dgram_max_writable_len(&self) -> Option<usize>[src]

Returns the maximum DATAGRAM payload that can be sent.

None is returned if the peer hasn’t advertised a maximum DATAGRAM frame size.

Examples:

if let Some(payload_size) = conn.dgram_max_writable_len() {
    if payload_size > 5 {
        conn.dgram_send(b"hello")?;
    }
}

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

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)[src]

Processes a timeout event.

If no timeout has occurred it does nothing.

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

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 the recv(), send(), timeout() and on_timeout() methods as normal, until the is_closed() method returns true.

pub fn trace_id(&self) -> &str[src]

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]ⓘ

Notable traits for &'_ [u8]

impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]
[src]

Returns the negotiated ALPN protocol.

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

pub fn peer_cert(&self) -> Option<Vec<u8>>[src]

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

pub fn source_id(&self) -> ConnectionId<'_>[src]

Returns the source connection ID.

Note that the value returned can change throughout the connection’s lifetime.

pub fn destination_id(&self) -> ConnectionId<'_>[src]

Returns the destination connection ID.

Note that the value returned can change throughout the connection’s lifetime.

pub fn is_established(&self) -> bool[src]

Returns true if the connection handshake is complete.

pub fn is_resumed(&self) -> bool[src]

Returns true if the connection is resumed.

pub fn is_in_early_data(&self) -> bool[src]

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

pub fn is_readable(&self) -> bool[src]

Returns whether there is stream or DATAGRAM data available to read.

pub fn is_draining(&self) -> bool[src]

Returns true if the connection is draining.

If this returns true, the connection object cannot yet be dropped, but no new application data can be sent or received. An application should continue calling the recv(), send(), timeout(), and on_timeout() methods as normal, until the is_closed() method returns true.

pub fn is_closed(&self) -> bool[src]

Returns true if the connection is closed.

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

pub fn peer_error(&self) -> Option<&ConnectionError>[src]

Returns the error received from the peer, if any.

The values contained in the tuple are symmetric with the close() method.

Note that a Some return value does not necessarily imply is_closed() or any other connection state.

pub fn stats(&self) -> Stats[src]

Collects and returns statistics about the connection.

Auto Trait Implementations

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.