Função RegisterTraceGuidsA (evntrace.h)
A função RegisterTraceGuids registra um provedor de rastreamento de eventos ETW clássico (estilo Windows 2000) e as classes de rastreamento de eventos que ele usa para gerar eventos. Essa função também especifica a função de retorno de chamada que o sistema usa para habilitar e desabilitar o rastreamento do provedor.
Essa função está obsoleta. O novo código deve usar EventRegister para registrar um provedor de rastreamento de eventos ETW estilo Windows Vista (Crimson).
Sintaxe
ULONG WMIAPI RegisterTraceGuidsA(
[in] WMIDPREQUEST RequestAddress,
[in] PVOID RequestContext,
[in] LPCGUID ControlGuid,
[in] ULONG GuidCount,
[in, out] PTRACE_GUID_REGISTRATION TraceGuidReg,
[in] LPCSTR MofImagePath,
[in] LPCSTR MofResourceName,
[out] PTRACEHANDLE RegistrationHandle
);
Parâmetros
[in] RequestAddress
Ponteiro para uma função ControlCallback que recebe notificação quando o provedor está habilitado ou desabilitado por uma sessão de rastreamento de eventos. A função EnableTrace dispara esse retorno de chamada.
[in] RequestContext
Ponteiro para um contexto opcional definido pelo provedor que o ETW passa para a função especificada por RequestAddress.
[in] ControlGuid
Controlar GUID (ID do provedor) do provedor de registro.
[in] GuidCount
Número de elementos na matriz TraceGuidReg . Se TraceGuidReg for NULL, defina esse parâmetro como 0.
[in, out] TraceGuidReg
Ponteiro para uma matriz de
TRACE_GUID_REGISTRATION estruturas.
Cada elemento identifica uma categoria de eventos que o provedor fornece.
Na entrada, o membro Guid de cada estrutura contém um GUID de classe de rastreamento de evento atribuído pelo provedor de registro. O GUID de classe identifica uma categoria de eventos que o provedor fornece. Os provedores usam o MESMO GUID de classe para definir o membro Guid do EVENT_TRACE_HEADER ao chamar a função TraceEvent para registrar o evento em log.
Na saída, o membro RegHandle recebe um identificador para o registro guid de classe do evento. Se o provedor chamar a função TraceEventInstance , use o membro RegHandle do TRACE_GUID_REGISTRATION para definir o membro RegHandle de EVENT_INSTANCE_HEADER.
Esse parâmetro poderá ser NULL se o provedor chamar apenas a função TraceEvent para registrar eventos. Se o provedor chamar a função TraceEventInstance para registrar eventos, esse parâmetro não poderá ser NULL.
[in] MofImagePath
Não há suporte para esse parâmetro. Defina como NULL. Você deve usar Mofcomp.exe para registrar o recurso MOF durante a instalação do aplicativo. Para obter mais informações, consulte Publicando seu esquema de eventos.
Windows XP com SP1, Windows XP e Windows 2000: Ponteiro para uma cadeia de caracteres opcional que especifica o caminho da DLL ou do programa executável que contém o recurso especificado por MofResourceName. Esse parâmetro poderá ser NULL se o provedor de eventos e o consumidor usarem outro mecanismo para compartilhar informações sobre as classes de rastreamento de eventos usadas pelo provedor.
[in] MofResourceName
Não há suporte para esse parâmetro. Defina como NULL. Você deve usar Mofcomp.exe para registrar o recurso MOF durante a instalação do aplicativo. Para obter mais informações, consulte Publicando seu esquema de eventos.
Windows XP com SP1, Windows XP e Windows 2000: Ponteiro para uma cadeia de caracteres opcional que especifica o recurso de cadeia de caracteres de MofImagePath. O recurso de cadeia de caracteres contém o nome do arquivo MOF binário que descreve as classes de rastreamento de eventos compatíveis com o provedor.
[out] RegistrationHandle
Recebe o identificador de registro do provedor. Use o identificador retornado ao chamar a função UnregisterTraceGuids .
Importante
Todos os identificadores de registro criados por uma DLL ou driver devem ser cancelados antes que a DLL ou o driver seja descarregado. Se o provedor não for cancelado, ocorrerá uma falha quando o ETW tentar invocar o retorno de chamada do provedor.
Valor retornado
Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.
Se a função falhar, o valor retornado será um dos códigos de erro do sistema. Veja a seguir alguns erros comuns e suas causas.
Importante
Essa função também pode retornar o valor retornado por ControlCallback se um controlador chamar EnableTrace para habilitar o provedor e o provedor ainda não tiver chamado RegisterTraceGuids. Quando isso ocorrer, RegisterTraceGuids retornará o valor retornado do retorno de chamada se o registro tiver sido bem-sucedido.
ERROR_INVALID_PARAMETER
Uma das seguintes condições é verdadeira:
- RequestAddress é NULL.
- ControlGuid é NULL.
- RegistrationHandle é NULL.
Windows XP e Windows 2000:TraceGuidReg é NULL ou GuidCount é menor ou igual a zero.
Comentários
Observação
A maioria dos desenvolvedores não chamará essa função diretamente. Em vez disso, os desenvolvedores normalmente usarão uma estrutura ETW. Por exemplo, o WPP baseado em TMF gerencia as chamadas para RegisterTraceGuids, TraceMessage e UnregisterTraceGuids em seu nome.
Essa função abre um identificador de provedor de eventos clássico (estilo Windows 2000) que pode ser usado para gravar eventos ETW WPP baseados em MOF e TMF por meio de TraceEvent, TraceEventInstance, TraceMessage e TraceMessageVa.
Observação
Para abrir um identificador de provedor no estilo do Windows Vista que grava eventos ETW baseados em manifesto ou TraceLogging por meio de EventWrite, use EventRegister.
Se o ControlGuid do provedor tiver sido registrado e habilitado anteriormente, os registros subsequentes que referenciam o mesmo ControlGuid serão habilitados automaticamente.
Um processo pode registrar até 1.024 GUIDs do provedor; no entanto, você deve limitar o número de provedores que seu processo registra para um ou dois. Esse limite inclui aqueles registrados usando essa função e a função EventRegister .
Antes do Windows Vista: Não há limite para o número de provedores que um processo pode registrar.
Exemplos
Para obter um exemplo que usa RegisterTraceGuids, consulte Escrevendo eventos clássicos.
Observação
O cabeçalho evntrace.h define RegisterTraceGuids como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | evntrace.h |
| Biblioteca | Sechost.lib em Windows 8.1 e Windows Server 2012 R2; Advapi32.lib no Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |
| DLL | Sechost.dll em Windows 8.1 e Windows Server 2012 R2; Advapi32.dll no Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de