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

指向调用方分配的位置的指针,该位置接收 ZwEnumerateTransactionObjectObjectCursor 缓冲区中返回的字节数,包括 KTMOBJECT_CURSOR 结构的长度和所有返回的 GUID 的长度。

返回值

如果操作成功,但例程尚未枚举所有对象,则 ZwEnumerateTransactionObject 将返回STATUS_SUCCESS。 如果没有其他要枚举的对象,则例程返回STATUS_NO_MORE_ENTRIES。 否则,此例程可能会返回以下值之一:

返回代码 说明
STATUS_INVALID_PARAMETER QueryTypeObjectCursorLength 参数的值无效。
STATUS_OBJECT_TYPE_MISMATCH RootObjectHandle 参数指定的句柄不是有效 KTM 对象的句柄。
STATUS_INVALID_HANDLE 对象句柄无效。
STATUS_ACCESS_DENIED 调用方对枚举的对象没有适当的访问权限。

例程可能会返回其他 NTSTATUS 值

注解

下表包含 RootObjectHandleQueryType 参数的有效值。

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 数。

NtEnumerateTransactionObjectZwEnumerateTransactionObject 是同一 Windows 本机系统服务例程的两个版本。

对于来自内核模式驱动程序的调用,Windows 本机系统服务例程的 NtXxxZwXxx 版本在处理和解释输入参数的方式上的行为可能有所不同。 有关例程的 NtXxxZwXxx 版本之间的关系的详细信息,请参阅 使用本机系统服务例程的 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)

另请参阅

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

使用本机系统服务例程的 Nt 和 Zw 版本