Função EventRegister (evntprov.h)

Registra um provedor de eventos ETW, criando um identificador que pode ser usado para gravar eventos ETW.

Sintaxe

ULONG EVNTAPI EventRegister(
  [in]           LPCGUID         ProviderId,
  [in, optional] PENABLECALLBACK EnableCallback,
  [in, optional] PVOID           CallbackContext,
  [out]          PREGHANDLE      RegHandle
);

Parâmetros

[in] ProviderId

GUID que identifica exclusivamente o provedor, às vezes chamado de GUID de controle. Esse deve ser um identificador estável para que os controladores de rastreamento possam usar o GUID para assinar eventos desse provedor.

[in, optional] EnableCallback

EnableCallback opcional que o ETW invocará quando uma sessão de rastreamento habilitar ou desabilitar esse provedor. Use NULL se nenhum retorno de chamada for necessário.

[in, optional] CallbackContext

Dados de contexto opcionais que o ETW fornecerá ao invocar EnableCallback. Use NULL se nenhum contexto de retorno de chamada for necessário.

[out] RegHandle

Recebe o identificador de registro do provedor de eventos. O identificador é usado em chamadas subsequentes para APIs do provedor, como EventWrite, EventProviderEnabled e EventRegister.

Antes que o provedor descarregue ou saia, libere o identificador de registro do provedor chamando EventUnregister. Uma DLL que descarrega sem liberar todos os identificadores do provedor registrados pode causar falha no processo.

Valor retornado

Retorna ERROR_SUCCESS se tiver êxito.

O código de erro retornado por EventRegister destina-se principalmente ao uso em cenários de depuração e diagnóstico. A maioria dos códigos de produção deve continuar a ser executada mesmo se um provedor ETW não tiver sido registrado, portanto, os builds de versão geralmente devem ignorar o código de erro retornado por EventRegister.

Comentários

EventRegister cria um identificador que você pode usar para gravar eventos ETW por meio de EventWrite, EventWriteTransfer ou EventWriteEx.

O registro de um provedor de eventos não deve ser confundido com a instalação do manifesto de um provedor de eventos.

• A API EventRegister executa o registro de um provedor de eventos para criar um identificador de provedor. Essa é uma operação de escopo de processo (o identificador é válido somente dentro do processo). O identificador pode ser usado para gravar eventos ETW. Todos os eventos gravados usando o identificador serão marcados com a ProviderId especificada durante o registro do provedor. Não é necessário instalar um manifesto para gravar eventos ou capturar rastreamentos (embora a instalação do manifesto possa ser necessária para decodificar os eventos do provedor ou para que o provedor trabalhe com o Log de Eventos).
• A ferramenta wevtutil.exe é usada para instalar ou desinstalar o manifesto de um provedor de eventos. A instalação de um manifesto do provedor de eventos significa que as informações do manifesto são registradas no sistema. As informações registradas são globais do sistema e persistem até que o manifesto seja desinstalado. As informações gravadas incluem os nomes, GUIDs, canais e caminhos de DLL de recurso dos provedores definidos no manifesto. As informações do manifesto são usadas pelas ferramentas de decodificação de rastreamento e pelo Log de Eventos.

A maioria dos componentes registrará seu provedor de eventos na inicialização do componente e cancelará o registro do provedor de eventos no desligamento do componente. Por exemplo, um aplicativo (EXE) pode se registrar durante a inicialização do aplicativo e cancelar o registro durante a saída do aplicativo. Uma DLL (biblioteca dinâmica) pode se registrar DllMain durante a anexação do processo e pode cancelar o registro durante DllMain o desanexamento do processo.

Como o rastreamento de eventos é uma preocupação de depuração/diagnóstico e normalmente não é uma funcionalidade crítica ao aplicativo, a maioria dos aplicativos de varejo deve ignorar silenciosamente as falhas retornadas por EventRegister. Em caso de falha, EventRegister definirá o parâmetro RegHandle como zero para que os usos subsequentes do RegHandle (ou seja, em chamadas para EventWrite e EventUnregister) não tenham efeito.

Cada processo pode registrar até 1.024 provedores. No entanto, você deve limitar o número de provedores que seu componente registra para um ou dois. Esse limite inclui provedores registrados usando essa função e provedores registrados usando RegisterTraceGuids.

Antes do Windows Vista: Não há nenhum limite específico para o número de provedores que um processo pode registrar.

Requisitos

Confira também

EnableCallback

EventWrite

EventUnregister