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。 否則，此例程可能會傳回下列其中一個值：

傳回碼 Description
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存取權。 屬於指定之交易管理員物件的所有 Resource Manager 物件
KTMOBJECT_ENLISTMENT Resource Manager 物件的句柄。 句柄必須具有物件的存取權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;
}

規格需求

需求 值
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)

另請參閱

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

使用原生系統服務例程的 Nt 和 Zw 版本