Função EnableTrace (evntrace.h)

Um controlador de sessão de rastreamento chama EnableTrace para configurar como um provedor de eventos ETW registra eventos em uma sessão de rastreamento.

Essa função está obsoleta. A função EnableTraceEx2 substitui essa função.

Sintaxe

ULONG WMIAPI EnableTrace(
  [in] ULONG       Enable,
  [in] ULONG       EnableFlag,
  [in] ULONG       EnableLevel,
  [in] LPCGUID     ControlGuid,
  [in] TRACEHANDLE TraceHandle
);

Parâmetros

[in] Enable

Defina como 1 para habilitar o recebimento de eventos do provedor ou para ajustar as configurações usadas ao receber eventos do provedor (por exemplo, para alterar o nível e as palavras-chave). Defina como 0 para desabilitar o recebimento de eventos do provedor.

[in] EnableFlag

Bitmask de 32 bits de palavras-chave que determinam as categorias de eventos que você deseja que o provedor escreva. O provedor normalmente grava um evento se os bits palavra-chave do evento corresponderem a qualquer um dos bits definidos nesse valor ou se o evento não tiver palavra-chave bits definidos, além de atender ao critera EnableLevel.

Observação

Os provedores baseados em EventRegister dão suporte a palavras-chave de 64 bits. Use EnableTraceEx2 para habilitar provedores usando uma máscara MatchAnyKeyword de 64 bits.

[in] EnableLevel

Um valor que indica o nível máximo de eventos que você deseja que o provedor escreva. O provedor normalmente grava um evento se o nível do evento for menor ou igual a esse valor, além de atender aos critérios EnableFlag .

Esse valor deve estar no intervalo de 1 a 255. A Microsoft define a semântica dos níveis 1 a 5, conforme mostrado abaixo. Valores mais baixos indicam eventos mais graves. Cada valor de EnableLevel habilita o nível especificado e todos os níveis mais graves. Por exemplo, se você especificar TRACE_LEVEL_WARNING, seu consumidor receberá aviso, erro e eventos críticos.

Valor	Significado
TRACE_LEVEL_CRITICAL (1)	Eventos anormais de saída ou encerramento
TRACE_LEVEL_ERROR (2)	Eventos de erro grave
TRACE_LEVEL_WARNING (3)	Eventos de aviso, como falhas de alocação
TRACE_LEVEL_INFORMATION (4)	Eventos informativos sem erro
TRACE_LEVEL_VERBOSE (5)	Eventos de diagnóstico detalhados

As TRACE_LEVEL constantes são definidas em evntrace.h. Constantes equivalentes WINMETA_LEVEL são definidas em winmeta.h.

[in] ControlGuid

O GUID de controle (ID do provedor) do provedor de eventos que você deseja habilitar ou desabilitar.

[in] TraceHandle

Identificador da sessão de rastreamento de eventos para a qual você está configurando o provedor. A função StartTrace retorna esse identificador quando um novo rastreamento é iniciado. Para obter o identificador de um rastreamento existente, use ControlTrace para consultar as propriedades de rastreamento com base no nome do rastreamento e, em seguida, obter o identificador do campo Wnode.HistoricContext dos dados retornados EVENT_TRACE_PROPERTIES .

Valor retornado

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 condições é verdadeira:

  • ControlGuid é NULL.
  • TraceHandle é NULL.

• ERROR_INVALID_FUNCTION

  Você não pode alterar os sinalizadores de habilitação e o nível quando o provedor não está registrado.

• ERROR_WMI_GUID_NOT_FOUND

  O provedor não está registrado. Ocorre quando o KB307331 ou o Windows 2000 Service Pack 4 está instalado e o provedor não está registrado. Para evitar esse erro, o provedor deve primeiro ser registrado.

• ERROR_NO_SYSTEM_RESOURCES

  Excedeu o número de sessões de rastreamento que podem habilitar o provedor.

• ERROR_ACCESS_DENIED

  Somente usuários com privilégios administrativos, usuários no Performance Log Users grupo e serviços em execução como LocalSystem, LocalServiceou NetworkService podem habilitar provedores de eventos para uma sessão entre processos. Para conceder a um usuário restrito a capacidade de habilitar um provedor de eventos, adicione-o ao Performance Log Users grupo ou consulte EventAccessControl.

  Windows XP e Windows 2000: Qualquer pessoa pode habilitar um provedor de eventos.

Comentários

Os controladores de rastreamento de eventos chamam essa função para configurar os provedores de eventos que gravam eventos na sessão. Por exemplo, um controlador pode chamar essa função para começar a coletar eventos de um provedor, ajustar o nível ou as palavras-chave dos eventos que estão sendo coletados de um provedor ou parar de coletar eventos de um provedor.

Essa função está obsoleta. Para funcionalidade adicional, o novo código deve usar EnableTraceEx2.

As duas chamadas de função a seguir são equivalentes:

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

Para obter detalhes adicionais sobre a semântica de configuração de provedores para uma sessão, consulte a documentação de EnableTraceEx2.

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	Advapi32.lib
DLL	Advapi32.dll

Confira também

StartTrace

EnableTraceEx2