结构体 Connection 

pub struct Connection(/* private fields */);

一个 QUIC 连接。

如果一个连接的所有引用（包括每个 Connection 句柄的克隆、各类入站流以及各种流类型）都被释放，则该连接会自动关闭，error_code 为 0 且 reason 为空。你也可以通过调用 Connection::close() 来显式关闭连接。

关闭连接会立即放弃向对端投递数据的尝试。对端在收到 CONNECTION_CLOSE 时可能会丢弃尚未交付给应用的任何流数据。Connection::close() 中更详细地介绍了如何在不丢失应用数据的前提下优雅地关闭连接。

可以通过克隆来获得指向同一连接的另一个句柄。

实现

impl Connection

pub fn open_uni(&self) -> OpenUni<'_>

发起一个新的出站单向流。

流的打开操作非常廉价且几乎是瞬时的，除非被流控阻塞。因此，在流真正被使用之前，对端并不会被通知该流已被打开。

pub fn open_bi(&self) -> OpenBi<'_>

发起一个新的出站双向流。

流的打开操作非常廉价且几乎是瞬时的，除非被流控阻塞。因此，在流真正被使用之前，对端并不会被通知该流已被打开。调用 open_bi() 后，如果不在 SendStream 上写入任何内容就等待 RecvStream，那么将永远无法成功。

pub fn accept_uni(&self) -> AcceptUni<'_>

接受下一条入站的单向流

pub fn accept_bi(&self) -> AcceptBi<'_>

接受下一条入站的双向流

重要提示：调用 open_bi() 的那个 Connection 必须先在自己的 SendStream 上写入数据，另一端的 Connection 才能 accept_bi() 成功。调用 open_bi() 之后，如果不在 SendStream 上写入任何内容就等待 RecvStream，将永远无法成功。

pub fn read_datagram(&self) -> ReadDatagram<'_>

接收一个应用数据报

pub async fn closed(&self) -> ConnectionError

等待该连接因任何原因而关闭

尽管返回类型的名字带有“closed”，但连接关闭本身在应用层并不一定意味着错误。常见的常规情况包括 ConnectionError::LocallyClosed 和 ConnectionError::ApplicationClosed。

pub fn close_reason(&self) -> Option<ConnectionError>

若连接已关闭，则返回其关闭原因。

若连接仍然处于打开状态，则返回 None。

pub fn close(&self, error_code: VarInt, reason: &[u8])

立即关闭该连接。

所有挂起的操作都会立刻失败，并返回 ConnectionError::LocallyClosed。不会再向对端发送任何数据，对端在收到 CONNECTION_CLOSE 帧时也可能会丢弃其缓冲区中的数据。

error_code 与 reason 不会被解释，会原样传递给对端。

reason 会被截断以适应单个数据包（包括开销）；为提高它被完整保留的概率，建议将其长度控制在 1KiB 以内。

优雅地关闭连接

只有最后接收到应用数据的那一端才能确认所有数据已经被送达。它随后能采取的可靠动作就是关闭连接（可以带上自定义错误码）。如果两端都保持在线足够长的时间，那么最终的 CONNECTION_CLOSE 帧大概率能够送达；可以使用 Endpoint::wait_idle() 来提供这段等待时间。否则，远端将会在空闲超时（前提是未禁用空闲超时）后让连接超时。

发送方无法保证所有的流数据都已经被送达远端应用，它只能确认数据已经送达远端的 QUIC 协议栈。一旦本端在调用 close() 后发送了 CONNECTION_CLOSE 帧，远端就可以丢弃任何它已收到但尚未交付给应用的数据——包括那些已经向本端确认收到的数据。

pub fn send_datagram(&self, data: Bytes) -> Result<(), SendDatagramError>

将 data 作为不可靠、无序的应用数据报发送出去

应用数据报是一个底层原语。它可能会丢失，也可能乱序到达；并且 data 必须既能容纳在单个 QUIC 数据包之内，又要小于对端所规定的最大值。

为了腾出空间容纳本数据报，已经排队但尚未发出、且比本数据报更早入队的数据报可能会被按从旧到新的顺序丢弃。

pub fn send_datagram_wait(&self, data: Bytes) -> SendDatagram<'_>

将 data 作为不可靠、无序的应用数据报发送出去

