ZwCreateKey 函式（wdm.h）

發行項
12/21/2024

ZwCreateKey 例程會建立新的登錄機碼或開啟現有的登錄機碼。

語法

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

參數

[out] KeyHandle

接收索引鍵句柄的 HANDLE 變數指標。

[in] DesiredAccess

指定 ACCESS_MASK 值，這個值會決定對物件的要求存取權。除了針對所有類型的物件所定義的訪問許可權（請參閱 ACCESS_MASK），呼叫者還可以指定下列一或多個特定物件目錄的訪問許可權：

DesiredAccess 旗標	允許呼叫端執行此動作
KEY_QUERY_VALUE	讀取索引鍵值。
KEY_SET_VALUE	寫入索引鍵值。
KEY_CREATE_SUB_KEY	建立金鑰的子機碼。
KEY_ENUMERATE_SUB_KEYS	讀取金鑰的子機碼。
KEY_CREATE_LINK	建立索引鍵的符號連結。裝置和中繼驅動程式不會使用此旗標。
KEY_NOTIFY	當金鑰的名稱、值或屬性變更時，要求接收通知。如需詳細資訊，請參閱 ZwNotifyChangeKey。

呼叫端也可以指定下列其中一個常數，結合數個ACCESS_MASK旗標。

不斷	由這些ACCESS_MASK旗標所組成
KEY_READ	STANDARD_RIGHTS_READ、KEY_QUERY_VALUE、KEY_ENUMERATE_SUB_KEYS和KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE、KEY_SET_VALUE和KEY_CREATE_SUB_KEY
KEY_EXECUTE	與KEY_READ相同。
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL、KEY_QUERY_VALUE、KEY_SET_VALUE、KEY_CREATE_SUB_KEY、KEY_ENUMERATE_SUB_KEYS、KEY_NOTIFY和KEY_CREATE_LINK

[in] ObjectAttributes

指定物件名稱和其他屬性之 OBJECT_ATTRIBUTES 結構的指標。使用 InitializeObjectAttributes 來初始化這個結構。如果呼叫端未在系統線程內容中執行，則呼叫 InitializeObjectAttributes時，它必須設定OBJ_KERNEL_HANDLE屬性。

TitleIndex

裝置和中繼驅動程式將此參數設定為零。

[in, optional] Class

包含索引鍵物件類別之 Unicode 字串的指標。組態管理員會使用這項資訊。

[in] CreateOptions

指定建立或開啟索引鍵時要套用的選項，指定為下列旗標的兼容組合。

CreateOptions 旗標	描述
REG_OPTION_VOLATILE	重新啟動系統時不會保留金鑰。
REG_OPTION_NON_VOLATILE	重新啟動系統時會保留金鑰。
REG_OPTION_CREATE_LINK	新建立的索引鍵是符號連結。裝置和中繼驅動程式不會使用此旗標。
REG_OPTION_BACKUP_RESTORE	密鑰應以允許備份和還原作業的特殊許可權來建立或開啟。裝置和中繼驅動程式不會使用此旗標。

[out, optional] Disposition

接收值的變數指標，指出是否已建立新的索引鍵或已開啟現有的索引鍵。

處置值	描述
REG_CREATED_NEW_KEY	已建立新的金鑰。
REG_OPENED_EXISTING_KEY	已開啟現有的金鑰。

傳回值

ZwCreateKey 會在成功時傳回STATUS_SUCCESS，或在失敗時傳回適當的 NTSTATUS 錯誤碼。

言論

ZwCreateKey 提供呼叫端可用來操作登錄機碼的句柄。如需詳細資訊，請參閱在驅動程式中使用登錄。

一旦 KeyHandle 所指向的句柄不再使用，驅動程式必須呼叫 ZwClose 關閉它。

有兩種替代方式可指定要建立或開啟的檔名，ZwCreateKey：

作為完整路徑名稱，提供於輸入 ObjectAttributesObjectName 成員中。登入機碼的路徑名稱開頭為 \Registry。
做為相對於另一個登錄機碼的路徑名稱，由輸入 ObjectAttributes中 RootDirectory 成員表示的句柄。

如果 ObjectAttributes 所指定的索引鍵不存在，則例程會嘗試建立索引鍵。若要讓此嘗試成功，新密鑰必須是 RootDirectory所參考之密鑰的直接子機碼，而且 RootDirectory 所參考的密鑰必須已開啟KEY_CREATE_SUB_KEY存取。

如果指定的索引鍵已經存在，則會開啟，而且其值不會以任何方式受到影響。

建立索引鍵時，ObjectAttributes 所指定的安全性屬性會 判斷指定的 DesiredAccess 是否會在後續 呼叫 ZwCreateKey 和 ZwOpenKey時授與。

如果呼叫端未在系統線程內容中執行，則必須確保所建立的任何句柄都是私人句柄。否則，進程可以存取其內容中的驅動程序執行句柄。如需詳細資訊，請參閱物件句柄。

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

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

Windows 核心中的 NtCreateKey 例程無法直接存取內核模式驅動程式。

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

要求

要求	價值
目標平臺	普遍
標頭	wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h）
連結庫	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIS（storport），IrqlZwPassive（wdm），PowerIrpDDis（wdm），ZwRegistryCreate（storport），ZwRegistryCreate（storport），ZwRegistryCreate（wdm），ZwRegistryOpen（wdm）