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 é obsoleta. O novo código deve usar eventRegister para registrar um provedor de rastreamento de eventos ETW no estilo do 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]     TRACEGUID_HANDLE         *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 Guid membro de cada estrutura contém um GUID de classe de rastreamento de eventos atribuído pelo provedor de registro. O GUID de classe identifica uma categoria de eventos que o provedor fornece. Os provedores usam o GUID da mesma 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 da classe do evento. Se o provedor chamar a função TraceEventInstance, use o RegHandle membro do TRACE_GUID_REGISTRATION para definir o RegHandle membro do EVENT_INSTANCE_HEADER.

Esse parâmetro poderá ser NULL se o provedor chamar apenas a função TraceEvent para registrar eventos de log. Se o provedor chamar a função TraceEventInstance para registrar eventos em log, esse parâmetro não poderá ser NULL.

[in] MofImagePath

Não há suporte para esse parâmetro. Definir 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 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. Definir 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 não ser registrados antes que a DLL ou o driver descarregue. Se o provedor não estiver registrado, ocorrerá uma falha quando o ETW tentar invocar o retorno de chamada do provedor.

Valor de retorno

Se a função for bem-sucedida, 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 opções é verdadeira:

    • RequestAddress é NULL.
    • ControlGuid é NULL.
    • RegistrationHandle é NULL.

    Windows XP e Windows 2000: TraceGuidReg é NULL ou guidCount é menor ou igual a zero.

Observações

Nota

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, TraceMessagee UnregisterTraceGuids em seu nome.

Essa função abre um identificador do provedor de eventos Clássico do (estilo Windows 2000) que pode ser usado para gravar eventos de ETW WPP baseados em MOF e TMF por meio de TraceEvent, TraceEventInstance, TraceMessagee TraceMessageVa.

Nota

Para abrir um identificador de provedor de 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 fazem referência ao 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 Gravando eventos clássicos.

Nota

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 do 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 Conventions for Function Prototypes.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
servidor com suporte mínimo Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
da Plataforma de Destino Windows
cabeçalho evntrace.h
biblioteca Sechost.lib no 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
de DLL Sechost.dll no Windows 8.1 e no 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

Consulte também

EnableTrace

UnregisterTraceGuids