ZwCreateTransaction 関数 (wdm.h)

  • [アーティクル]

ZwCreateTransaction ルーチンはトランザクション オブジェクトを作成します。

構文

NTSYSCALLAPI NTSTATUS ZwCreateTransaction(
  [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 バージョン間の関係の詳細については、「Using Nt and Zw Versions of the Native System Services Routines」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows Vista 以降のオペレーティング システム バージョンで使用できます。
対象プラットフォーム ユニバーサル
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

こちらもご覧ください

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

UNICODE_STRING

Nt および Zw バージョンのネイティブ システム サービス ルーチンの使用

ZwClose

ZwCommitTransaction

ZwCreateEnlistment

ZwCreateTransactionManager

ZwOpenTransaction

ZwOpenTransactionManager

ZwQueryInformationTransaction

ZwRollbackTransaction

ZwSetInformationTransaction