`CRegKey` 类

项目
04/03/2023

此类提供用于操作系统注册表中的条目的方法。

重要

无法在 Windows 运行时中执行的应用程序中使用此类及其成员。

语法

class CRegKey

成员

公共构造函数

名称	描述
`CRegKey::CRegKey`	构造函数。
`CRegKey::~CRegKey`	析构函数。

公共方法

名称	描述
`CRegKey::Attach`	通过将 `m_hKey` 成员句柄设置为 `hKey` 调用此方法，以将 HKEY 附加到 `CRegKey` 对象。
`CRegKey::Close`	调用此方法可释放 `m_hKey` 成员句柄并将其设置为 `NULL`。
`CRegKey::Create`	如果指定的项不作为 `hKeyParent` 的子项存在，可调用此方法来创建该项。
`CRegKey::DeleteSubKey`	调用此方法可从注册表中删除指定的项。
`CRegKey::DeleteValue`	调用此方法可从 `m_hKey` 中删除值字段。
`CRegKey::Detach`	调用此方法可将 `m_hKey` 成员句柄与 `CRegKey` 对象分离并将 `m_hKey` 设置为 `NULL`。
`CRegKey::EnumKey`	调用此方法可枚举打开的注册表项的子项。
`CRegKey::Flush`	调用此方法可将打开的注册表项的所有属性写入注册表。
`CRegKey::GetKeySecurity`	调用此方法可检索用于保护打开的注册表项的安全描述符的副本。
`CRegKey::NotifyChangeKeyValue`	此方法通知调用方有关打开的注册表项的属性或内容的更改。
`CRegKey::Open`	调用此方法可打开指定的项并将 `m_hKey` 设置为此项的句柄。
`CRegKey::QueryBinaryValue`	调用此方法可检索指定值名称的二进制数据。
`CRegKey::QueryDWORDValue`	调用此方法可检索指定值名称的 `DWORD` 数据。
`CRegKey::QueryGUIDValue`	调用此方法可检索指定值名称的 GUID 数据。
`CRegKey::QueryMultiStringValue`	调用此方法可检索指定值名称的多字符串数据。
`CRegKey::QueryQWORDValue`	调用此方法可检索指定值名称的 `QWORD` 数据。
`CRegKey::QueryStringValue`	调用此方法可检索指定值名称的字符串数据。
`CRegKey::QueryValue`	调用此方法可检索 `m_hKey` 的指定值字段的数据。此方法的早期版本不再受支持，已标记为 `ATL_DEPRECATED`。
`CRegKey::RecurseDeleteKey`	调用此方法可从注册表中删除指定的项并显式删除任何子项。
`CRegKey::SetBinaryValue`	调用此方法可设置注册表项的二进制值。
`CRegKey::SetDWORDValue`	调用此方法可设置注册表项的 `DWORD` 值。
`CRegKey::SetGUIDValue`	调用此方法可设置注册表项的 GUID 值。
`CRegKey::SetKeySecurity`	调用此方法可设置注册表项的安全性。
`CRegKey::SetKeyValue`	调用此方法可将数据存储在指定项的指定值字段中。
`CRegKey::SetMultiStringValue`	调用此方法可设置注册表项的多字符串值。
`CRegKey::SetQWORDValue`	调用此方法可设置注册表项的 `QWORD` 值。
`CRegKey::SetStringValue`	调用此方法可设置注册表项的字符串值。
`CRegKey::SetValue`	调用此方法可将数据存储在 `m_hKey` 的指定值字段中。此方法的早期版本不再受支持，已标记为 `ATL_DEPRECATED`。

公共运算符

“属性”	描述
`CRegKey::operator HKEY`	将 `CRegKey` 对象转换为 `HKEY`。
`CRegKey::operator =`	赋值运算符。

公共数据成员

“属性”	描述
`CRegKey::m_hKey`	包含与 `CRegKey` 对象关联的注册表项的句柄。
`CRegKey::m_pTM`	指向 `CAtlTransactionManager` 对象的指针

备注

CRegKey 提供用于在系统注册表中创建和删除项与值的方法。注册表包含一组特定于安装的系统组件定义，例如软件版本号、安装的硬件的逻辑到物理映射，以及 COM 对象。

