win_wrap/
registry.rs

1/*
2 * Copyright (c) 2024. The RigelA open source project team and
3 * its contributors reserve all rights.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software distributed under the
10 * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 * See the License for the specific language governing permissions and limitations under the License.
12 */
13
14use crate::common::Result;
15pub use windows::Win32::System::Registry::{
16    HKEY, HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER,
17    HKEY_CURRENT_USER_LOCAL_SETTINGS, HKEY_DYN_DATA, HKEY_LOCAL_MACHINE, HKEY_PERFORMANCE_DATA,
18    HKEY_PERFORMANCE_NLSTEXT, HKEY_PERFORMANCE_TEXT, HKEY_USERS, KEY_ALL_ACCESS, KEY_CREATE_LINK,
19    KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_EXECUTE, KEY_NOTIFY, KEY_QUERY_VALUE, KEY_READ,
20    KEY_SET_VALUE, KEY_WOW64_32KEY, KEY_WOW64_64KEY, KEY_WOW64_RES, KEY_WRITE, REG_EXPAND_SZ,
21    REG_MULTI_SZ, REG_NONE, REG_SAM_FLAGS, REG_SZ, REG_VALUE_TYPE,
22};
23use windows::{
24    core::HSTRING,
25    Win32::System::Registry::{RegCloseKey, RegDeleteValueW, RegOpenKeyExW, RegSetValueExW},
26};
27
28//noinspection SpellCheckingInspection
29/**
30打开指定的注册表项。 请注意，键名称不区分大小写。
31若要对密钥执行事务注册表操作，请调用 reg_open_key_transacted 函数。
32与 reg_create_key_ex 函数不同，如果注册表中不存在指定键， reg_open_key_ex 函数不会创建指定键。
33某些注册表操作对密钥的安全描述符（而不是获取密钥句柄时指定的访问掩码）执行访问检查。 例如，即使某个项以KEY_READ的 sam_desire 打开，也可用于创建注册表项（如果密钥的安全描述符允许）。 相比之下， reg_set_value_ex 函数专门要求使用KEY_SET_VALUE访问权限打开密钥。
34如果服务或应用程序模拟不同的用户，请不要将此函数与 HKEY_CURRENT_USER一起使用。 请改为调用 reg_open_current_user 函数。
35请注意，将重定向访问某些注册表项的操作。 有关详细信息，请参阅 注册表虚拟化 和 注册表中的 32 位和 64 位应用程序数据。
36`h_key` 打开的注册表项的句柄。 此句柄由 reg_create_key_ex 或 reg_open_key_ex 函数返回，也可以是以下 预定义键之一：
37- HKEY_CLASSES_ROOT
38- HKEY_CURRENT_CONFIG
39- HKEY_CURRENT_USER
40- HKEY_LOCAL_MACHINE
41- HKEY_USERS
42`sub_key` 要打开的注册表子项的名称。键名称不区分大小写。如果 sub_key 参数为 NULL 或指向空字符串的指针，并且 h_key 是预定义键，则系统会刷新预定义的键，并且 result 接收传递到函数中的同一 h_key 句柄。 否则， result 将接收打开的密钥的新句柄。有关详细信息，请参阅 注册表元素大小限制。
43`options` 指定要在打开密钥时应用的选项。 将此参数设置为零或以下参数：
44- REG_OPTION_OPEN_LINK 键是符号链接。 仅当绝对必要时才应使用注册表符号链接。
45`sam_desired` 一个掩码，指定要打开的密钥的所需访问权限。 如果密钥的安全描述符不允许对调用进程进行请求的访问，则函数将失败。 有关详细信息，请参阅 注册表项安全和访问权限。
46*/
47pub fn reg_open_key_ex(
48    h_key: HKEY,
49    sub_key: Option<&str>,
50    options: Option<u32>,
51    sam_desired: REG_SAM_FLAGS,
52) -> HKEY {
53    unsafe {
54        let mut res = std::mem::zeroed();
55        if match sub_key {
56            None => RegOpenKeyExW(h_key, None, options, sam_desired, &mut res),
57            Some(key) => RegOpenKeyExW(h_key, &HSTRING::from(key), options, sam_desired, &mut res),
58        }
59        .is_ok()
60        {
61            return res;
62        }
63        HKEY::default()
64    }
65}
66
67//noinspection SpellCheckingInspection
68/**
69设置注册表项下指定值的数据和类型。
70值大小受可用内存的限制。 但是，在注册表中存储较大的值可能会影响其性能。 (超过 2，048 字节的长值) 应存储为文件，文件的位置存储在注册表中。
71应用程序元素（如图标、位图和可执行文件）应存储为文件，而不是放置在注册表中。
72如果 type 是REG_SZ、REG_MULTI_SZ或REG_EXPAND_SZ类型，并且此函数的 ANSI 版本通过显式调用 reg_set_value_ex 或未在将 Windows.h 文件) 之前未定义 UNICODE 来 (使用，则 data 参数指向的数据必须是 ANSI 字符串。 字符串在存储到注册表中之前会转换为 Unicode。
73请注意，将重定向访问某些注册表项的操作。 有关详细信息，请参阅 注册表虚拟化 和 注册表中的 32 位和 64 位应用程序数据。
74请考虑使用 reg_set_key_value 函数，该函数提供了一种更方便的方式来设置注册表项的值。
75`h_key` 打开的注册表项的句柄。 Key 必须已使用KEY_SET_VALUE访问权限打开。 有关详细信息，请参阅 注册表项安全和访问权限。此句柄由 reg_create_key_ex、 reg_create_key_transacted、 reg_open_key_ex 或 reg_open_key_transacted 函数返回。 也可以是以下 预定义键之一：
76- HKEY_CLASSES_ROOT
77- HKEY_CURRENT_CONFIG
78- HKEY_CURRENT_USER
79- HKEY_LOCAL_MACHINE
80- HKEY_USERS
81- HKEY_PERFORMANCE_TEXT
82- HKEY_PERFORMANCE_NLSTEXT
83`value_name` 要设置的值的名称。 如果键中尚不存在具有此名称的值，则函数会将其添加到键中。如果 value_name 为 NULL 或空字符串“”，则该函数将设置键的未命名值或默认值的类型和数据。有关详细信息，请参阅 注册表元素大小限制。注册表项没有默认值，但它们可以有一个未命名的值，该值可以是任何类型的。
84`reserved` 此参数是保留的，必须为零。
85`type` data 参数指向的数据类型。
86`data` 要存储的数据。对于基于字符串的类型（如 REG_SZ），字符串必须以 null 结尾。 对于 REG_MULTI_SZ 数据类型，字符串必须以两个 null 字符结尾。
87*/
88pub fn reg_set_value_ex(
89    h_key: HKEY,
90    value_name: Option<&str>,
91    reserved: Option<u32>,
92    r#type: REG_VALUE_TYPE,
93    data: Option<&[u8]>,
94) -> Result<()> {
95    unsafe {
96        match value_name {
97            None => RegSetValueExW(h_key, None, reserved, r#type, data),
98            Some(name) => RegSetValueExW(h_key, &HSTRING::from(name), reserved, r#type, data),
99        }
100    }
101    .ok()
102}
103
104//noinspection SpellCheckingInspection
105/**
106从指定的注册表项中删除命名值。请注意，值名称不区分大小写。
107`h_key` 打开的注册表项的句柄。Key 必须已使用KEY_SET_VALUE访问权限打开。有关详细信息，请参阅注册表项安全性和访问权限。此句柄由 reg_create_key_ex、reg_create_key_transacted、reg_open_key_ex 或 reg_open_key_transacted 函数返回。它也可以是以下预定义键之一：
108- HKEY_CLASSES_ROOT
109- HKEY_CURRENT_CONFIG
110- HKEY_CURRENT_USER
111- HKEY_LOCAL_MACHINE
112- HKEY_USERS
113`value_name` 要删除的注册表值。如果此参数为 NULL 或空字符串，则删除 RegSetValue 函数设置的值。有关更多信息，请参见注册表元素大小限制。
114*/
115pub fn reg_delete_value(h_key: HKEY, value_name: Option<&str>) -> Result<()> {
116    unsafe {
117        match value_name {
118            None => RegDeleteValueW(h_key, None),
119            Some(name) => RegDeleteValueW(h_key, &HSTRING::from(name)),
120        }
121    }
122    .ok()
123}
124
125/**
126关闭指定注册表项的句柄。
127指定键的句柄在关闭后不应使用，因为它将不再有效。 键句柄的打开时间不应超过必要时间。
128reg_close_key 函数在返回之前不一定将信息写入注册表;缓存刷新到硬盘可能需要几秒钟的时间。 如果应用程序必须将注册表信息显式写入硬盘，则可以使用 reg_flush_key 函数。 但是，reg_flush_key 使用许多系统资源，仅在必要时才应调用。
129`h_key` 要关闭的打开键的句柄。 该句柄必须已由 reg_create_key_ex、reg_create_key_transacted、reg_open_key_ex、reg_open_key_transacted 或 reg_connect_registry 函数打开。
130*/
131pub fn reg_close_key(h_key: HKEY) -> bool {
132    unsafe { RegCloseKey(h_key) }.is_ok()
133}
win_wrap/registry.rs

win_wrap/
registry.rs
