Função UpdateTraceA (evntrace.h)

  • Artigo

A função UpdateTrace atualiza a configuração de propriedade da sessão de rastreamento de eventos especificada.

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

Sintaxe

ULONG WMIAPI UpdateTraceA(
  TRACEHANDLE             TraceHandle,
  LPCSTR                  InstanceName,
  PEVENT_TRACE_PROPERTIES Properties
);

Parâmetros

TraceHandle

Manipule para a sessão de rastreamento de eventos a ser atualizada ou 0. Você deve especificar um TraceHandle diferente de zero se InstanceName for NULL. Esse parâmetro será usado somente se InstanceName for NULL. O identificador é retornado pelo StartTrace.

InstanceName

Nome da sessão de rastreamento de eventos a ser atualizada ou NULL. Você deve especificar InstanceName se TraceHandle for 0.

Para especificar a sessão do Agente do Kernel NT, defina InstanceNamecomo KERNEL_LOGGER_NAME.

Properties

Ponteiro para uma estrutura de EVENT_TRACE_PROPERTIES inicializada.

Na entrada, os membros devem especificar os novos valores para as propriedades a serem atualizadas. Para obter informações sobre quais propriedades você pode atualizar, consulte Comentários.

Na saída, os membros da estrutura contêm as configurações e estatísticas atualizadas para a sessão de rastreamento de eventos.

Retornar valor

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. A tabela a seguir inclui alguns erros comuns e suas causas.

  • ERROR_BAD_LENGTH

    O membro BufferSize do membro Wnode de Properties especifica um tamanho incorreto.

  • ERROR_INVALID_PARAMETER

    Uma das seguintes condições é verdadeira:

    • As propriedades são NULL.
    • InstanceName e TraceHandle são NULL.
    • InstanceName é NULL e TraceHandle não é um identificador válido.
    • O membro LogFileNameOffset de Properties não é válido.
    • O membro LoggerNameOffset de Properties não é válido.

    Windows Server 2003 e Windows XP: O membro Guid da estrutura Wnode é SystemTraceControlGuid, mas o parâmetro InstanceName não é KERNEL_LOGGER_NAME.

  • ERROR_ACCESS_DENIED

    Somente usuários com privilégios administrativos, usuários no grupo Usuários do Log de Desempenho e serviços em execução como LocalSystem, LocalService, NetworkService podem controlar sessões de rastreamento de eventos. Para conceder a um usuário restrito a capacidade de controlar sessões de rastreamento, adicione-as ao grupo Usuários do Log de Desempenho.

    Windows XP e Windows 2000: Qualquer pessoa pode controlar uma sessão de rastreamento.

Comentários

Os controladores de rastreamento de eventos chamam essa função.

Essa função está obsoleta. Em vez disso, use ControlTrace com ControlCode definido como EVENT_TRACE_CONTROL_UPDATE.

Na entrada, os membros devem especificar os novos valores para as propriedades a serem atualizadas. Você pode atualizar as propriedades a seguir.

  • EnableFlags: defina esse membro como 0 para desabilitar todos os provedores de kernel. Caso contrário, você deve especificar os provedores de kernel que deseja habilitar ou manter habilitados. Aplica-se somente a sessões do agente do sistema.

  • FlushTimer: defina esse membro se quiser alterar o tempo de espera antes de liberar buffers. Se esse membro for 0, o membro não será atualizado.

  • LogFileNameOffset: defina esse membro se quiser alternar para outro arquivo de log. Se esse membro for 0, o nome do arquivo não será atualizado. Se o deslocamento não for zero e você não alterar o nome do arquivo de log, a função retornará um erro.

  • LogFileMode: defina esse membro se quiser ativar e desativar EVENT_TRACE_REAL_TIME_MODE . Para desativar o tempo real, defina esse membro como 0. Para ativar o tempo real, defina esse membro como EVENT_TRACE_REAL_TIME_MODE e ele será OR'd com os modos atuais.

  • MaximumBuffers: defina esse membro se quiser alterar o número máximo de buffers que o ETW usa. Se esse membro for 0, o membro não será atualizado.

Para sessões de agente privado, você só pode atualizar LogFileNameOffset e FlushTimer.

Se você estiver usando uma estrutura de EVENT_TRACE_PROPERTIES recém-inicializada, os únicos membros que você precisa especificar, além dos membros que você está atualizando, serão Wnode.BufferSize, Wnode.Guid e Wnode.Flags.

Se você usar a estrutura de propriedades passada para StartTrace, verifique se o membro LogFileNameOffset é 0, a menos que você esteja alterando o nome do arquivo de log.

Se você chamar a função ControlTrace para consultar as propriedades atuais da sessão e, em seguida, atualizar essas propriedades para atualizar a sessão, defina LogFileNameOffset como 0 (a menos que você esteja alterando o nome do arquivo de log) e defina EVENT_TRACE_PROPERTIES. Wnode.Flags para WNODE_FLAG_TRACED_GUID.

Para obter as configurações de propriedade e as estatísticas de sessão para uma sessão de rastreamento de eventos, chame a função ControlTrace .

Exemplos

Para obter um exemplo que usa UpdateTrace, consulte Atualizando uma sessão de rastreamento de eventos.

Observação

O cabeçalho evntrace.h define UpdateTrace 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

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho evntrace.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

ControlTrace