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,
       CONTROLTRACE_ID TraceId
);

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 de palavra-chave do evento corresponderem a qualquer um dos bits definidos nesse valor ou se o evento não tiver nenhum bit de palavra-chave definido, além de atender ao critera EnableLevel .

[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.

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.

TraceId

Retornar valor

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

Confira também

StartTrace

EnableTraceEx2