NtEnumerateTransactionObject-Funktion (wdm.h)

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 für ein KTM-Objekt. Die Routine listet die untergeordneten Objekte des angegebenen Objekts auf. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen zu gültigen Werten für diesen Parameter finden Sie in der Tabelle im folgenden Abschnitt Hinweise.

[in] QueryType

Ein KTMOBJECT_TYPE typisierter Wert, der den aufzuzählenden 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, auf den ObjectCursor verweist, in Bytes.

[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 aufgelistet hat. Wenn keine weiteren Objekte aufgelistet werden müssen, 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-Parameters 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 entsprechenden Zugriff auf die Objekte, die aufgelistet werden.

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

Hinweise

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 TRANSACTIONMANAGER_QUERY_INFORMATION Zugriff auf das Objekt haben.	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 RESOURCEMANAGER_QUERY_INFORMATION Zugriff auf das Objekt haben.	Alle Einlistungsobjekte, die zum angegebenen Ressourcen-Manager-Objekt gehören
KTMOBJECT_TRANSACTION	Ein Handle für ein Transaktions-Manager-Objekt. Das Handle muss TRANSACTIONMANAGER_QUERY_INFORMATION Zugriff auf das Objekt haben.	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 ZwEnumerateTransactionObject nicht aufrufen, aber die Routine kann nützlich sein, wenn Sie ein Debugging-Hilfsprogramm schreiben müssen.

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

Um alle KTM-Objekte des angegebenen Typs aufzulisten, 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 den 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, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Beispiele

Im folgenden Codebeispiel wird gezeigt, wie alle Transaktionsobjekte auf einem Computer aufgelistet werden. 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	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis

Weitere Informationen

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen