Struct ClientOptions

pub struct ClientOptions { /* private fields */ }

Available on Windows and crate feature net only.

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 pipe_mode(&mut self, pipe_mode: PipeMode) -> &mut Self

The pipe mode.

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

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

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.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 8 bytes