[][src]Struct quiche::Connection

pub struct Connection { /* fields omitted */ }

A QUIC connection.

Methods

impl Connection[src]

pub fn set_keylog(&mut self, writer: Box<dyn Write + Send>)[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).

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.

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.

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 stream_init_application_data<T>(
    &mut self,
    stream_id: u64,
    data: T
) -> Result<()> where
    T: Any + Send
[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[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[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 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 recv(), send() and timeout() 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][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 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_closed(&self) -> bool[src]

Returns true if the connection is closed.

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

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

Collects and returns statistics about the connection.

Auto Trait Implementations

impl !RefUnwindSafe for Connection

impl Send for Connection

impl !Sync for Connection

impl Unpin for Connection

impl !UnwindSafe for Connection

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.