winreg/
lib.rs

1// Copyright 2023, Igor Shaula
2// Licensed under the MIT License <LICENSE or
3// http://opensource.org/licenses/MIT>. This file
4// may not be copied, modified, or distributed
5// except according to those terms.
6
7//! Crate for accessing MS Windows registry
8//!
9//!## Usage
10//!
11//!### Basic usage
12//!
13//!```toml,ignore
14//!# Cargo.toml
15//![dependencies]
16//!winreg = "0.56"
17//!```
18//!
19//!```no_run
20//!use std::io;
21//!use std::path::Path;
22//!use winreg::enums::*;
23//!use winreg::{HKCU, HKLM};
24//!
25//!fn main() -> io::Result<()> {
26//!    println!("Reading some system info...");
27//!    let cur_ver = HKLM.open_subkey("SOFTWARE\\Microsoft\\Windows\\CurrentVersion")?;
28//!    let pf: String = cur_ver.get_value("ProgramFilesDir")?;
29//!    let dp: String = cur_ver.get_value("DevicePath")?;
30//!    println!("ProgramFiles = {}\nDevicePath = {}", pf, dp);
31//!    let info = cur_ver.query_info()?;
32//!    println!("info = {:?}", info);
33//!    let mt = info.get_last_write_time_system();
34//!    println!(
35//!        "last_write_time as windows_sys::Win32::Foundation::SYSTEMTIME = {}-{:02}-{:02} {:02}:{:02}:{:02}",
36//!        mt.wYear, mt.wMonth, mt.wDay, mt.wHour, mt.wMinute, mt.wSecond
37//!    );
38//!
39//!    // enable `chrono` feature on `winreg` to make this work
40//!    // println!(
41//!    //     "last_write_time as chrono::NaiveDateTime = {}",
42//!    //     info.get_last_write_time_chrono()
43//!    // );
44//!
45//!    println!("And now lets write something...");
46//!    let path = Path::new("Software").join("WinregRsExample1");
47//!    let (key, disp) = HKCU.create_subkey(&path)?;
48//!
49//!    match disp {
50//!        REG_CREATED_NEW_KEY => println!("A new key has been created"),
51//!        REG_OPENED_EXISTING_KEY => println!("An existing key has been opened"),
52//!    }
53//!
54//!    key.set_value("TestSZ", &"written by Rust")?;
55//!    let sz_val: String = key.get_value("TestSZ")?;
56//!    key.delete_value("TestSZ")?;
57//!    println!("TestSZ = {}", sz_val);
58//!
59//!    key.set_value("TestMultiSZ", &vec!["written", "by", "Rust"])?;
60//!    let multi_sz_val: Vec<String> = key.get_value("TestMultiSZ")?;
61//!    key.delete_value("TestMultiSZ")?;
62//!    println!("TestMultiSZ = {:?}", multi_sz_val);
63//!
64//!    key.set_value("TestDWORD", &1234567890u32)?;
65//!    let dword_val: u32 = key.get_value("TestDWORD")?;
66//!    println!("TestDWORD = {}", dword_val);
67//!
68//!    key.set_value("TestQWORD", &1234567891011121314u64)?;
69//!    let qword_val: u64 = key.get_value("TestQWORD")?;
70//!    println!("TestQWORD = {}", qword_val);
71//!
72//!    key.create_subkey("sub\\key")?;
73//!    HKCU.delete_subkey_all(&path)?;
74//!
75//!    println!("Trying to open nonexistent key...");
76//!    HKCU.open_subkey(&path).unwrap_or_else(|e| match e.kind() {
77//!        io::ErrorKind::NotFound => panic!("Key doesn't exist"),
78//!        io::ErrorKind::PermissionDenied => panic!("Access denied"),
79//!        _ => panic!("{:?}", e),
80//!    });
81//!    Ok(())
82//!}
83//!```
84//!
85//!### Iterators
86//!
87//!```no_run
88//!use std::io;
89//!use winreg::{HKCR, HKLM};
90//!
91//!fn main() -> io::Result<()> {
92//!    println!("File extensions, registered in system:");
93//!    for i in HKCR.enum_keys().map(|x| x.unwrap())
94//!        .filter(|x| x.starts_with("."))
95//!    {
96//!        println!("{}", i);
97//!    }
98//!
99//!    let system = HKLM.open_subkey("HARDWARE\\DESCRIPTION\\System")?;
100//!    for (name, value) in system.enum_values().map(|x| x.unwrap()) {
101//!        println!("{} = {:?}", name, value);
102//!    }
103//!
104//!    Ok(())
105//!}
106//!```
107//!
108cfg_if::cfg_if! {
109    if #[cfg(not(windows))] {
110        compile_error!("OS not supported. if your application is multi-platform, use `[target.'cfg(windows)'.dependencies] winreg = \"...\"`");
111    } else {
112        pub use crate::reg_key::{RegKey, HKEY, HKCC, HKCR, HKCU, HKLM, HKU};
113        pub use crate::enum_keys::EnumKeys;
114        pub use crate::enum_keys_os_string::EnumKeysOsString;
115        pub use crate::enum_values::EnumValues;
116        pub use crate::enum_values_os_string::EnumValuesOsString;
117        pub use crate::reg_key_metadata::RegKeyMetadata;
118        pub use crate::reg_value::RegValue;
119
120        mod common;
121        #[cfg(feature = "serialization-serde")]
122        pub mod decoder;
123        #[cfg(feature = "serialization-serde")]
124        pub mod encoder;
125        pub mod enums;
126        pub mod reg_key;
127        pub mod reg_key_metadata;
128        pub mod reg_value;
129        pub mod enum_keys;
130        pub mod enum_keys_os_string;
131        pub mod enum_values;
132        pub mod enum_values_os_string;
133        #[cfg(feature = "transactions")]
134        pub mod transaction;
135        pub mod types;
136    }
137}
winreg/lib.rs

winreg/
lib.rs
