ZwCreateKey 函式 (wdm.h)

發行項
02/29/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 旗標	Description
REG_OPTION_VOLATILE	重新啟動系統時，不會保留金鑰。
REG_OPTION_NON_VOLATILE	重新啟動系統時，會保留金鑰。
REG_OPTION_CREATE_LINK	新建立的索引鍵是符號連結。裝置和中繼驅動程式不會使用此旗標。
REG_OPTION_BACKUP_RESTORE	密鑰應以允許備份和還原作業的特殊許可權來建立或開啟。裝置和中繼驅動程式不會使用此旗標。

[out, optional] Disposition

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

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

傳回值

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

備註

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

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

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

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

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

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

當建立密鑰時，ObjectAttributes 所指定的安全性屬性會決定是否在後續呼叫 ZwCreateKey 和 ZwOpenKey 時授與指定的 DesiredAccess。

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

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

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

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

對於核心模式驅動程式的呼叫，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 (wdm)