ntCreateTransaction 函式 (wdm.h)

發行項
02/27/2024

ZwCreateTransaction 例程會建立交易物件。

語法

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

參數

[out] TransactionHandle

如果 呼叫 ZwCreateTransaction 成功，則為呼叫端配置變數的指標，該變數會接收新交易物件的句柄。

[in] DesiredAccess

ACCESS_MASK值，指定呼叫端對交易物件的要求存取權。除了針對所有類型的物件定義的訪問許可權之外， (請參閱 ACCESS_MASK) ，呼叫端還可以指定下列任何一個交易對象的旗標。

存取遮罩	允許呼叫端
TRANSACTION_COMMIT	認可交易 (請參閱 ZwCommitTransaction) 。
TRANSACTION_ENLIST	建立交易的登記 (請參閱 ZwCreateEnlistment) 。
TRANSACTION_PROPAGATE	請勿使用。
TRANSACTION_QUERY_INFORMATION	取得交易 (的相關信息，請參閱 ZwQueryInformationTransaction) 。
TRANSACTION_ROLLBACK	回復交易 (請參閱 ZwRollbackTransaction) 。
TRANSACTION_SET_INFORMATION	設定交易的資訊 (請參閱 ZwSetInformationTransaction) 。

或者，您可以指定下列一或多個ACCESS_MASK位圖。這些點陣圖會將上表中的旗標與STANDARD_RIGHTS_XXX 旗標結合，這些旗標會在 ACCESS_MASK 參考頁面上描述。您也可以將這些點陣圖與上表中的其他旗標結合。下表顯示位圖如何對應至特定訪問許可權。

許可權位圖	特定訪問許可權集
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ、TRANSACTION_QUERY_INFORMATION和 SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE、TRANSACTION_SET_INFORMATION、TRANSACTION_COMMIT、TRANSACTION_ENLIST、TRANSACTION_ROLLBACK、TRANSACTION_PROPAGATE、TRANSACTION_SAVEPOINT和 SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE、TRANSACTION_COMMIT、TRANSACTION_ROLLBACK和 SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED、TRANSACTION_GENERIC_READ、TRANSACTION_GENERIC_WRITE和TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE、TRANSACTION_GENERIC_READ、TRANSACTION_SET_INFORMATION、TRANSACTION_ENLIST、TRANSACTION_ROLLBACK、TRANSACTION_PROPAGATE和 SYNCHRONIZE

一般而言，資源管理員會指定TRANSACTION_RESOURCE_MANAGER_RIGHTS。

DesiredAccess 值不能為零。

[in, optional] ObjectAttributes

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

[in, optional] Uow

KTM 用來作為新交易物件工作單位的 GUID 指標， (UOW) 識別符。這個參數是選擇性的，而且可以是 NULL。如果此參數為 NULL，KTM 會產生 GUID，並將它指派給交易物件。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in, optional] TmHandle

先前呼叫 ZwCreateTransactionManager 或 ZwOpenTransactionManager 取得的交易管理員物件的句柄。 KTM 會將新的交易物件指派給指定的交易管理員物件。如果此參數為 NULL，KTM 會在資源管理員建立交易的登記時，將新的交易物件指派給交易管理員。

[in, optional] CreateOptions

選擇性物件建立旗標。下表包含 Ktmtypes.h 中定義的可用旗標。

選項旗標	意義
TRANSACTION_DO_NOT_PROMOTE	保留供未來使用。

[in, optional] IsolationLevel

保留供未來使用。呼叫端必須將此參數設定為零。

[in, optional] IsolationFlags

保留供未來使用。呼叫端應該將此參數設定為零。

[in, optional] Timeout

逾時值的指標。如果這個參數所指定的時間尚未認可交易，KTM 會回復交易。逾時值是以系統時間單位表示， (100 奈秒的間隔) ，而且可以指定絕對時間或相對時間。如果 Timeout 所指向的值是負數，則到期時間會相對於目前的系統時間。否則，到期時間是絕對的。此指標是選擇性的，如果您不想讓交易具有逾時值，則可以是 NULL 。如果 Timeout = NULL 或 *Timeout = 0，交易永遠不會逾時。 (您也可以使用 ZwSetInformationTransaction 來設定逾時值。)

[in, optional] Description

呼叫端提供的 UNICODE_STRING 結構的指標，其中包含NULL終止的字串。字串提供交易的描述。 KTM 會儲存字串的複本，並將字串包含在寫入記錄數據流的訊息中。字串長度上限為 MAX_TRANSACTION_DESCRIPTION_LENGTH。這個參數是選擇性的，而且可以是 NULL。

傳回值

如果作業成功，ZwCreateTransaction 會傳回STATUS_SUCCESS。否則，此例程可能會傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	CreateOptions 參數包含無效的旗標、DesiredAccess 參數為零，或 Description 參數的字串太長。
STATUS_INSUFFICIENT_RESOURCES	KTM 通常無法 (記憶體) 配置系統資源。
STATUS_INVALID_ACL	安全性描述項包含無效的訪問控制清單， (ACL) 。
STATUS_INVALID_SID	安全性描述元包含無效的安全性標識碼 (SID) 。
STATUS_OBJECT_NAME_EXISTS	ObjectAttributes 參數指定的物件名稱已經存在。
STATUS_OBJECT_NAME_INVALID	ObjectAttributes 參數指定的物件名稱無效。
STATUS_ACCESS_DENIED	DesiredAccess 參數的值無效。

例程可能會傳回其他 NTSTATUS值。

備註

呼叫端可以使用 Uow 參數來指定交易物件的UOW標識碼。如果呼叫端未指定 UOW 識別符，KTM 會產生 GUID 並將它指派給交易物件。呼叫端稍後可以藉由呼叫 ZwQueryInformationTransaction 來取得此 GUID。

一般而言，除非您的元件與已經為交易產生UOW標識碼的另一個TPS元件通訊，否則您應該讓KTM產生交易物件的 GUID。

若要關閉交易句柄，呼叫 ZwCreateTransaction 的元件必須呼叫 ZwClose。如果最後一個交易句柄會在任何元件呼叫交易的 ZwCommitTransaction 之前關閉，KTM 會回復交易。

如需交易用戶端如何使用 ZwCreateTransaction 的詳細資訊，請參閱建立交易式用戶端。

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

規格需求

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