win-desktop-utils 0.2.0

Windows-first desktop utility helpers for Rust apps
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

# 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 and mutex APIs.

## Scope

This crate currently provides helpers to:

- open an existing file or directory with the default Windows handler
- open a URL with the default browser or registered handler
- reveal an existing path in Explorer
- move an existing file or directory to the Recycle Bin
- enforce single-instance behavior with a named mutex
- resolve per-user roaming and local app-data paths
- create per-user roaming and local app-data paths if needed
- check whether the current process is elevated
- relaunch the current executable as administrator

This crate supports Windows only.

## Installation

```toml
[dependencies]
win-desktop-utils = "0.2"
```

## Current API

- `open_with_default(path)`
- `open_url(url)`
- `reveal_in_explorer(path)`
- `move_to_recycle_bin(path)`
- `single_instance(app_id)`
- `roaming_app_data(app_name)`
- `local_app_data(app_name)`
- `ensure_roaming_app_data(app_name)`
- `ensure_local_app_data(app_name)`
- `is_elevated()`
- `restart_as_admin(args)`

## Example

```rust
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")?;
    println!("local app dir: {}", local.display());

    Ok(())
}
```

## Error behavior

The crate exposes a small public error type with explicit path-related cases.

Notable error distinctions include:

- `Error::InvalidInput(...)` for empty or malformed input
- `Error::PathNotAbsolute` when an operation requires an absolute path
- `Error::PathDoesNotExist` when an operation requires an existing path
- `Error::WindowsApi { .. }` when a Win32 or shell operation reports failure
- `Error::Io(...)` for underlying I/O failures

## Behavior notes

- `open_with_default` requires a non-empty existing path.
- `open_url` only checks that the URL string is non-empty after trimming; deeper URL validation is delegated 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 `SHFileOperationW` with undo enabled.
- `single_instance` uses a `Local\...` named mutex, so the lock is scoped to the current Windows session.
- Keep the returned `InstanceGuard` alive for as long as the process should own the single-instance lock.
- `restart_as_admin` starts a new elevated instance of the current executable and does not terminate the current process.

## Quality

The crate includes:

- automated tests for validation and single-instance behavior
- doctest examples in the public modules
- Windows CI via GitHub Actions
- docs published on docs.rs

## Status

Early-stage crate, but tested and usable.

## Links

- Crates.io: https://crates.io/crates/win-desktop-utils
- Docs: https://docs.rs/win-desktop-utils
- Repository: https://github.com/funwithcthulhu/win-desktop-utils