Функция 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 доступ к объекту . | Все объекты 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, PowerIrpDDis |