ZwSetValueKey 函式 (wdm.h)

發行項
02/27/2024

ZwSetValueKey 例程會建立或取代登錄機碼的值專案。

語法

NTSYSAPI NTSTATUS ZwSetValueKey(
  [in]           HANDLE          KeyHandle,
  [in]           PUNICODE_STRING ValueName,
  [in, optional] ULONG           TitleIndex,
  [in]           ULONG           Type,
  [in, optional] PVOID           Data,
  [in]           ULONG           DataSize
);

參數

[in] KeyHandle

要寫入值項目的登錄機碼句柄。此句柄是由成功呼叫 ZwCreateKey 或 ZwOpenKey 所建立。

[in] ValueName

要寫入數據之值項目名稱的指標。如果值項目沒有名稱，這個參數可以是 NULL 指標。如果指定名稱字串，且指定的名稱與其包含索引鍵不是唯一的，則會取代現有值項目的數據。

[in, optional] TitleIndex

此參數已保留備用。裝置和中繼驅動程序應該將此參數設定為零。

[in] Type

要寫入的下列其中一種系統定義資料類型：

類型值	意義
REG_BINARY	任何形式的二進位資料，
REG_DWORD	4 位元組的數值。
REG_DWORD_LITTLE_ENDIAN	在最低位址具有最小有效位元組的4位元組數值。與REG_DWORD相同。
REG_DWORD_BIG_ENDIAN	在最高位址具有最小有效位元組的4位元組數值。
REG_EXPAND_SZ	Null 終止的 Unicode 字串，其中包含環境變數的未展開參考，例如「%PATH%」。
REG_LINK	命名符號連結的 Unicode 字串。此類型與裝置和中繼驅動程序無關。
REG_MULTI_SZ	以 Null 終止字串的陣列，由另一個零終止。
REG_NONE	沒有特定類型的數據。
REG_SZ	以 Null 結尾的 Unicode 字串。
REG_RESOURCE_LIST	在 \ResourceMap 樹狀結構中，驅動程式所使用的硬體資源清單，或驅動程式所控制之其中一個實體裝置的硬體資源清單
REG_RESOURCE_REQUIREMENTS_LIST	裝置驅動程式的可能硬體資源清單，或其控制可使用的其中一個實體裝置，系統會將子集寫入 \ResourceMap 樹狀結構
REG_FULL_RESOURCE_DESCRIPTOR	系統使用實體裝置、偵測到並寫入 \HardwareDescription 樹狀結構的硬體資源清單

設備驅動器不應該嘗試呼叫 ZwSetValueKey ，在 \Registry...\ResourceMap 機碼的子機碼中明確寫入值專案。只有系統可以將值專案寫入 至 \Registry...\HardwareDescription 樹狀結構。

[in, optional] Data

呼叫端配置的緩衝區指標，其中包含值項目的數據。

[in] DataSize

指定數據緩衝區的大小，以位元組為單位。如果 Type REG_XXX_SZ，此值必須包含任何終止零的空間。

傳回值

如果作業成功，ZwSetValueKey 會傳回STATUS_SUCCESS。否則，此例程可能會傳回下列其中一個值：

傳回碼	Description
STATUS_ACCESS_DENIED	呼叫端沒有登錄值的適當存取權。
STATUS_INVALID_HANDLE	控制代碼無效。

備註

傳遞至 ZwSetValueKey 的 KeyHandle 必須已開啟，且此呼叫設定為成功的KEY_SET_VALUE DesiredAccess 旗標。如需 DesiredAccess 可能值的描述，請參閱 ZwCreateKey。

如果指定的索引鍵沒有名稱符合指定 ValueName 的現有值專案， ZwSetValueKey 會建立具有指定名稱的新值專案。如果存在相符的值項目名稱，此例程會覆寫指定 ValueName 的原始值專案。因此， ZwSetValueKey 會保留任何特定索引鍵之每個值專案的唯一名稱。雖然每個值專案名稱都必須是唯一的，但登錄中的許多不同索引鍵可以有具有相同名稱的值專案。

如需使用登錄機碼的詳細資訊，請參閱在驅動程式中使用登錄。

如果呼叫此函式發生在使用者模式中，您應該使用名稱「NtSetValueKey」而不是「ZwSetValueKey」。

對於核心模式驅動程式的呼叫，Windows 原生系統服務例程的 NtXxx 和 ZwXxx 版本在處理和解譯輸入參數的方式可能會有不同的行為。如需例程 NtXxx 和 ZwXxx 版本之間的關聯性詳細資訊，請參閱使用 Nt 和 Zw 版本的原生系統服務例程。

規格需求

需求	值
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 IrqlZwPassive (wdm ) 、 PowerIrpDDis (wdm) 、 ZwRegistryCreate (storport) 、ZwRegistryCreate (storport) 、 ZwRegistryCreate (wdm) 、 ZwRegistryOpen (storport) 、 ZwRegistryOpen (storport ) 、 ZwRegistryOpen (wdm)