Struct winreg::RegKey [−][src]
pub struct RegKey { /* fields omitted */ }
Expand description
Handle of opened registry key
Implementations
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);
Load a registry hive from a file as an application hive.
If lock
is set to true
, then the hive cannot be loaded again until
it’s unloaded (i.e. all keys from it go out of scope).
Examples
let handle = RegKey::load_app_key("C:\\myhive.dat", false)?;
Load a registry hive from a file as an application hive with desired
permissions and options. If options
is set to REG_PROCESS_APPKEY
,
then the hive cannot be loaded again until it’s unloaded (i.e. all keys
from it go out of scope).
Examples
let handle = RegKey::load_app_key_with_flags("C:\\myhive.dat", KEY_READ, 0)?;
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();
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")?;
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)?;
pub 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.
pub 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.
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)>
pub 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.
pub 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.
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)?;
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);
}
pub const fn enum_values(&self) -> EnumValues<'_>ⓘNotable traits for EnumValues<'key>impl<'key> Iterator for EnumValues<'key> type Item = Result<(String, RegValue)>;
pub const fn enum_values(&self) -> EnumValues<'_>ⓘNotable traits for EnumValues<'key>impl<'key> Iterator for EnumValues<'key> type Item = Result<(String, RegValue)>;
impl<'key> Iterator for EnumValues<'key> type Item = Result<(String, RegValue)>;
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);
}
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")?;
Delete key from the desired platform-specific view of the registry. Key names are not case sensitive.
Examples
// delete the key from the 32-bit registry view
RegKey::predef(HKEY_LOCAL_MACHINE)
.delete_subkey_with_flags(r"Software\MyProduct\History", KEY_WOW64_32KEY)?;
pub 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.
pub fn delete_subkey_transacted_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction,
perms: REGSAM
) -> Result<()>
pub fn delete_subkey_transacted_with_flags<P: AsRef<OsStr>>(
&self,
path: P,
t: &Transaction,
perms: REGSAM
) -> Result<()>
Part of transactions
feature.
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")?;
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")?;
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);
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)?;
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);
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")?;
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)?;
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()?;