winreg

Rust bindings to MS Windows Registry API. Work in progress.

Current features: * Basic registry operations: * open/create/delete keys * read and write values * seamless conversion between REG_* types and rust primitives * String and OsString <= REG_SZ, REG_EXPAND_SZ or REG_MULTI_SZ * String, &str and OsStr => REG_SZ * u32 <=> REG_DWORD * u64 <=> REG_QWORD * Iteration through key names and through values * Transactions * Transacted serialization of rust types into/from registry (only primitives and structures for now)

Usage

Basic usage

```toml

Cargo.toml

[dependencies] winreg = "0.6" ```

```rust extern crate winreg; use std::path::Path; use std::io; use winreg::RegKey; use winreg::enums::*;

fn main() -> io::Result<()> { println!("Reading some system info..."); let hklm = RegKey::predef(HKEYLOCALMACHINE); let curver = hklm.opensubkey("SOFTWARE\Microsoft\Windows\CurrentVersion")?; let pf: String = curver.getvalue("ProgramFilesDir")?; let dp: String = curver.getvalue("DevicePath")?; println!("ProgramFiles = {}\nDevicePath = {}", pf, dp); let info = curver.queryinfo()?; println!("info = {:?}", info);

println!("And now lets write something...");
let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let path = Path::new("Software").join("WinregRsExample1");
let (key, disp) = hkcu.create_subkey(&path)?;

match disp {
    REG_CREATED_NEW_KEY => println!("A new key has been created"),
    REG_OPENED_EXISTING_KEY => println!("An existing key has been opened")
}

key.set_value("TestSZ", &"written by Rust")?;
let sz_val: String = key.get_value("TestSZ")?;
key.delete_value("TestSZ")?;
println!("TestSZ = {}", sz_val);

key.set_value("TestDWORD", &1234567890u32)?;
let dword_val: u32 = key.get_value("TestDWORD")?;
println!("TestDWORD = {}", dword_val);

key.set_value("TestQWORD", &1234567891011121314u64)?;
let qword_val: u64 = key.get_value("TestQWORD")?;
println!("TestQWORD = {}", qword_val);

key.create_subkey("sub\\key")?;
hkcu.delete_subkey_all(&path)?;

println!("Trying to open nonexistent key...");
hkcu.open_subkey(&path)
.unwrap_or_else(|e| match e.kind() {
    io::ErrorKind::NotFound => panic!("Key doesn't exist"),
    io::ErrorKind::PermissionDenied => panic!("Access denied"),
    _ => panic!("{:?}", e)
});
Ok(())

} ```

Iterators

```rust extern crate winreg; use std::io; use winreg::RegKey; use winreg::enums::*;

fn main() -> io::Result<()> { println!("File extensions, registered in system:"); for i in RegKey::predef(HKEYCLASSESROOT) .enumkeys().map(|x| x.unwrap()) .filter(|x| x.startswith(".")) { println!("{}", i); }

let system = RegKey::predef(HKEY_LOCAL_MACHINE)
    .open_subkey("HARDWARE\\DESCRIPTION\\System")?;
for (name, value) in system.enum_values().map(|x| x.unwrap()) {
    println!("{} = {:?}", name, value);
}

Ok(())

} ```

Transactions

```toml

Cargo.toml

[dependencies] winreg = { version = "0.6", features = ["transactions"] } ```

```rust extern crate winreg; use std::io; use winreg::RegKey; use winreg::enums::*; use winreg::transaction::Transaction;

fn main() -> io::Result<()> { let t = Transaction::new()?; let hkcu = RegKey::predef(HKEYCURRENTUSER); let (key, disp) = hkcu.createsubkeytransacted("Software\RustTransaction", &t)?; key.setvalue("TestQWORD", &1234567891011121314u64)?; key.set_value("TestDWORD", &1234567890u32)?;

println!("Commit transaction? [y/N]:");
let mut input = String::new();
io::stdin().read_line(&mut input)?;
input = input.trim_right().to_owned();
if input == "y" || input == "Y" {
    t.commit()?;
    println!("Transaction committed.");
}
else {
    // this is optional, if transaction wasn't committed,
    // it will be rolled back on disposal
    t.rollback()?;

    println!("Transaction wasn't committed, it will be rolled back.");
}

Ok(())

} ```

Serialization

```toml

Cargo.toml

[dependencies] winreg = { version = "0.6", features = ["serialization-serde"] } serde = "1" serde_derive = "1" ```

```rust

[macro_use]

extern crate serde_derive; extern crate winreg; use std::error::Error; use winreg::enums::*;

[derive(Debug, Serialize, Deserialize, PartialEq)]

struct Coords { x: u32, y: u32, }

[derive(Debug, Serialize, Deserialize, PartialEq)]

struct Size { w: u32, h: u32, }

[derive(Debug, Serialize, Deserialize, PartialEq)]

struct Rectangle { coords: Coords, size: Size, }

[derive(Debug, Serialize, Deserialize, PartialEq)]

struct Test { tbool: bool, tu8: u8, tu16: u16, tu32: u32, tu64: u64, tusize: usize, tstruct: Rectangle, tstring: String, ti8: i8, ti16: i16, ti32: i32, ti64: i64, tisize: isize, tf64: f64, t_f32: f32, }

fn main() -> Result<(), Box> { let hkcu = winreg::RegKey::predef(HKEYCURRENTUSER); let (key, disp) = hkcu.createsubkey("Software\RustEncode")?; let v1 = Test{ tbool: false, tu8: 127, tu16: 32768, tu32: 123456789, tu64: 123456789101112, tusize: 1234567891, tstruct: Rectangle{ coords: Coords{ x: 55, y: 77 }, size: Size{ w: 500, h: 300 }, }, tstring: "test 123!".toowned(), ti8: -123, ti16: -2049, ti32: 20100, ti64: -12345678910, tisize: -1234567890, tf64: -0.01, tf32: 3.14, };

key.encode(&v1)?;

let v2: Test = key.decode()?;
println!("Decoded {:?}", v2);

println!("Equal to encoded: {:?}", v1 == v2);
Ok(())

} ```

Changelog

0.6.0

• Breaking change: create_subkey, create_subkey_with_flags, create_subkey_transacted and create_subkey_transacted_with_flags now return a tuple which contains the subkey and its disposition which can be REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY (#21).
• Examples fixed to not use unwrap according to Rust API guidelines.

0.5.1

• Reexport HKEY (#15).
• Add raw_handle method (#18).

0.5.0

• Breaking change: open_subkey now opens a key with readonly permissions. Use create_subkey or open_subkey_with_flags to open with read-write permissins.
• Breaking change: features transactions and serialization-serde are now disabled by default.
• Breaking change: serialization now uses serde instead of rustc-serialize.
• winapi updated to 0.3.
• Documentation fixes (#14)

0.4.0

• Make transactions and serialization otional features
• Update dependensies + minor fixes (#12)

0.3.5

• Implement FromRegValue for OsString and ToRegValue for OsStr (#8)
• Minor fixes

0.3.4

• Add copy_tree method to RegKey
• Now checked with rust-clippy
  • no more unwraps
  • replaced to_string with to_owned
• Fix: reading strings longer than 2048 characters (#6)

0.3.3

• Fix: now able to read values longer than 2048 bytes (#3)

0.3.2

• Fix: FromRegValue trait now requires Sized (fixes build with rust 1.4)

0.3.1

• Fix: bump winapi version to fix build

0.3.0

• Add transactions support and make serialization transacted
• Breaking change: use std::io::{Error,Result} instead of own RegError and RegResult