Struct winreg::reg_key::RegKey

pub struct RegKey { /* private fields */ }

Handle of opened registry key

Implementations

impl RegKey

pub const 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);

pub fn load_app_key<N: AsRef<OsStr>>(filename: N, lock: bool) -> Result<RegKey>

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)?;

pub fn load_app_key_with_flags<N: AsRef<OsStr>>( filename: N, perms: REG_SAM_FLAGS, options: u32 ) -> Result<RegKey>

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)?;

pub const 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();

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")?;

pub fn open_subkey_with_flags<P: AsRef<OsStr>>( &self, path: P, perms: REG_SAM_FLAGS ) -> 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)?;

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: REG_SAM_FLAGS ) -> Result<RegKey>

Part of transactions feature.

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: REG_SAM_FLAGS ) -> 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: REG_SAM_FLAGS ) -> Result<(RegKey, RegDisposition)>

Part of transactions feature.

pub fn rename_subkey<ON: AsRef<OsStr>, NN: AsRef<OsStr>>( &self, old_name: ON, new_name: NN ) -> Result<()>

Rename a subkey

Examples

let items = RegKey::predef(HKEY_CURRENT_USER).open_subkey(r"Software\MyProduct\Items")?;
items.rename_subkey("itemA", "itemB")?;

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>

pub const 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);
}

pub const 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);
}

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")?;

pub fn delete_subkey_with_flags<P: AsRef<OsStr>>( &self, path: P, perms: REG_SAM_FLAGS ) -> Result<()>

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<()>

Part of transactions feature.

pub fn delete_subkey_transacted_with_flags<P: AsRef<OsStr>>( &self, path: P, t: &Transaction, perms: REG_SAM_FLAGS ) -> Result<()>

Part of transactions feature.

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")?;

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")?;

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);

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)?;

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);

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")?;

pub fn encode<T: Serialize>(&self, value: &T) -> EncodeResult<()>

Save Encodable type to a registry key. This will create a new transaction for this operation. Part of serialization-serde feature.

Examples

use serde_derive::Serialize;
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)?;

pub fn encode_transacted<T: Serialize>( &self, value: &T, tr: &Transaction ) -> EncodeResult<()>

Save Encodable type to a registry key using an existing transaction. Part of serialization-serde feature.

Examples

use serde_derive::Serialize;
use winreg::transaction::Transaction;
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 transaction = Transaction::new()?;

let s_key = RegKey::predef(HKEY_CURRENT_USER)
    .open_subkey_transacted("Software\\MyProduct\\Settings", &transaction)?;
s_key.encode_transacted(&s, &transaction)?;

transaction.commit()?;

pub fn decode<'de, T: Deserialize<'de>>(&self) -> DecodeResult<T>

Load Decodable type from a registry key. Part of serialization-serde feature.

Examples

use serde_derive::Deserialize;
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()?;

Trait Implementations

impl Debug for RegKey

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for RegKey

fn drop(&mut self)

Executes the destructor for this type.

impl Send for RegKey