Freigeben über


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