CRegKey 提供给定计算机的系统注册表的编程接口。例如，若要打开特定的注册表项，请调用 CRegKey::Open。若要检索或修改数据值，请分别调用 CRegKey::QueryValue 或 CRegKey::SetValue。若要关闭项，请调用 CRegKey::Close。

关闭某个项时，其注册表数据将写入（刷新）到硬盘中。该过程需要持续数秒。如果应用程序必须将注册表数据显式写入硬盘，你可以调用 RegFlushKey Win32 函数。但是，RegFlushKey 会占用许多系统资源，因此请仅在绝对必要时才调用它。

重要

任何允许调用方指定注册表位置的方法都有可能读取不受信任的数据。使用 RegQueryValueEx 的方法应考虑到此函数不会显式处理以 null 结尾的字符串。调用代码应检查这两种情况。

要求

标头atlbase.h：

`CRegKey::Attach`

通过将 m_hKey 成员句柄设置为 hKey 调用此方法，以将 HKEY 附加到 CRegKey 对象。

void Attach(HKEY hKey) throw();

参数

hKey
注册表项的句柄。

注解

Attach 将断言 m_hKey 是否不为 NULL。

`CRegKey::Close`

调用此方法可释放 m_hKey 成员句柄并将其设置为 NULL。

LONG Close() throw();

返回值

如果成功，则返回 ERROR_SUCCESS；否则返回错误值。

`CRegKey::Create`

如果指定的项不作为 hKeyParent 的子项存在，可调用此方法来创建该项。

LONG Create(
    HKEY hKeyParent,
    LPCTSTR lpszKeyName,
    LPTSTR lpszClass = REG_NONE,
    DWORD dwOptions = REG_OPTION_NON_VOLATILE,
    REGSAM samDesired = KEY_READ | KEY_WRITE,
    LPSECURITY_ATTRIBUTES lpSecAttr = NULL,
    LPDWORD lpdwDisposition = NULL) throw();

参数

hKeyParent
打开的项的句柄。

lpszKeyName
指定要创建或打开的项的名称。此名称必须是 hKeyParent 的子项。

lpszClass
指定要创建或打开的项的类。默认值为 REG_NONE。

dwOptions
项的选项。默认值为 REG_OPTION_NON_VOLATILE。有关可能值的列表及其说明，请参阅 Windows SDK 中的 RegCreateKeyEx。

samDesired
项的安全访问权限。默认值为 KEY_READ | KEY_WRITE。有关可能值的列表及其说明，请参阅 RegCreateKeyEx。

lpSecAttr
指向 SECURITY_ATTRIBUTES 结构的指针，指示项的句柄是否可由子进程继承。默认情况下，此参数为 NULL（表示句柄不能继承）。

lpdwDisposition
[out] 如果不为 NULL，则检索 REG_CREATED_NEW_KEY（如果项不存在并已创建）或 REG_OPENED_EXISTING_KEY（如果项存在并已打开）。

返回值

如果成功，则返回 ERROR_SUCCESS 并打开项。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

注解

Create 将 m_hKey 成员设置为此项的句柄。

`CRegKey::CRegKey`

构造函数。

CRegKey() throw();
CRegKey(CRegKey& key) throw();
explicit CRegKey(HKEY hKey) throw();
CRegKey(CAtlTransactionManager* pTM) throw();

参数

key
对 CRegKey 对象的引用。

hKey
注册表项的句柄。

pTM
指向 CAtlTransactionManager 对象的指针

备注

创建新的 CRegKey 对象。可以从现有的 CRegKey 对象，或者从注册表项的句柄创建该对象。

`CRegKey::~CRegKey`

析构函数。

~CRegKey() throw();

备注

析构函数释放 m_hKey。

`CRegKey::DeleteSubKey`

调用此方法可从注册表中删除指定的项。

LONG DeleteSubKey(LPCTSTR lpszSubKey) throw();

参数

lpszSubKey
指定要删除的项的名称。此名称必须是 m_hKey 的子项。

返回值

如果成功，则返回 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

DeleteSubKey 只能删除没有子项的项。如果该项有子项，请改为调用 RecurseDeleteKey。

`CRegKey::DeleteValue`

调用此方法可从 m_hKey 中删除值字段。

