NtEnumerateTransactionObject-Funktion (wdm.h)

Artikel
02/07/2025

Die ZwEnumerateTransactionObject Routine listet die KTM-Objekte auf einem Computer auf.

Syntax

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

Parameter

[in, optional] RootObjectHandle

Ein Handle zu einem KTM-Objekt. Die Routine listet die untergeordneten Objekte des angegebenen Objekts auf. Dieser Parameter ist optional und kann NULL-werden. Weitere Informationen zu gültigen Werten für diesen Parameter finden Sie in der Tabelle im folgenden Abschnitt "Hinweise".

[in] QueryType

Ein KTMOBJECT_TYPE-typed-Wert, der den zu aufzählden Objekttyp identifiziert. Weitere Informationen zu gültigen Werten für diesen Parameter finden Sie in der Tabelle im folgenden Abschnitt "Hinweise".

[in, out] ObjectCursor

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der mit einer KTMOBJECT_CURSOR Struktur beginnt. ZwEnumerateTransactionObject verwendet den Puffer, um die GUIDs der gefundenen Objekte zu speichern.

[in] ObjectCursorLength

Die Länge des Puffers in Byte, auf den ObjectCursor verweist.

[out] ReturnLength

Ein Zeiger auf einen vom Aufrufer zugewiesenen Speicherort, der die Anzahl der Bytes empfängt, die ZwEnumerateTransactionObject im ObjectCursor- Puffer zurückgibt, einschließlich der Länge der KTMOBJECT_CURSOR Struktur und der Länge aller zurückgegebenen GUIDs.

Rückgabewert

ZwEnumerateTransactionObject gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist, die Routine jedoch nicht alle Objekte aufgezählt hat. Wenn es keine weiteren Objekte gibt, die aufgezählt werden sollen, gibt die Routine STATUS_NO_MORE_ENTRIES zurück. Andernfalls gibt diese Routine möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Der Wert des QueryType oder ObjectCursorLength Parameter ist ungültig.
STATUS_OBJECT_TYPE_MISMATCH	Das Handle, das der RootObjectHandle--Parameter angibt, ist kein Handle für ein gültiges KTM-Objekt.
STATUS_INVALID_HANDLE	Ein Objekthandle ist ungültig.
STATUS_ACCESS_DENIED	Der Aufrufer hat keinen geeigneten Zugriff auf die Objekte, die aufgezählt werden.

Die Routine gibt möglicherweise andere NTSTATUS-Wertezurück.

Bemerkungen

Die folgende Tabelle enthält die gültigen Werte für die parameter RootObjectHandle und QueryType.

QueryType-Parameter	RootObjectHandle-Parameter	Aufgezählte Objekte
KTMOBJECT_TRANSACTION_MANAGER	NULL-	Alle Transaktions-Manager-Objekte
KTMOBJECT_RESOURCE_MANAGER	Ein Handle für ein Transaktions-Manager-Objekt. Das Handle muss über TRANSACTIONMANAGER_QUERY_INFORMATION Zugriff auf das Objekt verfügen.	Alle Ressourcen-Manager-Objekte, die zum angegebenen Transaktions-Manager-Objekt gehören
KTMOBJECT_ENLISTMENT	Ein Handle für ein Ressourcen-Manager-Objekt. Das Handle muss über RESOURCEMANAGER_QUERY_INFORMATION Zugriff auf das Objekt verfügen.	Alle Enlistment-Objekte, die zum angegebenen Ressourcen-Manager-Objekt gehören
KTMOBJECT_TRANSACTION	Ein Handle für ein Transaktions-Manager-Objekt. Das Handle muss über TRANSACTIONMANAGER_QUERY_INFORMATION Zugriff auf das Objekt verfügen.	Alle Transaktionsobjekte, die zum angegebenen Transaktions-Manager-Objekt gehören
KTMOBJECT_TRANSACTION	NULL-	Alle Transaktionsobjekte, die zu allen Transaktions-Manager-Objekten gehören

Die meisten TPS-Komponenten müssen nicht ZwEnumerateTransactionObject-aufrufen, aber die Routine kann nützlich sein, wenn Sie ein Debugging-Hilfsprogramm schreiben müssen.

Bevor die Komponente ZwEnumerateTransactionObject-aufruft, muss sie den Puffer zuweisen und null, auf den ObjectCursor verweist. Das GUID-Array des Puffers kann groß genug sein, um ein oder mehrere Elemente zu empfangen.

Zum Aufzählen aller KTM-Objekte des angegebenen Typs muss ihre Komponente ZwEnumerateTransactionObject wiederholt aufrufen, bis sie STATUS_NO_MORE_ENTRIES zurückgibt.

Jedes Mal, wenn die Routine aufgerufen wird, füllt sie das GUID-Array des Puffers mit so vielen Objekt-GUIDs, die passen. Nach jedem Aufruf kann ihre Komponente die ObjectIdCount- Member der KTMOBJECT_CURSOR Struktur verwenden, um die Anzahl der Objekt-GUIDs zu bestimmen, die die Routine im Array gespeichert hat.

NtEnumerateTransactionObject und ZwEnumerateTransactionObject sind zwei Versionen derselben Windows Native System Services-Routine.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx und ZwXxx- Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

Beispiele

Das folgende Codebeispiel zeigt, wie sie alle Transaktionsobjekte auf einem Computer aufzählen. In diesem Beispiel enthält das GUID-Array der KTMOBJECT_CURSOR-Struktur nur ein Element, sodass jeder Aufruf von ZwEnumerateTransactionObject eine GUID zurückgibt. Die Routine erstellt eine Unicode-Zeichenfolge aus der GUID und zeigt die Zeichenfolge an.

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;
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis

Siehe auch

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

Verwenden von Nt- und Zw-Versionen der systemeigenen Systemdienste-Routinen

Freigeben über