ZwSetValueKey 函式 (wdm.h)
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) |