LONG DeleteValue(LPCTSTR lpszValue) throw();

参数

lpszValue
指定要删除的值字段。

返回值

如果成功，则返回 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

`CRegKey::Detach`

调用此方法可将 m_hKey 成员句柄与 CRegKey 对象分离并将 m_hKey 设置为 NULL。

HKEY Detach() throw();

返回值

与 CRegKey 对象关联的 HKEY。

`CRegKey::EnumKey`

调用此方法可枚举打开的注册表项的子项。

LONG EnumKey(
    DWORD iIndex,
    LPTSTR pszName,
    LPDWORD pnNameLength,
    FILETIME* pftLastWriteTime = NULL) throw();

参数

iIndex
子项索引。首次调用时此参数应为零，后续调用时将会递增

pszName
指向接收子项名称的缓冲区的指针，包括结尾的 null 字符。只会将子项名称复制到缓冲区，而不会复制完整的项层次结构。

pnNameLength
指向变量的指针，该变量指定 pszName 参数指定的缓冲区的大小（以 TCHARs 为单位）。此大小应包括结尾的 null 字符。该方法返回时，pnNameLength 指向的变量包含缓冲区中存储的字符数。返回的计数不包括结尾的 null 字符。

pftLastWriteTime
指向变量的指针，该变量接收上次写入枚举子项的时间。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

若要枚举子项，请使用零索引调用 CRegKey::EnumKey。递增索引值并重复，直到该方法返回 ERROR_NO_MORE_ITEMS。有关详细信息，请参阅 Windows SDK 中的 RegEnumKeyEx。

`CRegKey::Flush`

调用此方法可将打开的注册表项的所有属性写入注册表。

LONG Flush() throw();

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

有关详细信息，请参阅 Windows SDK 中的 RegEnumFlush。

`CRegKey::GetKeySecurity`

调用此方法可检索用于保护打开的注册表项的安全描述符的副本。

LONG GetKeySecurity(
    SECURITY_INFORMATION si,
    PSECURITY_DESCRIPTOR psd,
    LPDWORD pnBytes) throw();

参数

si
指示请求的安全信息的 SECURITY_INFORMATION 值。

psd
指向缓冲区的指针，该缓冲区接收请求的安全描述符的副本。

pnBytes
psd 指向的缓冲区的大小（以字节为单位）。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

有关详细信息，请参阅 RegGetKeySecurity。

`CRegKey::m_hKey`

包含与 CRegKey 对象关联的注册表项的句柄。

HKEY m_hKey;

`CRegKey::m_pTM`

指向 CAtlTransactionManager 对象的指针。

CAtlTransactionManager* m_pTM;

备注

`CRegKey::NotifyChangeKeyValue`

此方法通知调用方有关打开的注册表项的属性或内容的更改。

LONG NotifyChangeKeyValue(
    BOOL bWatchSubtree,
    DWORD dwNotifyFilter,
    HANDLE hEvent,
    BOOL bAsync = TRUE) throw();

参数

bWatchSubtree
指定一个标志，用于指示是要报告指定项及其所有子项的更改，还是仅报告指定项的更改。如果此参数为 TRUE，则该方法将报告项及其子项的更改。如果参数为 FALSE，则该方法仅报告项的更改。

dwNotifyFilter
指定一组标志来控制应报告哪些更改。此参数可为以下值的组合：

值	含义
`REG_NOTIFY_CHANGE_NAME`	通知调用方是添加还是删除了子项。
`REG_NOTIFY_CHANGE_ATTRIBUTES`	向调用方通知项属性（例如安全描述符信息）的更改。
`REG_NOTIFY_CHANGE_LAST_SET`	向调用方通知项值的更改。这包括添加或删除值，或更改现有值。
`REG_NOTIFY_CHANGE_SECURITY`	向调用方通知项的安全描述符的更改。

hEvent
事件的句柄。如果 bAsync 参数为 TRUE，则该方法会立即返回，并通过发出此事件的信号来报告更改。如果 bAsync 为 FALSE，则忽略 hEvent。

bAsync
指定一个用于指示该方法如何报告更改的标志。如果此参数为 TRUE，则该方法会立即返回，并通过发出指定事件的信号来报告更改。如果此参数为 FALSE，则该方法在发生更改之前不会返回。如果 hEvent 未指定有效事件，则 bAsync 参数不能是 TRUE。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

