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.
Observação
A maioria dos provedores de eventos não chamará EventRegister diretamente. Em vez disso, a maioria dos provedores de eventos é implementada usando uma estrutura ETW que encapsula as chamadas para EventRegister, EventWrite e EventUnregister. Por exemplo, você pode escrever um manifesto de evento e usar o Compilador de Mensagens para gerar código C/C++ para os eventos ou pode usar TraceLogging para evitar a necessidade de um manifesto.
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
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | evntprov.h |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |