NtCreateTransaction 関数 (wdm.h)

[アーティクル]
03/14/2023

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ビットマップの 1 つ以上を指定することもできます。これらのビットマップは、前の表のフラグと、ACCESS_MASK参照ページで説明されているSTANDARD_RIGHTS_XXX フラグを組み合わせます。これらのビットマップを、前の表の追加フラグと組み合わせることもできます。次の表は、ビットマップが特定のアクセス権にどのように対応するかを示しています。

権限ビットマップ	特定のアクセス権のセット
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 値を 0 にすることはできません。

[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

将来使用するために予約されています。呼び出し元は、このパラメーターを 0 に設定する必要があります。

[in, optional] IsolationFlags

将来利用するために予約されています。呼び出し元は、このパラメーターを 0 に設定する必要があります。

[in, optional] Timeout

タイムアウト値へのポインター。このパラメーターで指定された時間までにトランザクションがコミットされていない場合、KTM はトランザクションをロールバックします。タイムアウト値はシステム時間単位 (100 ナノ秒間隔) で表され、絶対時間または相対時間のいずれかを指定できます。 Timeout が指す値が負の場合、有効期限は現在のシステム時刻に対して相対的になります。それ以外の場合、有効期限は絶対です。このポインターは省略可能であり、トランザクションにタイムアウト値を設定しない場合は NULL にすることができます。 Timeout = NULL または *Timeout = 0 の場合、トランザクションはタイムアウトしません。(ZwSetInformationTransaction を使用してタイムアウト値を設定することもできます)。

[in, optional] Description

NULL で終わる文字列を含む呼び出し元が指定した UNICODE_STRING 構造体へのポインター。文字列は、トランザクションの説明を提供します。 KTM は文字列のコピーを格納し、ログストリームに書き込むメッセージに文字列を含めます。文字列の最大長はMAX_TRANSACTION_DESCRIPTION_LENGTH。このパラメーターは省略可能であり、 NULL にすることができます。

戻り値

操作が成功した場合、ZwCreateTransaction はSTATUS_SUCCESSを返します。それ以外の場合、このルーチンは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	CreateOptions パラメーターに無効なフラグが含まれているか、DesiredAccess パラメーターが 0 であるか、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 以降のオペレーティングシステムバージョンで使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs、PowerIrpDDis