Функция 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. В противном случае эта подпрограмма может вернуть одно из следующих значений:

Подпрограмма может возвращать другие значения NTSTATUS.

Комментарии

В следующей таблице содержатся допустимые значения для параметров RootObjectHandle и QueryType .

Большинству компонентов 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;
}

Требования

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

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

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