windows-erg 0.1.0

Ergonomic, idiomatic Rust wrappers for Windows APIs
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! # windows-erg
//!
//! Ergonomic, idiomatic Rust wrappers for Windows APIs.
//!
//! This library provides safe, easy-to-use abstractions over Windows system APIs,
//! built on top of the `windows-rs` crate. It handles the complexity of:
//! - Automatic handle management (RAII)
//! - Permission handling
//! - Error conversion and context
//! - Type safety
//!
//! ## Quick Start
//!
//! ```no_run
//! use windows_erg::process::Process;
//!
//! // List all running processes
//! for proc_info in Process::list()? {
//!     println!("{}: {}", proc_info.pid, proc_info.name);
//! }
//! # Ok::<(), windows_erg::Error>(())
//! ```
//!
//! ## Raw File Example
//!
//! ```no_run
//! use windows_erg::file;
//!
//! // Requires administrator privileges in most environments.
//! file::raw_copy(
//!     r"C:\\Windows\\System32\\drivers\\etc\\hosts",
//!     r"C:\\Temp\\hosts.copy"
//! )?;
//! # Ok::<(), windows_erg::Error>(())
//! ```
//!
//! ## Modules
//!
//! - [`process`] - Process management (list, info, kill, spawn)
//! - [`desktop`] - Desktop windows and tray icon operations
//! - [`registry`] - Registry operations
//! - [`evt`] - Windows Event Log querying and reading
//! - [`etw`] - Event Tracing for Windows (ETW)
//! - [`file`] - Raw file operations
//! - [`pipes`] - Windows named and anonymous pipe API (in progress)
//! - [`service`] - Windows Service Control Manager operations

#![warn(missing_docs)]
#![cfg(windows)]

pub mod desktop;
pub mod error;
pub mod etw;
pub mod evt;
pub mod file;
pub mod mitigation;
pub mod pipes;
pub mod process;
pub mod proxy;
pub mod registry;
pub mod security;
pub mod service;
pub mod system;
pub mod types;
/// Shared utility helpers for UTF-16/Wide conversions and owned Win32 handle RAII.
pub mod utils;
/// Shared wait-object primitives for cancellation and coordination.
pub mod wait;

pub use error::{Error, Result};
pub use types::{ProcessId, ThreadId};
pub use wait::Wait;

/// Check if the current process is running with elevated (administrator) privileges.
///
/// # Examples
///
/// ```no_run
/// use windows_erg::is_elevated;
///
/// if is_elevated()? {
///     println!("Running as administrator");
/// } else {
///     println!("Not running as administrator");
/// }
/// # Ok::<(), windows_erg::Error>(())
/// ```
pub fn is_elevated() -> Result<bool> {
    use windows::Win32::Foundation::HANDLE;
    use windows::Win32::Security::{
        GetTokenInformation, TOKEN_ELEVATION, TOKEN_QUERY, TokenElevation,
    };
    use windows::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken};

    unsafe {
        let mut token = HANDLE::default();
        OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token)?;

        let mut elevation = TOKEN_ELEVATION::default();
        let mut return_length = 0u32;

        GetTokenInformation(
            token,
            TokenElevation,
            Some(&mut elevation as *mut _ as *mut _),
            std::mem::size_of::<TOKEN_ELEVATION>() as u32,
            &mut return_length,
        )?;

        Ok(elevation.TokenIsElevated != 0)
    }
}

/// Ensure the current process has elevated privileges, returning an error if not.
///
/// # Errors
///
/// Returns [`Error::AccessDenied`] if not running with administrator privileges.
///
/// # Examples
///
/// ```no_run
/// use windows_erg::require_elevation;
///
/// // This will fail if not running as admin
/// require_elevation()?;
/// # Ok::<(), windows_erg::Error>(())
/// ```
pub fn require_elevation() -> Result<()> {
    if !is_elevated()? {
        return Err(Error::AccessDenied(error::AccessDeniedError::new(
            "operation",
            "elevation",
        )));
    }
    Ok(())
}