ntEnumerateTransactionObject 函数 (wdm.h)

  • 项目

ZwEnumerateTransactionObject 例程枚举计算机上的 KTM 对象。

语法

__kernel_entry NTSYSCALLAPI NTSTATUS NtEnumerateTransactionObject(
  [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 Native System Services 例程的 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、PowerIrpDDis

另请参阅

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

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