共用方式為

NtCreateTransaction 函式 （wdm.h）

  • 發行項

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 參考頁面上描述。 您也可以將這些點陣圖與上表的其他旗標結合。 下表顯示位圖如何對應至特定訪問許可權。

Rights bitmap 一組特定的訪問許可權
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 用來做為新交易物件工作單位 （UOW） 識別碼 之 GUID 的指標。 這個參數是選擇性的，而且可以 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。 如果 逾時 = NULL 或 *逾時 = 0，則交易永遠不會逾時。（您也可以使用 ZwSetInformationTransaction 來設定逾時值。

[in, optional] Description

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

傳回值

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

傳回碼 描述
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的詳細資訊，請參閱 建立交易式用戶端。

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

要求

要求 價值
最低支援的用戶端 適用於 Windows Vista 和更新版本的作系統版本。
目標平臺 普遍
標頭 wdm.h （包括 Wdm.h、Ntddk.h、Ntifs.h）
連結庫 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDDIs， PowerIrpDDis

另請參閱

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

UNICODE_STRING

使用 Nt 和 Zw 版本的原生系統服務例程

ZwClose

ZwCommitTransaction

ZwCreateEnlistment

ZwCreateTransactionManager

ZwOpenTransaction

ZwOpenTransactionManager

ZwQueryInformationTransaction

ZwRollbackTransaction

ZwSetInformationTransaction