Crate sambrs 

sambrs

Safe, opinionated Windows SMB client operations for existing disk shares.

Sam -> SMB -> Rust -> Samba is taken!? -> sambrs

sambrs keeps unsafe Windows FFI, UTF-16 conversion, buffer ownership, validation, cleanup, and WNet quirks out of applications. It supports:

• deviceless, explicit-drive, and automatically assigned connections;
• temporary and persistent drive mappings;
• default, paired, and partial credentials;
• SMB signing and encryption requirements;
• guarded temporary mappings that disconnect on drop;
• querying mapped drives, connection users, and universal UNC paths;
• enumerating active connections, remembered mappings, and a server’s disk shares.

It deliberately does not create or administer shares, handle printers, expose raw WNet controls, or transfer files. See the boundary ADR.

Passwords and their temporary UTF-16 buffers are wiped on drop. Operations, targets, usernames, options, and raw Windows statuses are emitted through tracing; passwords are never logged.

Installation

The crate is Windows-only, so cross-platform applications should make the dependency conditional:

[target.'cfg(windows)'.dependencies]
sambrs = "0.2"

Usage

Configure an SmbTarget and establish a connection. Once connected, std::fs works on the UNC path or mapped drive like any other filesystem path:

use sambrs::{ConnectOptions, DisconnectOptions, DriveLetter, SmbTarget};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let target = SmbTarget::new(r"\\server.local\share")
        .credentials(r"LOGONDOMAIN\user", "pass")
        .mount_on(DriveLetter::D);

    target.connect_with(
        ConnectOptions::new()
            .persist(true)
            .require_privacy(true),
    )?;

    println!("{}", std::fs::metadata(r"D:\")?.is_dir());

    target.disconnect_with(DisconnectOptions::default().forget(true))?;
    Ok(())
}

Persistence requires an explicit or automatically assigned drive. A deviceless connection uses the UNC path directly and is never remembered:

let target = sambrs::SmbTarget::new(r"\\server.local\share");
target.connect()?;

Use a guard for an automatically cleaned-up temporary mapping:

let target = sambrs::SmbTarget::new(r"\\server.local\share");
let connection = target.connect_auto_guarded(sambrs::ConnectOptions::new())?;
println!("mapped on {}", connection.device());

Guarded connections cannot be persistent because persistence outlives the guard.

Inspect existing resources through the focused query and enumeration modules:

for resource in sambrs::enumerate::server_shares(r"\\fileserver")? {
    println!("{:?}", resource?.remote_name);
}

let remote = sambrs::query::get_connection("D:")?;
let user = sambrs::query::get_user("D:")?;
let unc = sambrs::query::get_universal_name(r"D:\folder\file.txt")?;

Testing

The integration tests need a real share and are excluded by default. Point them at one and run them explicitly:

SAMBRS_TEST_SHARE=\\server\share
SAMBRS_TEST_USERNAME=DOMAIN\user
SAMBRS_TEST_PASSWORD=...

cargo test --test integration -- --test-threads=1

The tests mount real drive letters and must run single-threaded.

Migrating from 0.1

0.2 is a breaking rework of the API:

0.1	0.2
SmbShare::new(share, user, pass, Some('d'))	SmbTarget::new(share).credentials(user, pass).mount_on(DriveLetter::D)
share.connect(persist, interactive)	target.connect_with(ConnectOptions::new().persist(persist))
share.disconnect(persist, force)	target.disconnect_with(DisconnectOptions::default().forget(persist).force(force))
Error::CStringConversion	Error::InteriorNul

The old persist: true disconnect argument removed persistence, hence the forget rename. Version 0.2 uses Unicode Windows APIs throughout and omitting credentials now means “use the logged-on Windows identity.”

License

This project is licensed under the MIT License. See the license.

Special thanks

Thanks to Christian Visintin for his article on accessing SMB shares with Rust on Windows. For a fully featured, cross-platform remote-file solution, see remotefs.

Modules

enumerate

Enumerate network resources via WNetOpenEnumW / WNetEnumResourceW: active connections, remembered (persistent) connections, and the shares a server exposes.

query

Query information about existing connections: which remote a device is mapped to, which user a connection runs as, and UNC paths for local paths on redirected drives.

Structs

ConnectOptions

Options for SmbTarget::connect_with.

Connection

RAII guard returned by SmbTarget::connect_guarded and SmbTarget::connect_auto_guarded: cancels the connection when dropped (best effort — a failure on drop is only visible as a tracing event).

DisconnectOptions

Options for SmbTarget::disconnect_with and cancel_connection.

SmbTarget

A reusable target for SMB connections, optionally mapped to a local drive.

Enums

DriveLetter

A local Windows drive letter (A: – Z:).

Error

Errors returned by sambrs operations.

Functions

cancel_connection

Cancel a connection by name: either a mapped drive (e.g. "Z:") or a remote name (\\server\share) for deviceless connections.

Type Aliases

Result