Функция ZwEnumerateTransactionObject (wdm.h)

Статья
03/08/2023

Подпрограмма 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.

Параметр QueryType	Параметр RootObjectHandle	Перечисление объектов
KTMOBJECT_TRANSACTION_MANAGER	NULL	Все объекты диспетчера транзакций
KTMOBJECT_RESOURCE_MANAGER	Дескриптор объекта диспетчера транзакций. Дескриптор должен иметь TRANSACTIONMANAGER_QUERY_INFORMATION доступ к объекту .	Все объекты resource manager, принадлежащие указанному объекту диспетчера транзакций
KTMOBJECT_ENLISTMENT	Дескриптор объекта Resource Manager. Дескриптор должен иметь RESOURCEMANAGER_QUERY_INFORMATION доступ к объекту .	Все объекты зачисления, принадлежащие указанному объекту Resource Manager
KTMOBJECT_TRANSACTION	Дескриптор объекта диспетчера транзакций. Дескриптор должен иметь TRANSACTIONMANAGER_QUERY_INFORMATION доступ к объекту .	Все объекты транзакций, принадлежащие указанному объекту диспетчера транзакций
KTMOBJECT_TRANSACTION	NULL	Все объекты транзакций, принадлежащие всем объектам диспетчера транзакций

Большинству компонентов TPS не требуется вызывать ZwEnumerateTransactionObject, но подпрограмма может оказаться полезной, если вам нужно написать служебную программу отладки.

Прежде чем компонент вызывает ZwEnumerateTransactionObject, он должен выделить и обнулить буфер, на который указывает ObjectCursor . Массив GUID буфера может быть достаточно большим для получения одного или нескольких элементов.

Чтобы перечислить все объекты KTM указанного типа, компонент должен многократно вызывать ZwEnumerateTransactionObject , пока не вернет STATUS_NO_MORE_ENTRIES.

Каждый раз, когда вызывается подпрограмма, она заполняет массив GUID буфера любым количеством идентификаторов GUID объектов, которые поместятся. После каждого вызова компонент может использовать элемент ObjectIdCountструктуры KTMOBJECT_CURSOR, чтобы определить количество идентификаторов GUID объектов, хранящихся в массиве подпрограммой.

NtEnumerateTransactionObject и ZwEnumerateTransactionObject — это две версии одной и той же подпрограммы системных служб Windows Native.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы Собственные системные службы Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями подпрограмм NtXxx и ZwXxx см. в разделе Использование версий NT и Zw подпрограмм собственных системных служб.

Примеры

В следующем примере кода показано, как перечислить все объекты транзакций на компьютере. В этом примере массив GUID структуры KTMOBJECT_CURSOR содержит только один элемент, поэтому каждый вызов ZwEnumerateTransactionObject возвращает один GUID. Подпрограмма создает строку Юникода на основе GUID и отображает ее.

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)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

См. также раздел

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

Использование версий nt и Zw собственных системных служб

Поделиться через