Struct tokio::net::windows::named_pipe::ClientOptions

pub struct ClientOptions { /* private fields */ }

A builder suitable for building and interacting with named pipes from the client side.

See ClientOptions::open.

Implementations

impl ClientOptions

pub fn new() -> Self

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

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

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

This corresponds to setting GENERIC_READ in the call to CreateFile.

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

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

This corresponds to setting GENERIC_WRITE in the call to CreateFile.

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

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.

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

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 winapi::shared::winerror;

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(winerror::ERROR_PIPE_BUSY as i32) => (),
        Err(e) => return Err(e),
    }

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

// use the connected client.

pub unsafe fn open_with_security_attributes_raw(
    &self,
    addr: impl AsRef<OsStr>,
    attrs: *mut c_void
) -> Result<NamedPipeClient>

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.

Trait Implementations

impl Clone for ClientOptions

fn clone(&self) -> ClientOptions

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ClientOptions

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

Formats the value using the given formatter.