Struct ClientOptions

Creates a new named pipe builder with the default settings.

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)?;

If the client supports reading data. This is enabled by default.

This corresponds to setting GENERIC_READ in the call to CreateFile.

If the created pipe supports writing data. This is enabled by default.

This corresponds to setting GENERIC_WRITE in the call to CreateFile.

Sets qos flags which are combined with other flags and attributes in the call to CreateFile.

By default security_qos_flags is set to SECURITY_IDENTIFICATION, calling this function would override that value completely with the argument specified.

When security_qos_flags is not set, a malicious program can gain the elevated privileges of a privileged Rust process when it allows opening user-specified paths, by tricking it into opening a named pipe. So arguably security_qos_flags should also be set when opening arbitrary paths. However the bits can then conflict with other flags, specifically FILE_FLAG_OPEN_NO_RECALL.

For information about possible values, see Impersonation Levels on the Windows Dev Center site. The SECURITY_SQOS_PRESENT flag is set automatically when using this method.

The pipe mode.

The default pipe mode is PipeMode::Byte. See PipeMode for documentation of what each mode means.

Opens the named pipe identified by addr.

This opens the client using CreateFile with the dwCreationDisposition option set to OPEN_EXISTING.

Errors

This errors if called outside of a Tokio Runtime, or in a runtime that has not enabled I/O, or if any OS-specific I/O errors occur.

There are a few errors you need to take into account when creating a named pipe on the client side:

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

A connect loop that waits until a pipe becomes available looks like this:

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.

Opens the named pipe identified by addr.

This is the same as open except that it supports providing the raw pointer to a structure of SECURITY_ATTRIBUTES which will be passed as the lpSecurityAttributes argument to CreateFile.

Safety

The attrs argument must either be null or point at a valid instance of the SECURITY_ATTRIBUTES structure. If the argument is null, the behavior is identical to calling the open method.

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.