Função NtEnumerateTransactionObject (wdm.h)
A rotina ZwEnumerateTransactionObject enumera os objetos KTM em um computador.
Sintaxe
__kernel_entry NTSYSCALLAPI NTSTATUS NtEnumerateTransactionObject(
[in, optional] HANDLE RootObjectHandle,
[in] KTMOBJECT_TYPE QueryType,
[in, out] PKTMOBJECT_CURSOR ObjectCursor,
[in] ULONG ObjectCursorLength,
[out] PULONG ReturnLength
);
Parâmetros
[in, optional] RootObjectHandle
Um identificador para um objeto KTM. A rotina enumera os objetos filho do objeto especificado. Esse parâmetro é opcional e pode ser NULL. Para obter mais informações sobre valores válidos para esse parâmetro, consulte a tabela na seção Comentários a seguir.
[in] QueryType
Um valor do tipo KTMOBJECT_TYPE que identifica o tipo de objeto a ser enumerado. Para obter mais informações sobre valores válidos para esse parâmetro, consulte a tabela na seção Comentários a seguir.
[in, out] ObjectCursor
Um ponteiro para um buffer alocado pelo chamador que começa com uma estrutura KTMOBJECT_CURSOR . ZwEnumerateTransactionObject usa o buffer para armazenar os GUIDs de objetos que ele encontra.
[in] ObjectCursorLength
O comprimento, em bytes, do buffer para o qual ObjectCursor aponta.
[out] ReturnLength
Um ponteiro para um local alocado pelo chamador que recebe o número de bytes que ZwEnumerateTransactionObject retorna no buffer ObjectCursor , incluindo o comprimento da estrutura KTMOBJECT_CURSOR e o comprimento de todos os GUIDs retornados.
Retornar valor
ZwEnumerateTransactionObject retornará STATUS_SUCCESS se a operação for bem-sucedida, mas a rotina não enumerar todos os objetos. Se não houver mais objetos para enumerar, a rotina retornará STATUS_NO_MORE_ENTRIES. Caso contrário, essa rotina pode retornar um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
| STATUS_INVALID_PARAMETER | O valor do parâmetro QueryType ou ObjectCursorLength é inválido. |
| STATUS_OBJECT_TYPE_MISMATCH | O identificador especificado pelo parâmetro RootObjectHandle não é um identificador para um objeto KTM válido. |
| STATUS_INVALID_HANDLE | Um identificador de objeto é inválido. |
| STATUS_ACCESS_DENIED | O chamador não tem acesso apropriado aos objetos que estão sendo enumerados. |
A rotina pode retornar outros valores NTSTATUS.
Comentários
A tabela a seguir contém os valores válidos para os parâmetros RootObjectHandle e QueryType .
| Parâmetro QueryType | Parâmetro RootObjectHandle | Objetos enumerados |
|---|---|---|
| KTMOBJECT_TRANSACTION_MANAGER | NULL | Todos os objetos do gerenciador de transações |
| KTMOBJECT_RESOURCE_MANAGER | Um identificador para um objeto do gerenciador de transações. O identificador deve ter TRANSACTIONMANAGER_QUERY_INFORMATION acesso ao objeto . | Todos os objetos do gerenciador de recursos que pertencem ao objeto especificado do gerenciador de transações |
| KTMOBJECT_ENLISTMENT | Um identificador para um objeto do gerenciador de recursos. O identificador deve ter RESOURCEMANAGER_QUERY_INFORMATION acesso ao objeto . | Todos os objetos de alistamento que pertencem ao objeto do gerenciador de recursos especificado |
| KTMOBJECT_TRANSACTION | Um identificador para um objeto do gerenciador de transações. O identificador deve ter TRANSACTIONMANAGER_QUERY_INFORMATION acesso ao objeto . | Todos os objetos de transação que pertencem ao objeto especificado do gerenciador de transações |
| KTMOBJECT_TRANSACTION | NULL | Todos os objetos de transação que pertencem a todos os objetos do gerenciador de transações |
A maioria dos componentes TPS não precisa chamar ZwEnumerateTransactionObject, mas a rotina pode ser útil se você precisar escrever um utilitário de depuração.
Antes que o componente chame ZwEnumerateTransactionObject, ele deve alocar e zero o buffer para o qual ObjectCursor aponta. A matriz GUID do buffer pode ser grande o suficiente para receber um ou mais elementos.
Para enumerar todos os objetos KTM do tipo especificado, seu componente deve chamar ZwEnumerateTransactionObject repetidamente até que ele retorne STATUS_NO_MORE_ENTRIES.
Sempre que a rotina é chamada, ela preenche a matriz GUID do buffer com o máximo de GUIDs de objeto que caberão. Após cada chamada, seu componente pode usar o membro ObjectIdCount da estrutura KTMOBJECT_CURSOR para determinar o número de GUIDs de objeto armazenados na matriz.
NtEnumerateTransactionObject e ZwEnumerateTransactionObject são duas versões da mesma rotina dos Serviços do Sistema Nativo do Windows.
Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo.
Exemplos
O exemplo de código a seguir mostra como enumerar todos os objetos de transação em um computador. Neste exemplo, a matriz GUID da estrutura KTMOBJECT_CURSOR contém apenas um elemento, portanto, cada chamada para ZwEnumerateTransactionObject retorna um GUID. A rotina cria uma cadeia de caracteres Unicode do GUID e exibe a cadeia de caracteres.
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;
}
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade de DDI | HwStorPortProhibitedDIs, PowerIrpDDis |
Confira também
Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo