Struct quiche::Connection [−][src]
pub struct Connection { /* fields omitted */ }
Expand description
A QUIC connection.
Implementations
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.
Configures the given session for resumption.
On the client, this can be used to offer the given serialized session,
as returned by session()
, for resumption.
This must only be called immediately after creating a connection, that is, before any packet is sent or received.
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, from) = socket.recv_from(&mut buf).unwrap();
let recv_info = quiche::RecvInfo { from };
let read = match conn.recv(&mut buf[..read], recv_info) {
Ok(v) => v,
Err(e) => {
// An error occurred, handle it.
break;
},
};
}
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()
orstream_shutdown()
are called).
Examples:
loop {
let (write, send_info) = 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_to(&out[..write], &send_info.to).unwrap();
}
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);
}
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).
Applications can provide a 0-length buffer with the fin flag set to
true. This will lead to a 0-length FIN STREAM frame being sent at the
latest offset. This is the only case where Ok(0)
is 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 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)?;
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.
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.
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.
Returns true if the stream has data that can be read.
Returns true if the stream has enough send capacity.
When len
more bytes can be buffered into the given streamâs send
buffer, true
will be returned, false
otherwise.
In the latter case, if the additional data canât be buffered due to flow control limits, the peer will also be notified.
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.
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
.
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.
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.
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
.
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 StreamIterimpl Iterator for StreamIter type Item = u64;
pub fn readable(&self) -> StreamIterâNotable traits for StreamIterimpl Iterator for StreamIter type Item = u64;
impl Iterator for StreamIter type Item = u64;
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 StreamIterimpl Iterator for StreamIter type Item = u64;
pub fn writable(&self) -> StreamIterâNotable traits for StreamIterimpl Iterator for StreamIter type Item = u64;
impl Iterator for StreamIter type Item = u64;
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);
}
}
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()
.
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);
}
Reads the first received DATAGRAM.
This is the same as dgram_recv()
but returns the DATAGRAM as a
Vec<u8>
instead of copying into the provided buffer.
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.
Returns the length of the first stored DATAGRAM.
Returns the number of items in the DATAGRAM receive queue.
Returns the total size of all items in the DATAGRAM receive queue.
Returns the number of items in the DATAGRAM send queue.
Returns the total size of all items in the DATAGRAM send queue.
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")?;
Sends data in a DATAGRAM frame.
This is the same as dgram_send()
but takes a Vec<u8>
instead of
a slice.
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 });
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.
Processes a timeout event.
If no timeout has occurred it does nothing.
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
.
Returns a string uniquely representing the connection.
This can be used for logging purposes to differentiate between multiple connections.
Returns the negotiated ALPN protocol.
If no protocol has been negotiated, the returned value is empty.
Returns the server name requested by the client.
Returns the peerâs leaf certificate (if any) as a DER-encoded buffer.
Returns the serialized cryptographic session for the connection.
This can be used by a client to cache a connectionâs session, and resume
it later using the set_session()
method.
Returns the source connection ID.
Note that the value returned can change throughout the connectionâs lifetime.
Returns the destination connection ID.
Note that the value returned can change throughout the connectionâs lifetime.
Returns true if the connection handshake is complete.
Returns true if the connection is resumed.
Returns true if the connection has a pending handshake that has progressed enough to send or receive early data.
Returns whether there is stream or DATAGRAM data available to read.
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
.
Returns true if the connection is closed.
If this returns true, the connection object can be dropped.
Returns true if the connection was closed due to the idle timeout.
Returns the error received from the peer, if any.
Note that a Some
return value does not necessarily imply
is_closed()
or any other connection state.
Returns the error close()
was called with, or internally
created quiche errors, if any.
Note that a Some
return value does not necessarily imply
is_closed()
or any other connection state.
Some
also does not guarantee that the error has been sent to
or recieved by the peer.