windows_erg/registry/
mod.rs

1//! Windows Registry operations.
2//!
3//! This module provides ergonomic access to the Windows Registry with automatic
4//! handle management and type-safe value operations.
5//!
6//! # Examples
7//!
8//! ## Basic Usage
9//!
10//! ```no_run
11//! use windows_erg::registry::{Hive, RegistryKey};
12//!
13//! // Open a key
14//! let key = RegistryKey::open(
15//!     Hive::LocalMachine,
16//!     r"SOFTWARE\Microsoft\Windows\CurrentVersion"
17//! )?;
18//!
19//! // Read a string value
20//! let program_files: String = key.get_value("ProgramFilesDir")?;
21//!
22//! // Create a new key and write values
23//! let key = RegistryKey::create(Hive::CurrentUser, r"Software\MyApp")?;
24//! key.set_value("Version", "1.0.0")?;
25//! key.set_value("Count", 42u32)?;
26//!
27//! // Enumerate subkeys
28//! for subkey in key.subkeys()? {
29//!     println!("Subkey: {}", subkey);
30//! }
31//! # Ok::<(), windows_erg::Error>(())
32//! ```
33//!
34//! ## Convenience Functions
35//!
36//! ```no_run
37//! use windows_erg::registry::{self, Hive};
38//!
39//! // Quick read/write without opening a key
40//! let version = registry::read_string(
41//!     Hive::LocalMachine,
42//!     r"SOFTWARE\Microsoft\Windows NT\CurrentVersion",
43//!     "ProductName"
44//! )?;
45//!
46//! registry::write_u32(Hive::CurrentUser, r"Software\MyApp", "Count", 42)?;
47//! # Ok::<(), windows_erg::Error>(())
48//! ```
49//!
50//! ## Advanced Key Opening
51//!
52//! ```no_run
53//! use windows_erg::registry::{Hive, RegistryKey};
54//!
55//! // Open with WOW64 view and specific access
56//! let key = RegistryKey::builder()
57//!     .hive(Hive::LocalMachine)
58//!     .path(r"SOFTWARE\MyApp")
59//!     .write()
60//!     .wow64_32()
61//!     .open()?;
62//! # Ok::<(), windows_erg::Error>(())
63//! ```
64
65mod builder;
66mod key;
67mod types;
68mod values;
69
70#[cfg(test)]
71mod tests;
72
73pub use builder::RegistryKeyBuilder;
74pub use key::RegistryKey;
75pub use types::{Access, Hive};
76pub use values::RegistryValue;
77
78use crate::Result;
79use crate::security::{ApplyMode, DescriptorEditResult, PermissionEditPlan, SecurityDescriptor};
80
81// Convenience functions for quick registry operations
82
83/// Read a string value from the registry without opening a key.
84pub fn read_string(hive: Hive, path: &str, name: &str) -> Result<String> {
85    let key = RegistryKey::open(hive, path)?;
86    key.get_value(name)
87}
88
89/// Write a string value to the registry without opening a key.
90pub fn write_string(hive: Hive, path: &str, name: &str, value: &str) -> Result<()> {
91    let key = RegistryKey::create(hive, path)?;
92    key.set_value(name, value.to_string())
93}
94
95/// Read a DWORD (u32) value from the registry.
96pub fn read_u32(hive: Hive, path: &str, name: &str) -> Result<u32> {
97    let key = RegistryKey::open(hive, path)?;
98    key.get_value(name)
99}
100
101/// Write a DWORD (u32) value to the registry.
102pub fn write_u32(hive: Hive, path: &str, name: &str, value: u32) -> Result<()> {
103    let key = RegistryKey::create(hive, path)?;
104    key.set_value(name, value)
105}
106
107/// Read a QWORD (u64) value from the registry.
108pub fn read_u64(hive: Hive, path: &str, name: &str) -> Result<u64> {
109    let key = RegistryKey::open(hive, path)?;
110    key.get_value(name)
111}
112
113/// Write a QWORD (u64) value to the registry.
114pub fn write_u64(hive: Hive, path: &str, name: &str, value: u64) -> Result<()> {
115    let key = RegistryKey::create(hive, path)?;
116    key.set_value(name, value)
117}
118
119/// Read a boolean value from the registry (stored as DWORD).
120pub fn read_bool(hive: Hive, path: &str, name: &str) -> Result<bool> {
121    let key = RegistryKey::open(hive, path)?;
122    key.get_value(name)
123}
124
125/// Write a boolean value to the registry (stored as DWORD).
126pub fn write_bool(hive: Hive, path: &str, name: &str, value: bool) -> Result<()> {
127    let key = RegistryKey::create(hive, path)?;
128    key.set_value(name, value)
129}
130
131/// Read binary data from the registry.
132pub fn read_binary(hive: Hive, path: &str, name: &str) -> Result<Vec<u8>> {
133    let key = RegistryKey::open(hive, path)?;
134    key.get_value(name)
135}
136
137/// Write binary data to the registry.
138pub fn write_binary(hive: Hive, path: &str, name: &str, value: &[u8]) -> Result<()> {
139    let key = RegistryKey::create(hive, path)?;
140    key.set_value(name, value.to_vec())
141}
142
143/// Read a multi-string value from the registry.
144pub fn read_multi_string(hive: Hive, path: &str, name: &str) -> Result<Vec<String>> {
145    let key = RegistryKey::open(hive, path)?;
146    key.get_value(name)
147}
148
149/// Write a multi-string value to the registry.
150pub fn write_multi_string(hive: Hive, path: &str, name: &str, value: &[String]) -> Result<()> {
151    let key = RegistryKey::create(hive, path)?;
152    key.set_value(name, value.to_vec())
153}
154
155/// Read a registry key security descriptor.
156pub fn read_security_descriptor(hive: Hive, path: &str) -> Result<SecurityDescriptor> {
157    let key = RegistryKey::open(hive, path)?;
158    key.security_descriptor()
159}
160
161/// Write a registry key security descriptor.
162pub fn write_security_descriptor(
163    hive: Hive,
164    path: &str,
165    descriptor: &SecurityDescriptor,
166) -> Result<()> {
167    let key = RegistryKey::builder()
168        .hive(hive)
169        .path(path)
170        .read_write()
171        .open()?;
172    key.set_security_descriptor(descriptor)
173}
174
175/// Apply a permission edit plan to a registry key.
176pub fn apply_permissions(
177    hive: Hive,
178    path: &str,
179    plan: &PermissionEditPlan,
180    mode: ApplyMode,
181) -> Result<DescriptorEditResult> {
182    let key = RegistryKey::builder()
183        .hive(hive)
184        .path(path)
185        .read_write()
186        .open()?;
187    key.apply_permissions(plan, mode)
188}
windows_erg/registry/mod.rs

windows_erg/registry/
mod.rs