注意

如果删除了指定的项，此方法不会通知调用方。

有关更多详细信息和示例程序，请参阅 RegNotifyChangeKeyValue。

`CRegKey::Open`

调用此方法可打开指定的项并将 m_hKey 设置为此项的句柄。

LONG Open(
    HKEY hKeyParent,
    LPCTSTR lpszKeyName,
    REGSAM samDesired = KEY_READ | KEY_WRITE) throw();

参数

hKeyParent
打开的项的句柄。

lpszKeyName
指定要创建或打开的项的名称。此名称必须是 hKeyParent 的子项。

samDesired
项的安全访问权限。默认值是 KEY_ALL_ACCESS。有关可能值的列表及其说明，请参阅 Windows SDK 中的 RegCreateKeyEx。

返回值

如果成功，则返回 ERROR_SUCCESS；否则返回 WINERROR.H 中定义的非零错误值。

备注

如果 lpszKeyName 参数为 NULL 或指向空字符串，则 Open 会打开由 hKeyParent 标识的项的新句柄，但不会关闭任何先前已打开的句柄。

与 CRegKey::Create 不同，如果指定的项不存在，Open 不会创建该项。

`CRegKey::operator HKEY`

将 CRegKey 对象转换为 HKEY。

operator HKEY() const throw();

`CRegKey::operator =`

赋值运算符。

CRegKey& operator= (CRegKey& key) throw();

参数

key
要复制的项。

返回值

返回对新项的引用。

注解

此运算符将 key 与其当前对象分离，并将其分配到 CRegKey 对象。

`CRegKey::QueryBinaryValue`

调用此方法可检索指定值名称的二进制数据。

LONG QueryBinaryValue(
    LPCTSTR pszValueName,
    void* pValue,
    ULONG* pnBytes) throw();

参数

pszValueName
指向以 NULL 结尾的字符串的指针，该字符串包含要查询的值的名称。

pValue
指向接收值数据的缓冲区的指针。

pnBytes
指向变量的指针，该变量指定 pValue 参数指向的缓冲区的大小（以字节为单位）。当方法返回时，此变量包含复制到缓冲区的数据的大小。

返回值

如果该方法成功，则返回 ERROR_SUCCESS。如果该方法无法读取值，则返回 WINERROR.H 中定义的非零错误代码。如果引用的数据的类型不是 REG_BINARY，则返回 ERROR_INVALID_DATA。

备注

此方法利用 RegQueryValueEx 并确认返回的数据类型是否正确。有关更多详细信息，请参阅RegQueryValueEx。

重要

此方法允许调用方指定任何注册表位置，可能会读取不受信任的数据。此外，此方法使用的 RegQueryValueEx 函数不会显式处理以 null 结尾的字符串。调用代码应检查这两种情况。

`CRegKey::QueryDWORDValue`

调用此方法可检索指定值名称的 DWORD 数据。

LONG QueryDWORDValue(
    LPCTSTR pszValueName,
    DWORD& dwValue) throw();

参数

pszValueName
指向以 NULL 结尾的字符串的指针，该字符串包含要查询的值的名称。

dwValue
指向接收 DWORD 的缓冲区的指针。

返回值

如果该方法成功，则返回 ERROR_SUCCESS。如果该方法无法读取值，则返回 WINERROR.H 中定义的非零错误代码。如果引用的数据的类型不是 REG_DWORD，则返回 ERROR_INVALID_DATA。

备注

此方法利用 RegQueryValueEx 并确认返回的数据类型是否正确。有关更多详细信息，请参阅RegQueryValueEx。

重要

`CRegKey::QueryGUIDValue`

调用此方法可检索指定值名称的 GUID 数据。

LONG QueryGUIDValue(
    LPCTSTR pszValueName,
    GUID& guidValue) throw();

参数

pszValueName
指向以 NULL 结尾的字符串的指针，该字符串包含要查询的值的名称。

guidValue
指向接收 GUID 的变量的指针。

返回值

如果该方法成功，则返回 ERROR_SUCCESS。如果该方法无法读取值，则返回 WINERROR.H 中定义的非零错误代码。如果引用的数据不是有效 GUID，则返回 ERROR_INVALID_DATA。

