ZwEnumerateTransactionObject 関数 (wdm.h)

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

ZwEnumerateTransactionObject ルーチンは、コンピューター上の KTM オブジェクトを列挙します。

構文

NTSYSCALLAPI NTSTATUS ZwEnumerateTransactionObject(
  [in, optional] HANDLE            RootObjectHandle,
  [in]           KTMOBJECT_TYPE    QueryType,
  [in, out]      PKTMOBJECT_CURSOR ObjectCursor,
  [in]           ULONG             ObjectCursorLength,
  [out]          PULONG            ReturnLength
);

パラメーター

[in, optional] RootObjectHandle

KTM オブジェクトへのハンドル。ルーチンは、指定したオブジェクトの子オブジェクトを列挙します。このパラメーターは省略可能であり、 NULL にすることができます。このパラメーターの有効な値の詳細については、次の「解説」セクションの表を参照してください。

[in] QueryType

列挙するオブジェクトの種類を識別するKTMOBJECT_TYPE型指定の値。このパラメーターの有効な値の詳細については、次の「解説」セクションの表を参照してください。

[in, out] ObjectCursor

KTMOBJECT_CURSOR構造体で始まる呼び出し元によって割り当てられたバッファーへのポインター。 ZwEnumerateTransactionObject は、バッファーを使用して、検出されたオブジェクトの GUID を格納します。

[in] ObjectCursorLength

ObjectCursor が指すバッファーの長さ (バイト単位)。

[out] ReturnLength

ZwEnumerateTransactionObject が ObjectCursor バッファーで返すバイト数を受け取る呼び出し元によって割り当てられた場所へのポインター。これには、KTMOBJECT_CURSOR構造体の長さと、返されるすべての GUID の長さが含まれます。

戻り値

ZwEnumerateTransactionObject は、操作が成功したが、ルーチンがすべてのオブジェクトを列挙していない場合、STATUS_SUCCESSを返します。列挙するオブジェクトがこれ以上ない場合、ルーチンはSTATUS_NO_MORE_ENTRIESを返します。それ以外の場合、このルーチンは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	QueryType または ObjectCursorLength パラメーターの値が無効です。
STATUS_OBJECT_TYPE_MISMATCH	RootObjectHandle パラメーターが指定するハンドルは、有効な KTM オブジェクトへのハンドルではありません。
STATUS_INVALID_HANDLE	オブジェクトハンドルが無効です。
STATUS_ACCESS_DENIED	呼び出し元は、列挙されているオブジェクトに適切なアクセス権を持っていません。

ルーチンは、他の NTSTATUS 値を返す場合があります。

注釈

次の表に、 RootObjectHandle パラメーターと QueryType パラメーターの有効な値を示します。

QueryType パラメーター	RootObjectHandle パラメーター	列挙されたオブジェクト
KTMOBJECT_TRANSACTION_MANAGER	NULL	すべてのトランザクションマネージャーオブジェクト
KTMOBJECT_RESOURCE_MANAGER	トランザクションマネージャーオブジェクトへのハンドル。ハンドルには、オブジェクトへのTRANSACTIONMANAGER_QUERY_INFORMATIONアクセス権が必要です。	指定されたトランザクション・マネージャー・オブジェクトに属するすべてのリソース・マネージャー・オブジェクト
KTMOBJECT_ENLISTMENT	リソースマネージャーオブジェクトへのハンドル。ハンドルには、オブジェクトへのRESOURCEMANAGER_QUERY_INFORMATIONアクセス権が必要です。	指定したリソースマネージャーオブジェクトに属するすべての参加オブジェクト
KTMOBJECT_TRANSACTION	トランザクションマネージャーオブジェクトへのハンドル。ハンドルには、オブジェクトへのTRANSACTIONMANAGER_QUERY_INFORMATIONアクセス権が必要です。	指定されたトランザクションマネージャーオブジェクトに属するすべてのトランザクションオブジェクト
KTMOBJECT_TRANSACTION	NULL	すべてのトランザクションマネージャーオブジェクトに属するすべてのトランザクションオブジェクト

ほとんどの TPS コンポーネントは ZwEnumerateTransactionObject を呼び出す必要はありませんが、デバッグユーティリティを記述する必要がある場合はルーチンが役立つ場合があります。

コンポーネントが ZwEnumerateTransactionObject を呼び出す前に、 ObjectCursor が指すバッファーを割り当ててゼロにする必要があります。バッファーの GUID 配列は、1 つ以上の要素を受け取るのに十分な大きさにすることができます。

指定した型のすべての KTM オブジェクトを列挙するには、コンポーネントが STATUS_NO_MORE_ENTRIESを返すまで 、ZwEnumerateTransactionObject を 繰り返し呼び出す必要があります。

ルーチンが呼び出されるたびに、バッファーの GUID 配列に収まるオブジェクト GUID が格納されます。各呼び出しの後、コンポーネントは、KTMOBJECT_CURSOR 構造体の ObjectIdCount メンバーを使用して、ルーチンが配列に格納したオブジェクト GUID の数を決定できます。

NtEnumerateTransactionObject と ZwEnumerateTransactionObject は、同じ Windows ネイティブシステムサービスルーチンの 2 つのバージョンです。

カーネルモードドライバーからの呼び出しの場合、Windows ネイティブシステムサービスルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なります。 ルーチンの NtXxx バージョンと ZwXxx バージョン間の関係の詳細については、「Using Nt and Zw Versions of the Native System Services Routines」を参照してください。

例

次のコード例は、コンピューター上のすべてのトランザクションオブジェクトを列挙する方法を示しています。この例では、 KTMOBJECT_CURSOR 構造体の GUID 配列には要素が 1 つだけ含まれているため、 ZwEnumerateTransactionObject の各呼び出しは 1 つの GUID を返します。ルーチンは、GUID から Unicode 文字列を作成し、その文字列を表示します。

NTSTATUS Status;
UNICODE_STRING GuidString;
KTMOBJECT_CURSOR Cursor;
ULONG ReturnedBytes;

RtlZeroMemory(&Cursor, sizeof(Cursor));

do {
    Status = ZwEnumerateTransactionObject(
                                          NULL,
                                          KTMOBJECT_TRANSACTION,
                                          &Cursor,
                                          sizeof(Cursor),
                                          &ReturnedBytes
                                          );

    if (Status != STATUS_NO_MORE_ENTRIES) {
        RtlStringFromGUID(
                          &Cursor.ObjectIds[0],
                          &GuidString
                          );
        OutputMessage(GuidString.Buffer);
        OutputMessage(L"\r\n");
        RtlFreeUnicodeString(&GuidString);
    }
} while (Status == STATUS_SUCCESS);
if (Status == STATUS_NO_MORE_ENTRIES) {
    Status = STATUS_SUCCESS;
}

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

こちらもご覧ください

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

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

次の方法で共有

ZwEnumerateTransactionObject 関数 (wdm.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース