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 |