注解

此方法利用 CRegKey::QueryStringValue 并使用 CLSIDFromString 将字符串转换为 GUID。

重要

此方法允许调用方指定任何注册表位置，可能会读取不受信任的数据。

`CRegKey::QueryMultiStringValue`

调用此方法可检索指定值名称的多字符串数据。

LONG QueryMultiStringValue(
    LPCTSTR pszValueName,
    LPTSTR pszValue,
    ULONG* pnChars) throw();

参数

pszValueName
指向以 NULL 结尾的字符串的指针，该字符串包含要查询的值的名称。

pszValue
指向接收多字符串数据的缓冲区的指针。多字符串是以 NULL 结尾的字符串数组，以两个 null 字符结尾。

pnChars
pszValue 指向的缓冲区的大小（以 TCHARs 为单位）。当方法返回时，pnChars 包含检索到的多字符串的大小（以 TCHARs 为单位），该大小包括结尾的 null 字符。

返回值

如果该方法成功，则返回 ERROR_SUCCESS。如果该方法无法读取值，则返回 WINERROR.H 中定义的非零错误代码。如果引用的数据的类型不是 REG_MULTI_SZ，则返回 ERROR_INVALID_DATA。

注解

此方法利用 RegQueryValueEx 并确认返回的数据类型是否正确。有关更多详细信息，请参阅RegQueryValueEx。

重要

`CRegKey::QueryQWORDValue`

调用此方法可检索指定值名称的 QWORD 数据。

LONG QueryQWORDValue(
    LPCTSTR pszValueName,
    ULONGLONG& qwValue) throw();

参数

pszValueName
指向以 NULL 结尾的字符串的指针，该字符串包含要查询的值的名称。

qwValue
指向接收 QWORD 的缓冲区的指针。

返回值

如果该方法成功，则返回 ERROR_SUCCESS。如果该方法无法读取值，则返回 WINERROR.H 中定义的非零错误代码。如果引用的数据的类型不是 REG_QWORD，则返回 ERROR_INVALID_DATA。

注解

此方法利用 RegQueryValueEx 并确认返回的数据类型是否正确。有关更多详细信息，请参阅RegQueryValueEx。

重要

`CRegKey::QueryStringValue`

调用此方法可检索指定值名称的字符串数据。

LONG QueryStringValue(
    LPCTSTR pszValueName,
    LPTSTR pszValue,
    ULONG* pnChars) throw();

参数

pszValueName
指向以 NULL 结尾的字符串的指针，该字符串包含要查询的值的名称。

pszValue
指向接收字符串数据的缓冲区的指针。

pnChars
pszValue 指向的缓冲区的大小（以 TCHARs 为单位）。当方法返回时，pnChars 包含检索到的字符串的大小（以 TCHARs 为单位），该大小包括结尾的 null 字符。

返回值

如果该方法成功，则返回 ERROR_SUCCESS。如果该方法无法读取值，则返回 WINERROR.H 中定义的非零错误代码。如果引用的数据的类型不是 REG_SZ，则返回 ERROR_INVALID_DATA。如果该方法返回 ERROR_MORE_DATA，则 pnChars 等于 0，而不是所需的缓冲区大小（以字节为单位）。

注解

此方法利用 RegQueryValueEx 并确认返回的数据类型是否正确。有关更多详细信息，请参阅RegQueryValueEx。

重要

`CRegKey::QueryValue`

调用此方法可检索 m_hKey 的指定值字段的数据。此方法的早期版本不再受支持，已标记为 ATL_DEPRECATED。

LONG QueryValue(
    LPCTSTR pszValueName,
    DWORD* pdwType,
    void* pData,
    ULONG* pnBytes) throw();

ATL_DEPRECATED LONG QueryValue(
    DWORD& dwValue,
    LPCTSTR lpszValueName);

ATL_DEPRECATED LONG QueryValue(
    LPTSTR szValue,
    LPCTSTR lpszValueName,
    DWORD* pdwCount);

参数

pszValueName
指向以 NULL 结尾的字符串的指针，该字符串包含要查询的值的名称。如果 pszValueName 为 NULL 或空字符串 ""，则该方法将检索项的未命名值或默认值（如果有）的类型和数据。

