Функция 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 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 для определения количества идентификаторов идентификаторов объектов, хранящихся в массиве.
NtEnumerateTransactionObject и ZwEnumerateTransactionObject являются двумя версиями одной подпрограммы собственных систем Windows.
Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.
Примеры
В следующем примере кода показано, как перечислить все объекты транзакции на компьютере. В этом примере массив 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 (include Wdm.h, Ntddk.h, Ntifs.h) |
| библиотеки | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| правил соответствия DDI | HwStorPortProhibitedDDIs, PowerIrpDDis |
См. также
использование версий собственных системных служб и Zw