pub struct RegKey { /* private fields */ }
Expand description
Handle of opened registry key
Implementations§
source§impl RegKey
impl RegKey
sourcepub fn predef(hkey: HKEY) -> RegKey
pub fn predef(hkey: HKEY) -> RegKey
Open one of predefined keys:
HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS
HKEY_PERFORMANCE_DATA
HKEY_PERFORMANCE_TEXT
HKEY_PERFORMANCE_NLSTEXT
HKEY_CURRENT_CONFIG
HKEY_DYN_DATA
HKEY_CURRENT_USER_LOCAL_SETTINGS
Examples
let hklm = RegKey::predef(HKEY_LOCAL_MACHINE);
sourcepub fn raw_handle(&self) -> HKEY
pub fn raw_handle(&self) -> HKEY
Return inner winapi HKEY of a key:
Examples
let hklm = RegKey::predef(HKEY_LOCAL_MACHINE);
let soft = hklm.open_subkey("SOFTWARE")?;
let handle = soft.raw_handle();
sourcepub fn open_subkey<P: AsRef<OsStr>>(&self, path: P) -> Result<RegKey>
pub fn open_subkey<P: AsRef<OsStr>>(&self, path: P) -> Result<RegKey>
Open subkey with KEY_READ
permissions.
Will open another handle to itself if path
is an empty string.
To open with different permissions use open_subkey_with_flags
.
You can also use create_subkey
to open with KEY_ALL_ACCESS
permissions.
Examples
let soft = RegKey::predef(HKEY_CURRENT_USER)
.open_subkey("Software")?;
sourcepub fn open_subkey_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
perms: REGSAM
) -> Result<RegKey>
pub fn open_subkey_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
perms: REGSAM
) -> Result<RegKey>
Open subkey with desired permissions.
Will open another handle to itself if path
is an empty string.
Examples
let hklm = RegKey::predef(HKEY_LOCAL_MACHINE);
hklm.open_subkey_with_flags("SOFTWARE\\Microsoft", KEY_READ)?;
sourcepub fn open_subkey_transacted<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction
) -> Result<RegKey>
pub fn open_subkey_transacted<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction
) -> Result<RegKey>
Part of transactions
feature.
sourcepub fn open_subkey_transacted_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction,
perms: REGSAM
) -> Result<RegKey>
pub fn open_subkey_transacted_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction,
perms: REGSAM
) -> Result<RegKey>
Part of transactions
feature.
sourcepub fn create_subkey<P: AsRef<OsStr>>(
&self,
path: P
) -> Result<(RegKey, RegDisposition)>
pub fn create_subkey<P: AsRef<OsStr>>(
&self,
path: P
) -> Result<(RegKey, RegDisposition)>
Create subkey (and all missing parent keys)
and open it with KEY_ALL_ACCESS
permissions.
Will just open key if it already exists.
If succeeds returns a tuple with the created subkey and its disposition,
which can be REG_CREATED_NEW_KEY
or REG_OPENED_EXISTING_KEY
.
Will open another handle to itself if path
is an empty string.
To create with different permissions use create_subkey_with_flags
.
Examples
use winreg::enums::*;
let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let (settings, disp) = hkcu.create_subkey("Software\\MyProduct\\Settings")?;
match disp {
REG_CREATED_NEW_KEY => println!("A new key has been created"),
REG_OPENED_EXISTING_KEY => println!("An existing key has been opened")
}
pub fn create_subkey_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
perms: REGSAM
) -> Result<(RegKey, RegDisposition)>
sourcepub fn create_subkey_transacted<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction
) -> Result<(RegKey, RegDisposition)>
pub fn create_subkey_transacted<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction
) -> Result<(RegKey, RegDisposition)>
Part of transactions
feature.
sourcepub fn create_subkey_transacted_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction,
perms: REGSAM
) -> Result<(RegKey, RegDisposition)>
pub fn create_subkey_transacted_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction,
perms: REGSAM
) -> Result<(RegKey, RegDisposition)>
Part of transactions
feature.
sourcepub fn copy_tree<P: AsRef<OsStr>>(&self, path: P, dest: &RegKey) -> Result<()>
pub fn copy_tree<P: AsRef<OsStr>>(&self, path: P, dest: &RegKey) -> Result<()>
Copy all the values and subkeys from path
to dest
key.
WIll copy the content of self
if path
is an empty string.
Examples
let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let src = hkcu.open_subkey_with_flags("Software\\MyProduct", KEY_READ)?;
let (dst, dst_disp) = hkcu.create_subkey("Software\\MyProduct\\Section2")?;
src.copy_tree("Section1", &dst)?;
pub fn query_info(&self) -> Result<RegKeyMetadata>
sourcepub fn enum_keys(&self) -> EnumKeys<'_> ⓘ
pub fn enum_keys(&self) -> EnumKeys<'_> ⓘ
Return an iterator over subkeys names.
Examples
println!("File extensions, registered in this system:");
for i in RegKey::predef(HKEY_CLASSES_ROOT)
.enum_keys().map(|x| x.unwrap())
.filter(|x| x.starts_with("."))
{
println!("{}", i);
}
sourcepub fn enum_values(&self) -> EnumValues<'_> ⓘ
pub fn enum_values(&self) -> EnumValues<'_> ⓘ
Return an iterator over values.
Examples
let system = RegKey::predef(HKEY_LOCAL_MACHINE)
.open_subkey_with_flags("HARDWARE\\DESCRIPTION\\System", KEY_READ)?;
for (name, value) in system.enum_values().map(|x| x.unwrap()) {
println!("{} = {:?}", name, value);
}
sourcepub fn delete_subkey<P: AsRef<OsStr>>(&self, path: P) -> Result<()>
pub fn delete_subkey<P: AsRef<OsStr>>(&self, path: P) -> Result<()>
Delete key.Key names are not case sensitive.
Cannot delete if it has subkeys.
Use delete_subkey_all
for that.
Examples
RegKey::predef(HKEY_CURRENT_USER)
.delete_subkey(r"Software\MyProduct\History")?;
sourcepub fn delete_subkey_transacted<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction
) -> Result<()>
pub fn delete_subkey_transacted<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction
) -> Result<()>
Part of transactions
feature.
sourcepub fn delete_subkey_all<P: AsRef<OsStr>>(&self, path: P) -> Result<()>
pub fn delete_subkey_all<P: AsRef<OsStr>>(&self, path: P) -> Result<()>
Recursively delete subkey with all its subkeys and values.
If path
is an empty string, the subkeys and values of this key are deleted.
Examples
RegKey::predef(HKEY_CURRENT_USER)
.delete_subkey_all("Software\\MyProduct")?;
sourcepub fn get_value<T: FromRegValue, N: AsRef<OsStr>>(&self, name: N) -> Result<T>
pub fn get_value<T: FromRegValue, N: AsRef<OsStr>>(&self, name: N) -> Result<T>
Get a value from registry and seamlessly convert it to the specified rust type
with FromRegValue
implemented (currently String
, u32
and u64
).
Will get the Default
value if name
is an empty string.
Examples
let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let settings = hkcu.open_subkey("Software\\MyProduct\\Settings")?;
let server: String = settings.get_value("server")?;
let port: u32 = settings.get_value("port")?;
sourcepub fn get_raw_value<N: AsRef<OsStr>>(&self, name: N) -> Result<RegValue>
pub fn get_raw_value<N: AsRef<OsStr>>(&self, name: N) -> Result<RegValue>
Get raw bytes from registry value.
Will get the Default
value if name
is an empty string.
Examples
let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let settings = hkcu.open_subkey("Software\\MyProduct\\Settings")?;
let data = settings.get_raw_value("data")?;
println!("Bytes: {:?}", data.bytes);
sourcepub fn set_value<T: ToRegValue, N: AsRef<OsStr>>(
&self,
name: N,
value: &T
) -> Result<()>
pub fn set_value<T: ToRegValue, N: AsRef<OsStr>>(
&self,
name: N,
value: &T
) -> Result<()>
Seamlessly convert a value from a rust type and write it to the registry value
with ToRegValue
trait implemented (currently String
, &str
, u32
and u64
).
Will set the Default
value if name
is an empty string.
Examples
let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let (settings, disp) = hkcu.create_subkey("Software\\MyProduct\\Settings")?;
settings.set_value("server", &"www.example.com")?;
settings.set_value("port", &8080u32)?;
sourcepub fn set_raw_value<N: AsRef<OsStr>>(
&self,
name: N,
value: &RegValue
) -> Result<()>
pub fn set_raw_value<N: AsRef<OsStr>>(
&self,
name: N,
value: &RegValue
) -> Result<()>
Write raw bytes from RegValue
struct to a registry value.
Will set the Default
value if name
is an empty string.
Examples
use winreg::{RegKey, RegValue};
use winreg::enums::*;
let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let settings = hkcu.open_subkey("Software\\MyProduct\\Settings")?;
let bytes: Vec<u8> = vec![1, 2, 3, 5, 8, 13, 21, 34, 55, 89];
let data = RegValue{ vtype: REG_BINARY, bytes: bytes};
settings.set_raw_value("data", &data)?;
println!("Bytes: {:?}", data.bytes);
sourcepub fn delete_value<N: AsRef<OsStr>>(&self, name: N) -> Result<()>
pub fn delete_value<N: AsRef<OsStr>>(&self, name: N) -> Result<()>
Delete specified value from registry.
Will delete the Default
value if name
is an empty string.
Examples
let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let settings = hkcu.open_subkey("Software\\MyProduct\\Settings")?;
settings.delete_value("data")?;
sourcepub fn encode<T: Serialize>(&self, value: &T) -> Result<(), EncoderError>
pub fn encode<T: Serialize>(&self, value: &T) -> Result<(), EncoderError>
Save Encodable
type to a registry key.
Part of serialization-serde
feature.
Examples
#[macro_use]
extern crate serde_derive;
extern crate winreg;
use winreg::RegKey;
use winreg::enums::*;
#[derive(Serialize)]
struct Rectangle{
x: u32,
y: u32,
w: u32,
h: u32,
}
#[derive(Serialize)]
struct Settings{
current_dir: String,
window_pos: Rectangle,
show_in_tray: bool,
}
let s: Settings = Settings{
current_dir: "C:\\".to_owned(),
window_pos: Rectangle{ x:200, y: 100, w: 800, h: 500 },
show_in_tray: false,
};
let s_key = RegKey::predef(HKEY_CURRENT_USER)
.open_subkey("Software\\MyProduct\\Settings")?;
s_key.encode(&s)?;
sourcepub fn decode<'de, T: Deserialize<'de>>(&self) -> Result<T, DecoderError>
pub fn decode<'de, T: Deserialize<'de>>(&self) -> Result<T, DecoderError>
Load Decodable
type from a registry key.
Part of serialization-serde
feature.
Examples
#[macro_use]
extern crate serde_derive;
extern crate winreg;
use winreg::RegKey;
use winreg::enums::*;
#[derive(Deserialize)]
struct Rectangle{
x: u32,
y: u32,
w: u32,
h: u32,
}
#[derive(Deserialize)]
struct Settings{
current_dir: String,
window_pos: Rectangle,
show_in_tray: bool,
}
let s_key = RegKey::predef(HKEY_CURRENT_USER)
.open_subkey("Software\\MyProduct\\Settings")?;
let s: Settings = s_key.decode()?;