pdwType
指向变量的指针，该变量接收一个指示存储在指定值中的数据类型的代码。如果不需要类型代码，pdwType 参数可以是 NULL。

pData
指向接收值数据的缓冲区的指针。如果不需要数据，此参数可以是 NULL。

pnBytes
指向变量的指针，该变量指定 pData 参数指向的缓冲区的大小（以字节为单位）。当方法返回时，此变量包含复制到 pData 的数据的大小。

dwValue
值字段的数值数据。

lpszValueName
指定要查询的值字段。

szValue
值字段的字符串数据。

pdwCount
字符串数据的大小。其值最初设置为 szValue 缓冲区的大小。

返回值

如果成功，则返回 ERROR_SUCCESS；否则返回 WINERROR.H 中定义的非零错误代码。

备注

QueryValue 的两个原始版本不再受支持，已标记为 ATL_DEPRECATED。如果使用这些形式，编译器将发出警告。

其余方法调用 RegQueryValueEx。

重要

`CRegKey::RecurseDeleteKey`

调用此方法可从注册表中删除指定的项并显式删除任何子项。

LONG RecurseDeleteKey(LPCTSTR lpszKey) throw();

参数

lpszKey
指定要删除的项的名称。此名称必须是 m_hKey 的子项。

返回值

如果成功，则返回 ERROR_SUCCESS；否则返回 WINERROR.H 中定义的非零错误值。

注解

如果项有子项，则必须调用此方法删除该项。

`CRegKey::SetBinaryValue`

调用此方法可设置注册表项的二进制值。

LONG SetBinaryValue(
    LPCTSTR pszValueName,
    const void* pValue,
    ULONG nBytes) throw();

参数

pszValueName
指向字符串的指针，该字符串包含要设置的值的名称。如果尚不存在具有此名称的值，该方法会将该值添加到项。

pValue
指向缓冲区的指针，该缓冲区包含要用指定的值名称存储的数据。

nBytes
指定 pValue 参数指向的信息的大小（以字节为单位）。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

此方法使用 RegSetValueEx 将值写入注册表。

`CRegKey::SetDWORDValue`

调用此方法可设置注册表项的 DWORD 值。

LONG SetDWORDValue(LPCTSTR pszValueName, DWORD dwValue) throw();

参数

pszValueName
指向字符串的指针，该字符串包含要设置的值的名称。如果尚不存在具有此名称的值，该方法会将该值添加到项。

dwValue
要用指定的值名称存储的 DWORD 数据。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

此方法使用 RegSetValueEx 将值写入注册表。

`CRegKey::SetGUIDValue`

调用此方法可设置注册表项的 GUID 值。

LONG SetGUIDValue(LPCTSTR pszValueName, REFGUID guidValue) throw();

参数

pszValueName
指向字符串的指针，该字符串包含要设置的值的名称。如果尚不存在具有此名称的值，该方法会将该值添加到项。

guidValue
对要用指定的值名称存储的 GUID 的引用。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

此方法利用 CRegKey::SetStringValue 并使用 StringFromGUID2 将 GUID 转换为字符串。

`CRegKey::SetKeyValue`

调用此方法可将数据存储在指定项的指定值字段中。

LONG SetKeyValue(
    LPCTSTR lpszKeyName,
    LPCTSTR lpszValue,
    LPCTSTR lpszValueName = NULL) throw();

参数

lpszKeyName
指定要创建或打开的项的名称。此名称必须是 m_hKey 的子项。

lpszValue
指定要存储的数据。此参数不能为 NULL。

lpszValueName
指定要设置的值字段。如果项中尚不存在具有此名称的值字段，则会添加该字段。

返回值

如果成功，则返回 ERROR_SUCCESS；否则返回 WINERROR.H 中定义的非零错误代码。

备注

调用此方法可创建或打开 lpszKeyName 项，并将 lpszValue 数据存储在 lpszValueName 值字段中。

`CRegKey::SetKeySecurity`

调用此方法可设置注册表项的安全性。

LONG SetKeySecurity(SECURITY_INFORMATION si, PSECURITY_DESCRIPTOR psd) throw();

参数

si
指定要设置的安全描述符的组成部分。该值可为以下值的组合：

