Struct HKEY

pub struct HKEY(/* private fields */);

Available on crate feature advapi only.

Handle to a registry key.

This handle also exposes several predefined registry keys, like HKEY::CURRENT_USER, which are always open and ready to be used. Usually, they are the starting point to open a registry key.

Implementations

impl HKEY

pub const unsafe fn from_ptr(p: *mut c_void) -> Self

Constructs a new handle object by wrapping a pointer.

This method can be used as an escape hatch to interoperate with other libraries.

Safety

Be sure the pointer has the correct type and isn’t owned by anyone else, otherwise you may cause memory access violations.

pub const unsafe fn raw_copy(&self) -> Self

Returns a raw copy of the underlying handle pointer.

Safety

As the name implies, raw_copy returns a raw copy of the handle, so closing one of the copies won’t close the others. This means a handle can be used after it has been closed, what can lead to errors and undefined behavior. Even worse: sometimes Windows reuses handle values, so you can call a method on a completely different handle type, what can be catastrophic.

However, in some cases the Windows API demands a copy of the handle – raw_copy is an escape hatch to fill this gap.

pub const unsafe fn as_mut(&mut self) -> &mut *mut c_void

Returns a mutable reference to the underlying raw pointer.

This method can be used as an escape hatch to interoperate with other libraries.

Safety

This method exposes the raw pointer used by raw Windows calls. It’s an opaque pointer to an internal Windows structure, and no dereferencings should be attempted.

pub const fn ptr(&self) -> *mut c_void

Returns the underlying raw pointer.

This method exposes the raw pointer used by raw Windows calls. It’s an opaque pointer to an internal Windows structure, and no dereferencings should be attempted.

This method can be used as an escape hatch to interoperate with other libraries.

impl HKEY

pub const CLASSES_ROOT: HKEY

Predefined registry key, always open.

pub const CURRENT_USER: HKEY

Predefined registry key, always open.

pub const LOCAL_MACHINE: HKEY

Predefined registry key, always open.

pub const USERS: HKEY

Predefined registry key, always open.

pub const PERFORMANCE_DATA: HKEY

Predefined registry key, always open.

pub const CURRENT_CONFIG: HKEY

Predefined registry key, always open.

pub const DYN_DATA: HKEY

Predefined registry key, always open.

pub const CURRENT_USER_LOCAL_SETTINGS: HKEY

Predefined registry key, always open.

pub const PERFORMANCE_TEXT: HKEY

Predefined registry key, always open.

pub const PERFORMANCE_NLSTEXT: HKEY

Predefined registry key, always open.

pub fn RegConnectRegistry( machine_name: Option<&str>, predef_hkey: &HKEY, ) -> SysResult<RegCloseKeyGuard>

RegConnectRegistry function.

Panics

Panics if predef_key is different from:

• HKEY::LOCAL_MACHINE;
• HKEY::PERFORMANCE_DATA;
• HKEY::USERS.

pub fn RegCopyTree(&self, sub_key: Option<&str>, dest: &HKEY) -> SysResult<()>

RegCopyTree function.