与 send_datagram() 不同，本方法在拥塞导致缓冲区不足时会等待空闲空间，因此实际上是优先发送旧的数据报而非新的。

详细信息请参阅 send_datagram()。

pub fn max_datagram_size(&self) -> Option<usize>

计算可传递给 send_datagram() 的数据报最大尺寸。

若对端不支持数据报，或本端禁用了数据报，则返回 None。

该值在连接生命周期内可能会随路径 MTU 估值的变化而变化。对端也可以强制施加一个任意小的固定上限；但只要对端的上限比较大，则该值保证至少略大于 1 KiB。

该值不一定等于接收到的数据报的最大尺寸。

pub fn datagram_send_buffer_space(&self) -> usize

出站数据报缓冲区中可用的字节数

当该值大于零时，调用 send_datagram() 发送一个不超过此大小的数据报，可以保证不会导致旧的数据报被丢弃。

pub fn side(&self) -> Side

连接所处的角色（客户端或服务器）

pub fn remote_address(&self) -> SocketAddr

对端的 UDP 地址

若 ServerConfig::migration 被设为 true，客户端可以随时更换地址，例如在切换到蜂窝网络连接时。

pub fn local_ip(&self) -> Option<IpAddr>

对端建立该连接时所使用的本地 IP 地址

当端点绑定到 0.0.0.0 或 :: 这样的通配地址时，该地址可能与端点绑定的地址不同。

对于客户端，或者当平台不提供该信息时，该方法会返回 None。在使用 quinn_udp（默认）作为 I/O 实现时，所支持的平台列表见 quinn_udp::RecvMeta::dst_ip。

pub fn rtt(&self) -> Duration

该连接延迟（往返时间）的当前最佳估计值

pub fn stats(&self) -> ConnectionStats

返回该连接的统计信息

pub fn congestion_state(&self) -> Box<dyn Controller>

拥塞控制算法的当前状态，仅供调试使用

pub fn handshake_data(&self) -> Option<Box<dyn Any>>

在握手阶段协商得到的参数

对于已完全建立的连接，或在 Connecting::handshake_data() 成功之后，该方法保证返回 Some。关于返回值的详细信息，请参阅该方法的文档。

pub fn peer_identity(&self) -> Option<Box<dyn Any>>

对端的密码学身份

返回值的具体动态类型由所配置的 Session 决定。对于默认的 rustls 会话，返回值可以被 downcast 为 Vec<rustls::pki_types::CertificateDer>。

pub fn stable_id(&self) -> usize

该连接的一个稳定标识符

对端地址和连接 ID 都可能变化，但该值在连接的生命周期内始终保持不变。

pub fn force_key_update(&self)

主动更新流量密钥

该方法主要为了测试目的而存在。

pub fn export_keying_material( &self, output: &mut [u8], label: &[u8], context: &[u8], ) -> Result<(), ExportKeyingMaterialError>

从该连接的 TLS 会话密钥中派生密钥材料。

当两端使用相同的 label、context 参数以及等长的 output 缓冲区来调用本方法时，它们将在 output 中得到相同的字节序列。这些字节具有密码学强度且是伪随机的，适合直接用作密钥材料。

更多信息请参阅 RFC5705。

pub fn set_max_concurrent_uni_streams(&self, count: VarInt)

修改对端发起的、可以同时处于打开状态的单向流数量上限

只有当已经打开的对端单向流数量少于 count 时，对端才能再打开新的流。较大的 count 会同时提高最小内存占用和最坏情况下的内存占用。

pub fn set_send_window(&self, send_window: u64)

参见 proto::TransportConfig::send_window()

pub fn set_receive_window(&self, receive_window: VarInt)

参见 proto::TransportConfig::receive_window()

pub fn set_max_concurrent_bi_streams(&self, count: VarInt)

修改对端发起的、可以同时处于打开状态的双向流数量上限

只有当已经打开的对端双向流数量少于 count 时，对端才能再打开新的流。较大的 count 会同时提高最小内存占用和最坏情况下的内存占用。

trait 实现

impl Clone for Connection

fn clone(&self) -> Connection

返回值的副本。 更多信息

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. 更多信息

impl Debug for Connection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化器格式化此值。 更多信息