值	含义
`DACL_SECURITY_INFORMATION`	设置项的自由访问控制列表 (DACL)。该项必须拥有 `WRITE_DAC` 访问权限，或者调用进程必须是对象的所有者。
`GROUP_SECURITY_INFORMATION`	设置项的主要组安全标识符 (SID)。该项必须拥有 `WRITE_OWNER` 访问权限，或者调用进程必须是对象的所有者。
`OWNER_SECURITY_INFORMATION`	设置项的所有者 SID。该项必须拥有 `WRITE_OWNER` 访问权限，或者调用进程必须是对象的所有者或启用了 `SE_TAKE_OWNERSHIP_NAME` 特权。
`SACL_SECURITY_INFORMATION`	设置项的系统访问控制列表 (SACL)。该项必须拥有 `ACCESS_SYSTEM_SECURITY` 访问权限。获取此访问权限的正确方法是在调用方的当前访问令牌中启用 `SE_SECURITY_NAME` 特权，打开 `ACCESS_SYSTEM_SECURITY` 访问权限的句柄，然后禁用特权。

psd
指向 SECURITY_DESCRIPTOR 结构的指针，该结构指定要为指定的项设置的安全属性。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

注解

设置项的安全属性。有关更多详细信息，请参阅RegSetKeySecurity。

`CRegKey::SetMultiStringValue`

调用此方法可设置注册表项的多字符串值。

LONG SetMultiStringValue(LPCTSTR pszValueName, LPCTSTR pszValue) throw();

参数

pszValueName
指向字符串的指针，该字符串包含要设置的值的名称。如果尚不存在具有此名称的值，该方法会将该值添加到项。

pszValue
指向要用指定的值名称存储的多字符串数据的指针。多字符串是以 NULL 结尾的字符串数组，以两个 null 字符结尾。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

此方法使用 RegSetValueEx 将值写入注册表。

`CRegKey::SetQWORDValue`

调用此方法可设置注册表项的 QWORD 值。

LONG SetQWORDValue(LPCTSTR pszValueName, ULONGLONG qwValue) throw();

参数

pszValueName
指向字符串的指针，该字符串包含要设置的值的名称。如果尚不存在具有此名称的值，该方法会将该值添加到项。

qwValue
要用指定的值名称存储的 QWORD 数据。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

备注

此方法使用 RegSetValueEx 将值写入注册表。

`CRegKey::SetStringValue`

调用此方法可设置注册表项的字符串值。

LONG SetStringValue(
    LPCTSTR pszValueName,
    LPCTSTR pszValue,
    DWORD dwType = REG_SZ) throw();

参数

pszValueName
指向字符串的指针，该字符串包含要设置的值的名称。如果尚不存在具有此名称的值，该方法会将该值添加到项。

pszValue
指向要用指定的值名称存储的字符串数据的指针。

dwType
要写入注册表的字符串的类型：REG_SZ（默认）或 REG_EXPAND_SZ（用于多字符串）。

返回值

如果该方法成功，则返回值为 ERROR_SUCCESS。如果该方法失败，则返回值为 WINERROR.H 中定义的非零错误代码。

注解

此方法使用 RegSetValueEx 将值写入注册表。

`CRegKey::SetValue`

调用此方法可将数据存储在 m_hKey 的指定值字段中。此方法的早期版本不再受支持，已标记为 ATL_DEPRECATED。

LONG SetValue(
    LPCTSTR pszValueName,
    DWORD dwType,
    const void* pValue,
    ULONG nBytes) throw();

static LONG WINAPI SetValue(
    HKEY hKeyParent,
    LPCTSTR lpszKeyName,
    LPCTSTR lpszValue,
    LPCTSTR lpszValueName = NULL);

ATL_DEPRECATED LONG SetValue(
    DWORD dwValue,
    LPCTSTR lpszValueName);

ATL_DEPRECATED LONG SetValue(
    LPCTSTR lpszValue,
    LPCTSTR lpszValueName = NULL,
    bool bMulti = false,
    int nValueLen = -1);

参数

pszValueName
指向字符串的指针，该字符串包含要设置的值的名称。如果项中尚不存在具有此名称的值，该方法会将该值添加到项。如果 pszValueName 为 NULL 或空字符串 ""，则该方法将设置项的未命名值或默认值的类型和数据。

