Struct winreg::RegKey [−] [src]

pub struct RegKey {
    // some fields omitted
}

Handle of opened registry key

Methods

impl RegKey
[src]

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

fn open_subkey<P: AsRef<OsStr>>(&self, path: P) -> Result<RegKey>

Open subkey with KEY_ALL_ACCESS permissions. Will open another handle to itself if path is an empty string. To open with different permissions use open_subkey_with_flags.

Examples

let soft = RegKey::predef(HKEY_CURRENT_USER)
    .open_subkey("Software").unwrap();

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).unwrap();

fn open_subkey_transacted<P: AsRef<OsStr>>(&self, path: P, t: &Transaction) -> Result<RegKey>

Part of transactions feature.

fn open_subkey_transacted_with_flags<P: AsRef<OsStr>>(&self, path: P, t: &Transaction, perms: REGSAM) -> Result<RegKey>

Part of transactions feature.

fn create_subkey<P: AsRef<OsStr>>(&self, path: P) -> Result<RegKey>

Create subkey (and all missing parent keys) and open it with KEY_ALL_ACCESS permissions. Will just open key if it already exists. Will open another handle to itself if path is an empty string. To create with different permissions use create_subkey_with_flags.

Examples

let hkcu = RegKey::predef(HKEY_CURRENT_USER);
let settings = hkcu.create_subkey("Software\\MyProduct\\Settings").unwrap();

fn create_subkey_with_flags<P: AsRef<OsStr>>(&self, path: P, perms: REGSAM) -> Result<RegKey>

fn create_subkey_transacted<P: AsRef<OsStr>>(&self, path: P, t: &Transaction) -> Result<RegKey>

Part of transactions feature.

fn create_subkey_transacted_with_flags<P: AsRef<OsStr>>(&self, path: P, t: &Transaction, perms: REGSAM) -> Result<RegKey>

Part of transactions feature.

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).unwrap();
let dst = hkcu.create_subkey("Software\\MyProduct\\Section2").unwrap();
src.copy_tree("Section1", &dst).unwrap();

fn query_info(&self) -> Result<RegKeyMetadata>

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

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)
    .unwrap();
for (name, value) in system.enum_values().map(|x| x.unwrap()) {
    println!("{} = {:?}", name, value);
}

fn delete_subkey<P: AsRef<OsStr>>(&self, path: P) -> Result<()>

Delete key. Cannot delete if it has subkeys. Will delete itself if path is an empty string. Use delete_subkey_all for that.

Examples

RegKey::predef(HKEY_CURRENT_USER)
    .delete_subkey(r"Software\MyProduct\History").unwrap();

fn delete_subkey_transacted<P: AsRef<OsStr>>(&self, path: P, t: &Transaction) -> Result<()>

Part of transactions feature.

fn delete_subkey_all<P: AsRef<OsStr>>(&self, path: P) -> Result<()>

Recursively delete subkey with all its subkeys and values. Will delete itself if path is an empty string.

Examples

RegKey::predef(HKEY_CURRENT_USER)
    .delete_subkey_all("Software\\MyProduct").unwrap();

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 settings = hkcu.open_subkey("Software\\MyProduct\\Settings").unwrap();
let server: String = settings.get_value("server").unwrap();
let port: u32 = settings.get_value("port").unwrap();

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 settings = hkcu.open_subkey("Software\\MyProduct\\Settings").unwrap();
let data = settings.get_raw_value("data").unwrap();
println!("Bytes: {:?}", data.bytes);

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 settings = hkcu.create_subkey("Software\\MyProduct\\Settings").unwrap();
settings.set_value("server", &"www.example.com").unwrap();
settings.set_value("port", &8080u32).unwrap();

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").unwrap();
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).unwrap();
println!("Bytes: {:?}", data.bytes)

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 settings = hkcu.open_subkey("Software\\MyProduct\\Settings").unwrap();
settings.delete_value("data").unwrap();

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

Save Encodable type to a registry key. Part of serialization-rustc feature.

Examples

extern crate rustc_serialize;
extern crate winreg;
use winreg::RegKey;
use winreg::enums::*;
use rustc_serialize::Encodable;

#[derive(RustcEncodable)]
struct Rectangle{
    x: u32,
    y: u32,
    w: u32,
    h: u32,
}

#[derive(RustcEncodable)]
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").unwrap();
s_key.encode(&s).unwrap();

fn decode<T: Decodable>(&self) -> DecodeResult<T>

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

Examples

extern crate rustc_serialize;
extern crate winreg;
use winreg::RegKey;
use winreg::enums::*;
use rustc_serialize::Decodable;

#[derive(RustcDecodable)]
struct Rectangle{
    x: u32,
    y: u32,
    w: u32,
    h: u32,
}

#[derive(RustcDecodable)]
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").unwrap();
let s: Settings = s_key.decode().unwrap();

Trait Implementations

impl Debug for RegKey
[src]

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Drop for RegKey
[src]

fn drop(&mut self)

A method called when the value goes out of scope. Read more