Função NtEnumerateTransactionObject (wdm.h)
A rotina de 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 KTMOBJECT_TYPEdigitado 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 por chamador que começa com uma estrutura KTMOBJECT_CURSOR. ZwEnumerateTransactionObject usa o buffer para armazenar os GUIDs de objetos encontrados.
[in] ObjectCursorLength
O comprimento, em bytes, do buffer que ObjectCursor aponta para.
[out] ReturnLength
Um ponteiro para um local alocado por 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.
Valor de retorno
ZwEnumerateTransactionObject retornará STATUS_SUCCESS se a operação for bem-sucedida, mas a rotina não tiver enumerado todos os objetos. Se não houver mais objetos para enumerar, a rotina retornará STATUS_NO_MORE_ENTRIES. Caso contrário, essa rotina poderá retornar um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
| STATUS_INVALID_PARAMETER | O QueryType ou o valor do parâmetro ObjectCursorLength é inválido. |
| STATUS_OBJECT_TYPE_MISMATCH | O identificador que o parâmetro RootObjectHandle especifica 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 .
Observações
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 acesso TRANSACTIONMANAGER_QUERY_INFORMATION ao objeto. | Todos os objetos do gerenciador de recursos que pertencem ao objeto do gerenciador de transações especificado |
| KTMOBJECT_ENLISTMENT | Um identificador para um objeto do gerenciador de recursos. O identificador deve ter acesso RESOURCEMANAGER_QUERY_INFORMATION ao objeto. | Todos os objetos de inscrição 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 acesso TRANSACTIONMANAGER_QUERY_INFORMATION ao objeto. | Todos os objetos de transação que pertencem ao objeto do gerenciador de transações especificado |
| 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é retornar 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 se ajustarão. Após cada chamada, seu componente pode usar o membro ObjectIdCount da estrutura de 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 nativos do Windows.
Para chamadas de drivers no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de 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 de serviços do 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 |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| regras de conformidade de DDI | HwStorPortProhibitedDIs, PowerIrpDDis |
Consulte também
usando versões Nt e Zw das rotinas de serviços do sistema nativo