ZwOpenKeyTransactedEx 函式 (wdm.h)

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

語法

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

參數

[out] KeyHandle

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

[in] DesiredAccess

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

[in] ObjectAttributes

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

[in] OpenOptions

指定開啟索引鍵時要套用的選項。 將此參數設定為零,或設定為下列一或多個 REG_OPTION_XXX 旗標位的位 OR。

OpenOptions 旗標 Description
REG_OPTION_OPEN_LINK 索引鍵是符號連結。 裝置和中繼驅動程式不會使用此旗標。
REG_OPTION_BACKUP_RESTORE 密鑰應以允許備份和還原作業的特殊許可權開啟。 裝置和中繼驅動程式不會使用此旗標。

[in] TransactionHandle

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

傳回值

如果呼叫成功開啟密鑰,ZwOpenKeyTransactedEx 會傳回STATUS_SUCCESS。 可能的錯誤傳回值包括下列各項:

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

備註

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

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

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

ZwOpenKeyEx 例程類似於 ZwOpenKeyTransactedEx,但不會將密鑰與交易產生關聯。

ZwOpenKeyTransacted 例程類似於 ZwOpenKeyTransactedEx,但不接受 OpenOptions 參數。 ZwOpenKeyTransactedExOpenOptions 參數可讓呼叫端開啟符號連結的密鑰,或開啟用於備份和還原作業的密鑰。 呼叫 ZwOpenKeyTransactedEx 並將 OpenOptions 參數設定為零相當於對 ZwOpenKeyTransacted 的呼叫。

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

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

在交易期間,如果執行作業的系統呼叫符合下列任一條件,登錄作業就會是交易的一部分:

  • 呼叫會將交易句柄指定為輸入參數。 例如,呼叫 ZwCreateKeyTransactedZwOpenKeyTransactedEx 可以將一或多個密鑰與交易產生關聯。
  • 呼叫會指定做為輸入參數的登錄機碼句柄,該句柄是由對 ZwCreateKeyTransactedZwOpenKeyTransactedEx 的呼叫所取得。 例如,對 ZwSetValueKey 例程的呼叫可以使用以這種方式取得的機碼句柄,將登錄機碼的值設定為交易的一部分。
如需核心模式交易的詳細資訊,請參閱 使用核心交易管理員

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

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

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

規格需求

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

另請參閱

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ObOpenObjectByPointer

ZwClose

ZwCommitTransaction

ZwCreateKey

ZwCreateKeyTransacted

ZwCreateTransaction

ZwOpenKeyEx

ZwOpenKeyTransacted

ZwRollbackTransaction

ZwSetValueKey