dwType
指定一个代码用于指示 pValue 参数指向的数据的类型。

pValue
指向缓冲区的指针，该缓冲区包含要用指定的值名称存储的数据。

nBytes
指定 pValue 参数指向的信息的大小（以字节为单位）。如果数据的类型为 REG_SZ、REG_EXPAND_SZ 或 REG_MULTI_SZ，则 nBytes 必须包含结尾 null 字符的大小。

hKeyParent
打开的项的句柄。

lpszKeyName
指定要创建或打开的项的名称。此名称必须是 hKeyParent 的子项。

lpszValue
指定要存储的数据。此参数不能为 NULL。

lpszValueName
指定要设置的值字段。如果项中尚不存在具有此名称的值字段，则会添加该字段。

dwValue
指定要存储的数据。

bMulti
如果为 false，则表示字符串的类型为 REG_SZ。如果为 true，则表示字符串是 REG_MULTI_SZ 类型的多字符串。

nValueLen
如果 bMulti 为 true，则 nValueLen 是 lpszValue 字符串的长度（以字符为单位）。如果 bMulti 为 false，则值 -1 表示该方法将自动计算长度。

返回值

如果成功，则返回 ERROR_SUCCESS；否则返回 WINERROR.H 中定义的非零错误代码。

备注

SetValue 的两个原始版本已标记为 ATL_DEPRECATED，不再可用。如果使用这些形式，编译器将发出警告。

第三个方法调用 RegSetValueEx。

另请参阅

DCOM 示例
 类概述

CRegKey 类

语法

成员

公共构造函数

公共方法

公共运算符

公共数据成员

备注

要求

CRegKey::Attach

参数

注解

CRegKey::Close

返回值

CRegKey::Create

参数

返回值

注解

CRegKey::CRegKey

参数

备注

CRegKey::~CRegKey

备注

CRegKey::DeleteSubKey

参数

返回值

备注

CRegKey::DeleteValue

参数

返回值

CRegKey::Detach

返回值

CRegKey::EnumKey

参数

返回值

备注

CRegKey::Flush

返回值

备注

CRegKey::GetKeySecurity

参数

返回值

备注

CRegKey::m_hKey

CRegKey::m_pTM

备注

CRegKey::NotifyChangeKeyValue

参数

返回值

备注

CRegKey::Open

参数

返回值

备注

CRegKey::operator HKEY

CRegKey::operator =

参数

返回值

注解

CRegKey::QueryBinaryValue

参数

返回值

备注

CRegKey::QueryDWORDValue

参数

返回值

备注

CRegKey::QueryGUIDValue

参数

返回值

注解

CRegKey::QueryMultiStringValue

参数

返回值

注解

CRegKey::QueryQWORDValue

参数

返回值

注解

CRegKey::QueryStringValue

`CRegKey` 类

`CRegKey::Attach`

`CRegKey::Close`

`CRegKey::Create`

`CRegKey::CRegKey`

`CRegKey::~CRegKey`

`CRegKey::DeleteSubKey`

`CRegKey::DeleteValue`

`CRegKey::Detach`

`CRegKey::EnumKey`

`CRegKey::Flush`

`CRegKey::GetKeySecurity`

`CRegKey::m_hKey`

`CRegKey::m_pTM`

`CRegKey::NotifyChangeKeyValue`

`CRegKey::Open`

`CRegKey::operator HKEY`

`CRegKey::operator =`

`CRegKey::QueryBinaryValue`

`CRegKey::QueryDWORDValue`

`CRegKey::QueryGUIDValue`

`CRegKey::QueryMultiStringValue`

`CRegKey::QueryQWORDValue`

`CRegKey::QueryStringValue`

`CRegKey::QueryValue`

`CRegKey::RecurseDeleteKey`

`CRegKey::SetBinaryValue`

`CRegKey::SetDWORDValue`

`CRegKey::SetGUIDValue`

`CRegKey::SetKeyValue`

`CRegKey::SetKeySecurity`

`CRegKey::SetMultiStringValue`

`CRegKey::SetQWORDValue`

`CRegKey::SetStringValue`

`CRegKey::SetValue`