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.

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.

• 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

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.

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.

Requisitos

Consulte também

EnableTrace

UnregisterTraceGuids