windows_erg/
lib.rs

1//! # windows-erg
2//!
3//! Ergonomic, idiomatic Rust wrappers for Windows APIs.
4//!
5//! This library provides safe, easy-to-use abstractions over Windows system APIs,
6//! built on top of the `windows-rs` crate. It handles the complexity of:
7//! - Automatic handle management (RAII)
8//! - Permission handling
9//! - Error conversion and context
10//! - Type safety
11//!
12//! ## Quick Start
13//!
14//! ```no_run
15//! use windows_erg::process::Process;
16//!
17//! // List all running processes
18//! for proc_info in Process::list()? {
19//!     println!("{}: {}", proc_info.pid, proc_info.name);
20//! }
21//! # Ok::<(), windows_erg::Error>(())
22//! ```
23//!
24//! ## Raw File Example
25//!
26//! ```no_run
27//! use windows_erg::file;
28//!
29//! // Requires administrator privileges in most environments.
30//! file::raw_copy(
31//!     r"C:\\Windows\\System32\\drivers\\etc\\hosts",
32//!     r"C:\\Temp\\hosts.copy"
33//! )?;
34//! # Ok::<(), windows_erg::Error>(())
35//! ```
36//!
37//! ## Modules
38//!
39//! - [`process`] - Process management (list, info, kill, spawn)
40//! - [`desktop`] - Desktop windows and tray icon operations
41//! - [`registry`] - Registry operations
42//! - [`evt`] - Windows Event Log querying and reading
43//! - [`etw`] - Event Tracing for Windows (ETW)
44//! - [`file`] - Raw file operations
45//! - [`pipes`] - Windows named and anonymous pipe API (in progress)
46//! - [`service`] - Windows Service Control Manager operations
47
48#![warn(missing_docs)]
49#![cfg(windows)]
50
51pub mod desktop;
52pub mod error;
53pub mod etw;
54pub mod evt;
55pub mod file;
56pub mod mitigation;
57pub mod pipes;
58pub mod process;
59pub mod proxy;
60pub mod registry;
61pub mod security;
62pub mod service;
63pub mod system;
64pub mod types;
65/// Shared utility helpers for UTF-16/Wide conversions and owned Win32 handle RAII.
66pub mod utils;
67/// Shared wait-object primitives for cancellation and coordination.
68pub mod wait;
69
70pub use error::{Error, Result};
71pub use types::{ProcessId, ThreadId};
72pub use wait::Wait;
73
74/// Check if the current process is running with elevated (administrator) privileges.
75///
76/// # Examples
77///
78/// ```no_run
79/// use windows_erg::is_elevated;
80///
81/// if is_elevated()? {
82///     println!("Running as administrator");
83/// } else {
84///     println!("Not running as administrator");
85/// }
86/// # Ok::<(), windows_erg::Error>(())
87/// ```
88pub fn is_elevated() -> Result<bool> {
89    use windows::Win32::Foundation::HANDLE;
90    use windows::Win32::Security::{
91        GetTokenInformation, TOKEN_ELEVATION, TOKEN_QUERY, TokenElevation,
92    };
93    use windows::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken};
94
95    unsafe {
96        let mut token = HANDLE::default();
97        OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token)?;
98
99        let mut elevation = TOKEN_ELEVATION::default();
100        let mut return_length = 0u32;
101
102        GetTokenInformation(
103            token,
104            TokenElevation,
105            Some(&mut elevation as *mut _ as *mut _),
106            std::mem::size_of::<TOKEN_ELEVATION>() as u32,
107            &mut return_length,
108        )?;
109
110        Ok(elevation.TokenIsElevated != 0)
111    }
112}
113
114/// Ensure the current process has elevated privileges, returning an error if not.
115///
116/// # Errors
117///
118/// Returns [`Error::AccessDenied`] if not running with administrator privileges.
119///
120/// # Examples
121///
122/// ```no_run
123/// use windows_erg::require_elevation;
124///
125/// // This will fail if not running as admin
126/// require_elevation()?;
127/// # Ok::<(), windows_erg::Error>(())
128/// ```
129pub fn require_elevation() -> Result<()> {
130    if !is_elevated()? {
131        return Err(Error::AccessDenied(error::AccessDeniedError::new(
132            "operation",
133            "elevation",
134        )));
135    }
136    Ok(())
137}
windows_erg/lib.rs

windows_erg/
lib.rs
