ZwEnumerateTransactionObject 函数 (wdm.h)
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 数组可以足够大，可以接收一个或多个元素。
若要枚举指定类型的所有 KTM 对象 ，组件必须重复调用 ZwEnumerateTransactionObject ，直到返回STATUS_NO_MORE_ENTRIES。
每次调用例程时，它都会使用适合的任意数量的对象 GUID 填充缓冲区的 GUID 数组。 每次调用后，组件都可以使用 KTMOBJECT_CURSOR 结构的 ObjectIdCount 成员来确定该例程存储在数组中的对象 GUID 数。
NtEnumerateTransactionObject 和 ZwEnumerateTransactionObject 是同一 Windows 本机系统服务例程的两个版本。
对于来自内核模式驱动程序的调用，Windows 本机系统服务例程的 NtXxx 和 ZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXxx 和 ZwXxx 版本之间的关系的详细信息，请参阅 使用本机系统服务例程的 Nt 和 Zw 版本。
示例
下面的代码示例演示如何枚举计算机上的所有事务对象。 在此示例中， KTMOBJECT_CURSOR 结构的 GUID 数组仅包含一个元素，因此每次调用 ZwEnumerateTransactionObject 都会返回一个 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;
}
要求
| 要求 | 值 |
|---|---|
| 目标平台 | 通用 |
| 标头 | wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h） |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI 符合性规则 | HwStorPortProhibitedDDI (storport) 、 PowerIrpDDis (wdm) |