Struct ClientOptions

pub struct ClientOptions { /* private fields */ }

Available on Windows 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 compio_fs::named_pipe::{ClientOptions, ServerOptions};

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

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

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

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

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

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

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.

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

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 compio_fs::named_pipe::ClientOptions;
use compio_runtime::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).await {
        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.

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.

impl Default for ClientOptions

fn default() -> Self

Returns the “default value” for a type.