registry 1.3.0

A safe wrapper for the Windows Registry API
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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

#![cfg(windows)]
#![deny(rust_2018_idioms)]

//! # Registry
//!
//! A convenient crate for safely accessing and mutating the Windows Registry.
//!
//! ## Usage
//!
//! In general, you will want to access a key from a [`Hive`](enum.Hive.html). This crate automatically handles
//! the conversion of `String` and `str` into a UTF-16 string suitable for FFI usage.
//!
//! ```no_run
//! # use registry::{Hive, Security};
//! let regkey = Hive::CurrentUser.open(r"some\nested\path", Security::Read)?;
//! # Ok::<(), registry::Error>(())
//! ```
//!
//! A [`RegKey`](struct.RegKey.html) has all necessary functionality for querying subkeys, values within a key,
//! and accessing key value data.
//!
//! ```no_run
//! # use registry::{Data, Hive, Security};
//! # let regkey = Hive::CurrentUser.open(r"some\nested\path", Security::Read)?;
//! regkey.set_value("SomeValue", &Data::U32(42))?;
//! assert!(matches!(regkey.value("SomeValue")?, Data::U32(42)));
//! # Ok::<(), registry::Error>(())
//! ```
//!
//! [`RegKey`](struct.RegKey.html)s also support iteration of all subkeys with the `keys()` function, and all values with the `values()` function.
//!

mod hive;
pub mod iter;
pub mod key;
mod sec;
pub mod value;

pub use hive::Hive;
#[doc(inline)]
pub use key::RegKey;
pub use sec::Security;
#[doc(inline)]
pub use value::Data;

#[derive(Debug, thiserror::Error)]
/// A higher level convenience error type for functions that do
/// multiple registry-related operations and don't want to invent
/// their own error type.
pub enum Error {
    #[error("A key error occurred.")]
    Key(#[from] key::Error),
    #[error("A keys error occurred.")]
    Keys(#[from] iter::keys::Error),
    #[error("A value error occurred.")]
    Value(#[from] value::Error),
    #[error("A values error occurred.")]
    Values(#[from] iter::values::Error),
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::convert::TryInto;

    #[test]
    fn open_key() {
        let result = Hive::CurrentUser
            .open(r"SOFTWARE\Microsoft", Security::AllAccess)
            .unwrap();
        println!("{}", result);
    }

    #[test]
    fn iter_keys() {
        let regkey = Hive::CurrentUser
            .open(r"SOFTWARE\Microsoft", Security::AllAccess)
            .unwrap();
        let results = regkey.keys().collect::<Result<Vec<_>, _>>().unwrap();
        println!("{:?}", &results);
    }

    #[test]
    fn iter_values() {
        let regkey = Hive::CurrentUser
            .open(r"Keyboard Layout\Preload", Security::Read)
            .unwrap();
        let results = regkey.values().collect::<Result<Vec<_>, _>>().unwrap();
        println!("{:?}", &results);
    }

    #[test]
    fn display_repr() {
        const KEY_UNINSTALL: &str = r"SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall";
        let regkey = Hive::LocalMachine
            .open(KEY_UNINSTALL, Security::Read)
            .unwrap();

        assert_eq!(
            format!("{}", regkey),
            r"HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall"
        );
    }

    #[test]
    fn set_value_and_delete() {
        let regkey = Hive::CurrentUser
            .create(r"Test\registry-rust-crate", Security::AllAccess)
            .unwrap();
        regkey
            .set_value("test", &Data::String("Meow meow".try_into().unwrap()))
            .unwrap();
        regkey
            .set_value(
                "test2",
                &Data::MultiString(vec![
                    "Meow meow".try_into().unwrap(),
                    "Woop woop".try_into().unwrap(),
                ]),
            )
            .unwrap();
        regkey.set_value("nothing", &Data::None).unwrap();
        regkey
            .set_value("some binary", &Data::Binary(vec![1, 2, 3, 4, 255]))
            .unwrap();
        regkey.set_value("u32", &Data::U32(0x1234FEFE)).unwrap();
        regkey.set_value("u32be", &Data::U32BE(0x1234FEFE)).unwrap();
        regkey
            .set_value("u64", &Data::U64(0x1234FEFE_1234FEFE))
            .unwrap();

        let results = regkey.values().collect::<Result<Vec<_>, _>>().unwrap();
        println!("{:?}", &results);

        assert_eq!(
            format!("{}", regkey),
            r"HKEY_CURRENT_USER\Test\registry-rust-crate"
        );
        let subkey = regkey.create("subkey", Security::AllAccess).unwrap();
        assert_eq!(
            format!("{}", subkey),
            r"HKEY_CURRENT_USER\Test\registry-rust-crate\subkey"
        );

        let subkey = regkey.open("subkey", Security::AllAccess).unwrap();
        assert_eq!(
            format!("{}", subkey),
            r"HKEY_CURRENT_USER\Test\registry-rust-crate\subkey"
        );

        Hive::CurrentUser.delete("Test", true).unwrap();
    }
}