ZwOpenKeyTransacted 函式 (wdm.h)

發行項
02/29/2024

ZwOpenKeyTransacted 例程會開啟現有的登錄機碼，並將密鑰與交易產生關聯。

語法

NTSYSAPI NTSTATUS ZwOpenKeyTransacted(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  HANDLE             TransactionHandle
);

參數

[out] KeyHandle

HANDLE 變數的指標，例程會將句柄寫入索引鍵。

[in] DesiredAccess

指定呼叫端要求之金鑰的存取類型。此參數是 ACCESS_MASK 值。如需詳細資訊，請參閱 ZwCreateKey 例程的 DesiredAccess 參數描述。

[in] ObjectAttributes

要開啟之索引鍵之物件屬性的指標。這個參數會指向先前必須由 InitializeObjectAttributes 例程初始化的OBJECT_ATTRIBUTES結構。呼叫端必須將登錄機碼的名稱指定為 InitializeObjectAttributes 呼叫中的 ObjectName 參數。如果呼叫端未在系統線程內容中執行，它必須在呼叫 InitializeObjectAttributes 時設定OBJ_KERNEL_HANDLE屬性。

[in] TransactionHandle

交易物件的句柄。若要取得此句柄，您可以呼叫 ZwCreateTransaction 例程。或者，如果您有交易物件的指標，則可以提供 ObOpenObjectByPointer 例程的指標，以取得對應的交易句柄。

傳回值

如果呼叫成功開啟密鑰，ZwOpenKeyTransacted 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括：

傳回碼	Description
STATUS_INVALID_PARAMETER	ObjectAttributes 參數為 NULL 或指向無效的資訊。
STATUS_OBJECT_PATH_SYNTAX_BAD	物件屬性中的登錄路徑無效。
STATUS_OBJECT_NAME_NOT_FOUND	找不到物件屬性中的登錄路徑。
STATUS_ACCESS_DENIED	呼叫端沒有開啟具名登錄機碼句柄的必要訪問許可權。
STATUS_INSUFFICIENT_RESOURCES	記憶體配置作業失敗。

備註

這個例程提供呼叫端可以存取登錄機碼的句柄。此外，此例程會將密鑰與作用中交易產生關聯。

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

如果登錄中沒有指定的機碼， ZwOpenKeyTransacted 會傳回錯誤狀態值，而且不提供密鑰句柄。不同於 ZwCreateKeyTransacted 例程，如果索引鍵不存在， ZwOpenKeyTransacted 例程就不會建立指定的索引鍵。 ZwCreateKeyTransacted 和 ZwOpenKeyTransacted 都會將登錄機碼與交易產生關聯。

ZwOpenKey 例程類似於 ZwOpenKeyTransacted，但不會將密鑰與交易產生關聯。

例如，在內核模式驅動程式透過呼叫 ZwCreateTransaction) ，取得交易 (句柄之後，驅動程式就可以執行屬於此交易的一系列登錄作業。驅動程式可以認可交易中所做的變更，或復原交易來關閉交易。

驅動程式成功完成屬於交易一部分的所有登錄作業之後，就可以呼叫 ZwCommitTransaction 例程來認可變更。驅動程式可以呼叫 ZwRollbackTransaction 例程來回復交易。

在交易期間，如果執行作業的系統呼叫符合下列其中一個條件，登錄作業就是交易的一部分：

呼叫會將交易句柄指定為輸入參數。例如，呼叫 ZwCreateKeyTransacted 和 ZwOpenKeyTransacted 可以將一或多個密鑰與交易產生關聯。
呼叫會指定做為輸入參數的登錄機碼句柄，該句柄是由呼叫 ZwCreateKeyTransacted 或提供交易句柄的 ZwOpenKeyTransacted 所取得。例如，對 ZwSetValueKey 例程的呼叫可以使用以這種方式取得的機碼句柄，將登錄機碼的值設定為交易的一部分。

如需核心模式交易的詳細資訊，請參閱使用核心交易管理員。

ZwOpenKeyTransacted 會忽略 ObjectAttributes 參數指向之結構中的安全性資訊。

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

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

規格需求

需求	值
最低支援的用戶端	可在 Windows Vista 和更新版本的 Windows 作業系統中使用。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIS (storport) 、 PowerIrpDDis (wdm)