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 files and directories with explicit shell verbs
• opening URLs
• revealing items in Explorer
• sending files or directories to the Recycle Bin
• creating Windows .lnk and .url shortcuts
• 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_with_verb
• show_properties
• print_with_default
• open_url
• reveal_in_explorer
• open_containing_folder
• move_to_recycle_bin
• move_paths_to_recycle_bin
• empty_recycle_bin
• empty_recycle_bin_for_root
• create_shortcut
• create_url_shortcut
• single_instance
• single_instance_with_scope
• single_instance_with_options
• roaming_app_data
• local_app_data
• ensure_roaming_app_data
• ensure_local_app_data
• is_elevated
• restart_as_admin
• run_as_admin
• run_with_verb
• InstanceScope
• SingleInstanceOptions
• ShortcutOptions
• ShortcutIcon

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_with_verb uses ShellExecuteW with the requested shell verb.
• show_properties and print_with_default are small shell-verb wrappers.
• open_url trims surrounding whitespace before delegating to the Windows shell.
• reveal_in_explorer requires an existing path and launches explorer.exe.
• open_containing_folder opens the existing path’s parent directory.
• move_to_recycle_bin requires an absolute existing path and uses IFileOperation on a dedicated STA thread for recycle-bin behavior.
• move_paths_to_recycle_bin validates all paths before starting one shell recycle-bin operation.
• empty_recycle_bin permanently empties the Recycle Bin without showing shell UI.
• create_shortcut uses IShellLinkW on a dedicated STA thread.
• 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.
• single_instance_with_scope can opt into either the current-session or global mutex namespace.
• restart_as_admin starts a new elevated instance of the current executable, does not terminate the current process, and rejects arguments containing NUL bytes.
• run_as_admin and run_with_verb launch arbitrary commands through ShellExecuteW.

Re-exports

pub use error::Error;

pub use error::Result;

pub use elevation::is_elevated;

pub use elevation::restart_as_admin;

pub use elevation::run_as_admin;

pub use elevation::run_with_verb;

pub use instance::single_instance;

pub use instance::single_instance_with_options;

pub use instance::single_instance_with_scope;

pub use instance::InstanceGuard;

pub use instance::InstanceScope;

pub use instance::SingleInstanceOptions;

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::empty_recycle_bin;

pub use shell::empty_recycle_bin_for_root;

pub use shell::move_paths_to_recycle_bin;

pub use shell::move_to_recycle_bin;

pub use shell::open_containing_folder;

pub use shell::open_url;

pub use shell::open_with_default;

pub use shell::open_with_verb;

pub use shell::print_with_default;

pub use shell::reveal_in_explorer;

pub use shell::show_properties;

pub use shortcuts::create_shortcut;

pub use shortcuts::create_url_shortcut;

pub use shortcuts::ShortcutIcon;

pub use shortcuts::ShortcutOptions;

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.

shortcuts

Shortcut helpers for Windows .lnk and .url files.