Função NtEnumerateTransactionObject (wdm.h)

  • Artigo

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

KTMOBJECT_CURSOR

KTMOBJECT_TYPE

Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo