Função TraceLoggingRegister (traceloggingprovider.h)

Artigo
08/26/2023

Registra um provedor tracelogging para que ele possa ser usado para registrar eventos. O registro é válido até que o provedor não seja registrado ou o processo seja encerrado.

Sintaxe

TLG_STATUS TraceLoggingRegister(
  TraceLoggingHProvider hProvider
);

Parâmetros

hProvider

O identificador do provedor TraceLogging a ser registrado. O identificador ainda não deve estar registrado.

Retornar valor

Se você chamar essa função do código do modo de usuário, a função retornará um HRESULT. Use a SUCCEEDED() macro para determinar se a função é bem-sucedida.

Se você chamar essa função do código do modo kernel, a função retornará um NTSTATUS. Use a NT_SUCCESS() macro para determinar se a função é bem-sucedida.

Observação

O código de erro retornado por TraceLoggingRegister 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 que um provedor ETW não tenha sido registrado, portanto, os builds de versão geralmente devem ignorar o código de erro retornado por TraceLoggingRegister.

Comentários

Quando um componente começa a ser executado, qualquer identificador do provedor TraceLogging no componente estará em um estado não registrado e todas as tentativas de usar o identificador do provedor para gerar eventos serão silenciosamente ignoradas. Antes que o provedor possa gravar eventos, você precisa registrar o provedor usando TraceLoggingRegister. Normalmente, você fará isso durante a inicialização do componente, por exemplo, em main, wmain, WinMain, DllMain(DLL_PROCESS_ATTACH)ou DriverEntry. No desligamento do componente, cancele o registro do provedor chamando TraceLoggingUnregister.

Não chame TraceLoggingRegister em um identificador de provedor que já esteja registrado. Você pode cancelar o registro de um identificador e registrá-lo novamente, se necessário, embora registrar e cancelar o registro repetidamente do identificador possa causar problemas de desempenho e deve ser evitado (ou seja, não registre, escreva alguns eventos e cancele o registro; em vez disso, registre-se uma vez na inicialização do componente e cancele o registro no desligamento do componente).

TraceLoggingRegister não é thread-safe em relação a outras chamadas para TraceLoggingRegister ou TraceLoggingUnregister no mesmo identificador. Não chame TraceLoggingRegister se for possível que outro thread possa chamar TraceLoggingRegister ou TraceLoggingUnregister no mesmo identificador ao mesmo tempo.

Se TraceLoggingRegister falhar, o identificador do provedor permanecerá sem registro e todos os usos do identificador do provedor não serão operações seguras. Em particular, é uma operação não operacional segura para chamar TraceLoggingWrite ou TraceLoggingUnregister com um identificador de provedor não registrado.

Importante

Se a DLL ou o driver chamar TraceLoggingRegister em um identificador de provedor, ele deverá chamar TraceLoggingUnregister nesse identificador de provedor antes que a DLL ou o driver descarregue. Se uma DLL for descarregada sem chamar TraceLoggingUnregister, o processo poderá falhar posteriormente. Se um driver descarregar sem chamar TraceLoggingUnregister, o sistema poderá falhar posteriormente. A função TraceLoggingRegister estabelece um retorno de chamada de configuração etw e TraceLoggingUnregister cancela o retorno de chamada. Se o retorno de chamada não for cancelado e o módulo for descarregado, ocorrerá uma falha na próxima vez que o ETW tentar invocar o retorno de chamada.

Aviso

Se o driver chamar TraceLoggingRegister e encontrar um erro durante DriverEntry, ele deverá chamar TraceLoggingUnregister antes de retornar o erro de DriverEntry. As rotinas normais de limpeza do driver não serão chamadas se o driver retornar um erro de DriverEntry e a falha ao chamar TraceLoggingUnregister causará uma falha no sistema.

TraceLoggingRegister faz o seguinte:

Chama EventRegister para abrir a conexão com o ETW.
Se EventRegister for bem-sucedido, chamará TraceLoggingSetInformation com InformationClassEventProviderSetTraits para configurar o provedor para suporte ao TraceLogging.

Uma chamada para TraceLoggingRegister é a mesma que uma chamada para TraceLoggingRegisterEx com NULL para os parâmetros de retorno de chamada e contexto. Use TraceLoggingRegisterEx se precisar receber um retorno de chamada de habilitação de ETW quando as sessões habilitarem ou desabilitarem o provedor.

Requisitos

Requisito	Valor
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]
Cabeçalho	traceloggingprovider.h
Biblioteca	Advapi32.lib