registry/
lib.rs

1#![cfg(windows)]
2#![deny(rust_2018_idioms)]
3
4//! # Registry
5//!
6//! A convenient crate for safely accessing and mutating the Windows Registry.
7//!
8//! ## Usage
9//!
10//! In general, you will want to access a key from a [`Hive`](enum.Hive.html). This crate automatically handles
11//! the conversion of `String` and `str` into a UTF-16 string suitable for FFI usage.
12//!
13//! ```no_run
14//! # use registry::{Hive, Security};
15//! let regkey = Hive::CurrentUser.open(r"some\nested\path", Security::Read)?;
16//! # Ok::<(), registry::Error>(())
17//! ```
18//!
19//! A [`RegKey`](struct.RegKey.html) has all necessary functionality for querying subkeys, values within a key,
20//! and accessing key value data.
21//!
22//! ```no_run
23//! # use registry::{Data, Hive, Security};
24//! # let regkey = Hive::CurrentUser.open(r"some\nested\path", Security::Read)?;
25//! regkey.set_value("SomeValue", &Data::U32(42))?;
26//! assert!(matches!(regkey.value("SomeValue")?, Data::U32(42)));
27//! # Ok::<(), registry::Error>(())
28//! ```
29//!
30//! [`RegKey`](struct.RegKey.html)s also support iteration of all subkeys with the `keys()` function, and all values with the `values()` function.
31//!
32
33mod hive;
34pub mod iter;
35pub mod key;
36mod sec;
37pub mod value;
38
39pub use hive::Hive;
40#[doc(inline)]
41pub use key::RegKey;
42pub use sec::Security;
43#[doc(inline)]
44pub use value::Data;
45
46#[derive(Debug, thiserror::Error)]
47/// A higher level convenience error type for functions that do
48/// multiple registry-related operations and don't want to invent
49/// their own error type.
50pub enum Error {
51    #[error("A key error occurred.")]
52    Key(#[from] key::Error),
53    #[error("A keys error occurred.")]
54    Keys(#[from] iter::keys::Error),
55    #[error("A value error occurred.")]
56    Value(#[from] value::Error),
57    #[error("A values error occurred.")]
58    Values(#[from] iter::values::Error),
59}
60
61#[cfg(test)]
62mod tests {
63    use super::*;
64    use std::convert::TryInto;
65
66    #[test]
67    fn open_key() {
68        let result = Hive::CurrentUser
69            .open(r"SOFTWARE\Microsoft", Security::AllAccess)
70            .unwrap();
71        println!("{}", result);
72    }
73
74    #[test]
75    fn iter_keys() {
76        let regkey = Hive::CurrentUser
77            .open(r"SOFTWARE\Microsoft", Security::AllAccess)
78            .unwrap();
79        let results = regkey.keys().collect::<Result<Vec<_>, _>>().unwrap();
80        println!("{:?}", &results);
81    }
82
83    #[test]
84    fn iter_values() {
85        let regkey = Hive::CurrentUser
86            .open(r"Keyboard Layout\Preload", Security::Read)
87            .unwrap();
88        let results = regkey.values().collect::<Result<Vec<_>, _>>().unwrap();
89        println!("{:?}", &results);
90    }
91
92    #[test]
93    fn display_repr() {
94        const KEY_UNINSTALL: &str = r"SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall";
95        let regkey = Hive::LocalMachine
96            .open(KEY_UNINSTALL, Security::Read)
97            .unwrap();
98
99        assert_eq!(
100            format!("{}", regkey),
101            r"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall"
102        );
103    }
104
105    #[test]
106    fn set_value_and_delete() {
107        let regkey = Hive::CurrentUser
108            .create(r"Test\registry-rust-crate", Security::AllAccess)
109            .unwrap();
110        regkey
111            .set_value("test", &Data::String("Meow meow".try_into().unwrap()))
112            .unwrap();
113        regkey
114            .set_value(
115                "test2",
116                &Data::MultiString(vec![
117                    "Meow meow".try_into().unwrap(),
118                    "Woop woop".try_into().unwrap(),
119                ]),
120            )
121            .unwrap();
122        regkey.set_value("nothing", &Data::None).unwrap();
123        regkey
124            .set_value("some binary", &Data::Binary(vec![1, 2, 3, 4, 255]))
125            .unwrap();
126        regkey.set_value("u32", &Data::U32(0x1234FEFE)).unwrap();
127        regkey.set_value("u32be", &Data::U32BE(0x1234FEFE)).unwrap();
128        regkey
129            .set_value("u64", &Data::U64(0x1234FEFE_1234FEFE))
130            .unwrap();
131
132        let results = regkey.values().collect::<Result<Vec<_>, _>>().unwrap();
133        println!("{:?}", &results);
134
135        assert_eq!(
136            format!("{}", regkey),
137            r"HKEY_CURRENT_USER\Test\registry-rust-crate"
138        );
139        let subkey = regkey.create("subkey", Security::AllAccess).unwrap();
140        assert_eq!(
141            format!("{}", subkey),
142            r"HKEY_CURRENT_USER\Test\registry-rust-crate\subkey"
143        );
144
145        let subkey = regkey.open("subkey", Security::AllAccess).unwrap();
146        assert_eq!(
147            format!("{}", subkey),
148            r"HKEY_CURRENT_USER\Test\registry-rust-crate\subkey"
149        );
150
151        Hive::CurrentUser.delete("Test", true).unwrap();
152    }
153}
registry/lib.rs

registry/
lib.rs
