结构体 ClientOptions

Source

pub struct ClientOptions { /* private fields */ }

展开描述

一个构建器，用于从客户端构建命名管道并与之交互。

参见 ClientOptions::open。

实现§

Source §

impl ClientOptions

Source

pub fn new() -> Self

使用默认设置创建一个新的命名管道构建器。

use tokio::net::windows::named_pipe::{ServerOptions, ClientOptions};

const PIPE_NAME: &str = r"\\.\pipe\tokio-named-pipe-client-new";

// Server must be created in order for the client creation to succeed.
let server = ServerOptions::new().create(PIPE_NAME)?;
let client = ClientOptions::new().open(PIPE_NAME)?;

Source

pub fn read(&mut self, allowed: bool) -> &mut Self

如果客户端支持读取数据。默认启用。

这对应于在调用 CreateFile 时设置 GENERIC_READ。

Source

pub fn write(&mut self, allowed: bool) -> &mut Self

如果所创建的管道支持写入数据。默认启用。

这对应于在调用 CreateFile 时设置 GENERIC_WRITE。

Source

pub fn security_qos_flags(&mut self, flags: u32) -> &mut Self

设置 qos 标志，这些标志会在调用 CreateFile 时与其他标志和属性合并。

默认情况下，security_qos_flags 被设置为 SECURITY_IDENTIFICATION，调用此函数会使用所提供的参数完全覆盖该值。

当未设置 security_qos_flags 时，恶意程序可以通过诱使特权 Rust 进程打开命名管道，从而在允许打开用户指定路径时获得该进程的提升权限。因此在打开任意路径时，按理也应设置 security_qos_flags。不过这些位可能会与其他标志（特别是 FILE_FLAG_OPEN_NO_RECALL）冲突。

有关可能取值的更多信息，请参阅 Windows 开发人员中心网站上的 Impersonation Levels。在使用此方法时，SECURITY_SQOS_PRESENT 标志会被自动设置。

Source

pub fn pipe_mode(&mut self, pipe_mode: PipeMode) -> &mut Self

管道模式。

默认的管道模式是 PipeMode::Byte。有关每种模式的含义，请参阅 PipeMode 的文档。

Source

pub fn open(&self, addr: impl AsRef<OsStr>) -> Result<NamedPipeClient>

打开由 addr 标识的命名管道。

使用 CreateFile 打开客户端，其中 dwCreationDisposition 选项设置为 OPEN_EXISTING。

§Errors

如果在 Tokio 运行时之外被调用，或者在未启用 I/O的运行时中调用，或者发生任何操作系统特有的 I/O 错误，则此函数会出错。

在客户端创建命名管道时，需要考虑几种错误情况：

std::io::ErrorKind::NotFound - This indicates that the named pipe does not exist. Presumably the server is not up.
ERROR_PIPE_BUSY - This error is raised when the named pipe exists, but the server is not currently waiting for a connection. Please see the examples for how to check for this error.

等待管道变为可用的连接循环如下所示：

use std::time::Duration;
use tokio::net::windows::named_pipe::ClientOptions;
use tokio::time;
use windows_sys::Win32::Foundation::ERROR_PIPE_BUSY;

const PIPE_NAME: &str = r"\\.\pipe\mynamedpipe";

let client = loop {
    match ClientOptions::new().open(PIPE_NAME) {
        Ok(client) => break client,
        Err(e) if e.raw_os_error() == Some(ERROR_PIPE_BUSY as i32) => (),
        Err(e) => return Err(e),
    }

    time::sleep(Duration::from_millis(50)).await;
};

// use the connected client.