Função EtwRegister (wdm.h)

Artigo
02/07/2025

A função EtwRegister registra o provedor de eventos e deve ser chamada antes que um provedor possa iniciar o rastreamento. A função EtwRegister é a equivalente do modo kernel à função EventRegister do modo de usuário. A função também pode fornecer um ponteiro para uma função de retorno de chamada opcional que pode ser usada para fornecer recursos adicionais de filtragem de eventos.

Sintaxe

NTSTATUS EtwRegister(
  [in]           LPCGUID            ProviderId,
  [in, optional] PETWENABLECALLBACK EnableCallback,
  [in, optional] PVOID              CallbackContext,
  [out]          PREGHANDLE         RegHandle
);

Parâmetros

[in] ProviderId

Um ponteiro para o GUID do provedor de eventos.

[in, optional] EnableCallback

Um ponteiro para uma função de retorno de chamada opcional. A função de retorno de chamada fornece recursos adicionais de filtragem de eventos. A função de retorno de chamada é definida pelo usuário.

[in, optional] CallbackContext

A função retorna o contexto de retorno de chamada opcional quando um retorno de chamada é feito. Você pode especificar o contexto opcional ao registrar um provedor. O parâmetro CallbackContext dá suporte aos cenários em que um retorno de chamada é compartilhado por vários provedores, como em uma classe C++. O CallbackContext fornece uma maneira de distinguir as instâncias do provedor de destino para habilitar o retorno de chamada.

[out] RegHandle

Um ponteiro para uma variável que recebe o identificador de registro do provedor se a chamada de função for bem-sucedida.

Valor de retorno

A função etwRegister retorna um código de status da seguinte lista:

Código de retorno	Descrição
STATUS_SUCCESS	Indica que o provedor de eventos foi registrado com êxito no ETW.
STATUS_INVALID_PARAMETER	Indica que o parâmetro não era válido.
STATUS_Xxx	Indica que a solicitação falhou pelo motivo especificado pelo valor NTSTATUS. Consulte Ntstatus.h para obter informações detalhadas sobre o código de retorno de status real.

Observações

Antes que um driver no modo kernel possa rastrear eventos, o driver deve se registrar como um provedor de eventos usando a função EtwRegister. Quando um driver de modo kernel chama etwRegister, a função retorna um identificador de registro. Esse identificador de registro pode ser usado para testar se uma palavra-chave ou nível está habilitado para um provedor específico e para chamar funções de rastreamento e registro em log de eventos. Após a conclusão do rastreamento, um driver deve chamar a função EtwUnregister para cancelar o registro do provedor. Para cada chamada para EtwRegister deve haver uma chamada correspondente para etwUnregister. A falha ao cancelar o registro do provedor de eventos pode causar erros quando o processo é descarregado porque as funções de retorno de chamada associadas ao processo não são mais válidas. Nenhuma chamada de rastreamento deve ser feita que esteja fora do código delimitado pelas funções EtwRegister e EtwUnregister. Para obter o melhor desempenho, você pode chamar a função EtwRegister em sua rotina de DriverEntry e a função EtwUnregister em sua rotina de driverunload.

Os chamadores de etwRegister devem estar em execução em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível no Windows Vista e versões posteriores do Windows.
da Plataforma de Destino	Universal
cabeçalho	wdm.h (include Wdm.h, Ntddk.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Consulte também

EtwUnregister

Compartilhar via