Crate win_desktop_utils 

Windows-first desktop utility helpers for Rust apps.

win-desktop-utils provides small, focused helpers for common Windows desktop-app tasks without forcing consumers to work directly with raw Win32 shell, mutex, and known-folder APIs.

Scope

This crate currently provides helpers for:

• opening files and directories with the default shell handler
• opening URLs
• revealing items in Explorer
• sending files or directories to the Recycle Bin
• enforcing single-instance behavior
• resolving per-user app-data directories
• creating per-user app-data directories if needed
• checking elevation and relaunching as admin

This crate is intended for Windows desktop applications and utilities. Some functions launch external shell behavior or may trigger a UAC prompt. This crate supports Windows only.

Current API

• open_with_default
• open_url
• reveal_in_explorer
• move_to_recycle_bin
• single_instance
• roaming_app_data
• local_app_data
• ensure_roaming_app_data
• ensure_local_app_data
• is_elevated
• restart_as_admin

Example

fn main() -> Result<(), win_desktop_utils::Error> {
    let _guard = match win_desktop_utils::single_instance("demo-app")? {
        Some(guard) => guard,
        None => {
            println!("already running");
            return Ok(());
        }
    };

    let local = win_desktop_utils::ensure_local_app_data("demo-app")?;
    assert!(local.ends_with("demo-app"));

    Ok(())
}

Behavior Notes

• open_with_default requires a non-empty existing path.
• open_url trims surrounding whitespace before delegating to the Windows shell.
• reveal_in_explorer requires an existing path and launches explorer.exe.
• move_to_recycle_bin requires an absolute existing path and uses IFileOperation on a dedicated STA thread for recycle-bin behavior.
• roaming_app_data and local_app_data resolve their base directories via SHGetKnownFolderPath.
• single_instance uses a Local\... named mutex, so the lock is scoped to the current Windows session, and app_id cannot contain backslashes.
• restart_as_admin starts a new elevated instance of the current executable, does not terminate the current process, and rejects arguments containing NUL bytes.

Re-exports

pub use error::Error;

pub use error::Result;

pub use elevation::is_elevated;

pub use elevation::restart_as_admin;

pub use instance::single_instance;

pub use instance::InstanceGuard;

pub use paths::ensure_local_app_data;

pub use paths::ensure_roaming_app_data;

pub use paths::local_app_data;

pub use paths::roaming_app_data;

pub use shell::move_to_recycle_bin;

pub use shell::open_url;

pub use shell::open_with_default;

pub use shell::reveal_in_explorer;

Modules

elevation

Elevation helpers for checking admin state and relaunching through UAC.

error

Shared error and result types for the crate.

instance

Single-instance helpers backed by named Windows mutexes.

paths

Helpers for resolving and creating per-user application data directories.

shell

Shell-facing helpers for opening files, URLs, Explorer selections, and the Recycle Bin.