pub fn RegCreateKeyEx( &self, sub_key: &str, class: Option<&str>, options: REG_OPTION, access_rights: KEY, security_attributes: Option<&SECURITY_ATTRIBUTES<'_>>, ) -> SysResult<(RegCloseKeyGuard, REG_DISPOSITION)>

RegCreateKeyEx function.

pub fn RegCreateKeyTransacted( &self, sub_key: &str, class: Option<&str>, options: REG_OPTION, access_rights: KEY, security_attributes: Option<&SECURITY_ATTRIBUTES<'_>>, htransaction: &HTRANSACTION, ) -> SysResult<(RegCloseKeyGuard, REG_DISPOSITION)>

RegCreateKeyTransacted function.

pub fn RegDeleteKey(&self, sub_key: &str) -> SysResult<()>

RegDeleteKey function.

pub fn RegDeleteKeyEx(&self, sub_key: &str, platform_view: KEY) -> SysResult<()>

RegDeleteKeyEx function.

Panics

Panics if platform_view is different from co::KEY::WOW64_32KEY and co::KEY::WOW64_64KEY.

pub fn RegDeleteKeyTransacted( &self, sub_key: &str, access_rights: KEY, htransaction: &HTRANSACTION, ) -> SysResult<()>

RegDeleteKeyTransacted function.

pub fn RegDeleteTree(&self, sub_key: Option<&str>) -> SysResult<()>

RegDeleteTree function.

pub fn RegDeleteValue(&self, value_name: Option<&str>) -> SysResult<()>

RegDeleteValue function.

pub fn RegDisableReflectionKey(&self) -> SysResult<()>

RegDisableReflectionKey function.

pub fn RegEnableReflectionKey(&self) -> SysResult<()>

RegEnableReflectionKey function.

pub fn RegEnumKeyEx( &self, ) -> SysResult<impl DoubleEndedIterator<Item = SysResult<String>> + '_>

Returns an iterator over the names of the keys, which calls RegEnumKeyEx repeatedly.

Examples

use winsafe::{self as w, prelude::*, co};

let hkey = w::HKEY::CURRENT_USER.RegOpenKeyEx(
    Some("Control Panel"),
    co::REG_OPTION::default(),
    co::KEY::READ,
)?;

for key_name in hkey.RegEnumKeyEx()? {
    let key_name = key_name?;
    println!("{}", key_name);
}

// Collecting into a Vec
let names: Vec<String> =
    hkey.RegEnumKeyEx()?
        .collect::<w::SysResult<Vec<_>>>()?;

pub fn RegEnumValue( &self, ) -> SysResult<impl DoubleEndedIterator<Item = SysResult<(String, REG)>> + '_>

Returns an iterator of the names and types of the values, which calls RegEnumValue repeatedly.

Examples

use winsafe::{self as w, prelude::*, co};

let hkey = w::HKEY::CURRENT_USER.RegOpenKeyEx(
    Some("Control Panel\\Appearance"),
    co::REG_OPTION::default(),
    co::KEY::READ,
)?;

for value_and_type in hkey.RegEnumValue()? {
    let (value, reg_type) = value_and_type?;
    println!("{}, {}", value, reg_type);
}

// Collecting into a Vec
let values_and_types: Vec<(String, co::REG)> =
    hkey.RegEnumValue()?
        .collect::<w::SysResult<Vec<_>>>()?;

pub fn RegFlushKey(&self) -> SysResult<()>

RegFlushKey function.

pub fn RegGetValue( &self, sub_key: Option<&str>, value_name: Option<&str>, flags: RRF, ) -> SysResult<RegistryValue>

RegGetValue function.

Examples

use winsafe::{self as w, prelude::*, co};

let val = w::HKEY::CURRENT_USER.RegGetValue(
    Some("Control Panel\\Mouse"),
    Some("Beep"),
    co::RRF::RT_ANY,
)?;

println!("{val}");

pub fn RegLoadKey( &self, sub_key: Option<&str>, file_path: &str, ) -> SysResult<()>

RegLoadKey function.

pub fn RegOpenCurrentUser(access_rights: KEY) -> SysResult<RegCloseKeyGuard>

RegOpenCurrentUser function.

pub fn RegOpenKeyEx( &self, sub_key: Option<&str>, options: REG_OPTION, access_rights: KEY, ) -> SysResult<RegCloseKeyGuard>

RegOpenKeyEx function.

Examples

use winsafe::{self as w, prelude::*, co};

let hkey = w::HKEY::CURRENT_USER.RegOpenKeyEx(
    Some("Control Panel\\Mouse"),
    co::REG_OPTION::default(),
    co::KEY::READ,
)?;

pub fn RegOpenKeyTransacted( &self, sub_key: &str, options: REG_OPTION, access_rights: KEY, htransaction: &HTRANSACTION, ) -> SysResult<RegCloseKeyGuard>

RegOpenKeyTransacted function.

pub fn RegQueryInfoKey( &self, class: Option<&mut WString>, num_sub_keys: Option<&mut u32>, max_sub_key_name_len: Option<&mut u32>, max_class_len: Option<&mut u32>, num_values: Option<&mut u32>, max_value_name_len: Option<&mut u32>, max_value_len: Option<&mut u32>, security_descr_len: Option<&mut u32>, last_write_time: Option<&mut FILETIME>, ) -> SysResult<()>

RegQueryInfoKey function.

pub fn RegQueryMultipleValues( &self, value_names: &[impl AsRef<str>], ) -> SysResult<Vec<RegistryValue>>

RegQueryMultipleValues function.

Examples

use winsafe::{self as w, prelude::*, co};

let hkey = w::HKEY::CURRENT_USER.RegOpenKeyEx(
    Some("Control Panel\\Desktop"),
    co::REG_OPTION::default(),
    co::KEY::READ,
)?;

for val in hkey.RegQueryMultipleValues(&["DpiScalingVer", "WallPaper"])? {
    println!("{val}");
}

pub fn RegQueryReflectionKey(&self) -> SysResult<bool>

RegQueryReflectionKey function.

pub fn RegQueryValueEx( &self, value_name: Option<&str>, ) -> SysResult<RegistryValue>

RegQueryValueEx function.

Examples

use winsafe::{self as w, prelude::*, co};

let hkey = w::HKEY::CURRENT_USER.RegOpenKeyEx(
    Some("Control Panel\\Mouse"),
    co::REG_OPTION::default(),
    co::KEY::READ,
)?;

let val = hkey.RegQueryValueEx(Some("Beep"))?;
println!("{val}");

pub fn RegRenameKey( &self, sub_key_name: &str, new_key_name: &str, ) -> SysResult<()>

RegRenameKey function.

pub fn RegReplaceKey( &self, sub_key: Option<&str>, new_src_file: &str, old_file_backup: &str, ) -> SysResult<()>

RegReplaceKey function.

pub fn RegRestoreKey( &self, file_path: &str, flags: REG_RESTORE, ) -> SysResult<()>

RegRestoreKey function.

pub fn RegSaveKey( &self, dest_file_path: &str, security_attributes: Option<&SECURITY_ATTRIBUTES<'_>>, ) -> SysResult<()>

RegSaveKey function.

pub fn RegSaveKeyEx( &self, dest_file_path: &str, security_attributes: Option<&SECURITY_ATTRIBUTES<'_>>, flags: REG_SAVE, ) -> SysResult<()>

RegSaveKeyEx function.

pub fn RegSetKeyValue( &self, sub_key: Option<&str>, value_name: Option<&str>, data: RegistryValue, ) -> SysResult<()>

RegSetKeyValue function.

If the value doesn’t exist, if will be created. If new type is different from current type, new type will take over.

Examples

use winsafe::{self as w, prelude::*};

w::HKEY::CURRENT_USER.RegSetKeyValue(
    Some("Software\\My Company"),
    Some("Color"),
    w::RegistryValue::Sz("blue".to_owned()),
)?;

pub fn RegSetValueEx( &self, value_name: Option<&str>, data: RegistryValue, ) -> SysResult<()>

RegSetValueEx function.

If the value doesn’t exist, if will be created. If new type is different from current type, new type will prevail.

Examples

use winsafe::{self as w, prelude::*, co};

let hkey = w::HKEY::CURRENT_USER.RegOpenKeyEx(
    Some("Console\\Git Bash"),
    co::REG_OPTION::default(),
    co::KEY::ALL_ACCESS,
)?;

hkey.RegSetValueEx(
    Some("Color"),
    w::RegistryValue::Sz("blue".to_owned()),
)?;

pub fn RegUnLoadKey(&self, sub_key: Option<&str>) -> SysResult<()>

RegUnLoadKey function.

Trait Implementations

impl Debug for HKEY

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

Formats the value using the given formatter.

impl Display for HKEY

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

Formats the value using the given formatter.

impl Handle for HKEY

const NULL: Self

Available on crate feature kernel only.

The null, uninitialized handle; equals to 0.

const INVALID: Self

Available on crate feature kernel only.

The invalid handle; equals to -1.

unsafe fn from_ptr(p: *mut c_void) -> Self

Available on crate feature kernel only.

Constructs a new handle object by wrapping a pointer.

unsafe fn raw_copy(&self) -> Self

Available on crate feature kernel only.

Returns a raw copy of the underlying handle pointer.

unsafe fn as_mut(&mut self) -> &mut *mut c_void

Available on crate feature kernel only.

Returns a mutable reference to the underlying raw pointer.

fn ptr(&self) -> *mut c_void

Available on crate feature kernel only.

Returns the underlying raw pointer.

fn as_opt(&self) -> Option<&Self>

Available on crate feature kernel only.

Returns None if the handle is null or invalid, otherwise returns Some(&self).

impl Hash for HKEY

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl LowerHex for HKEY

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

Formats the value using the given formatter.

impl PartialEq for HKEY

fn eq(&self, other: &HKEY) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl UpperHex for HKEY

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

Formats the value using the given formatter.

impl Eq for HKEY

impl Send for HKEY

impl StructuralPartialEq for HKEY