Função FlushTraceA (evntrace.h)

  • Artigo

A função FlushTrace faz com que uma sessão de rastreamento de eventos entregue imediatamente eventos armazenados em buffer para a sessão especificada. Por padrão, uma sessão de rastreamento de eventos fornecerá eventos quando um buffer estiver cheio, o FlushTimer da sessão expirar ou a sessão for fechada.

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

Sintaxe

ULONG WMIAPI FlushTraceA(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parâmetros

[in] TraceHandle

Manipule para a sessão de rastreamento de eventos a ser liberada 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.

[in] InstanceName

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

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

[in, out] Properties

Ponteiro para uma estrutura de EVENT_TRACE_PROPERTIES inicializada.

Se você estiver usando uma estrutura recém-inicializada, só precisará definir os membros Wnode.BufferSize, Wnode.Guid, LoggerNameOffset e LogFileNameOffset da estrutura. Você pode usar o nome máximo da sessão (1024 caracteres) e os comprimentos máximos do nome do arquivo de log (1024 caracteres) para calcular o tamanho e os deslocamentos do buffer, se não forem conhecidos.

Na saída, a estrutura recebe as configurações de propriedade e as estatísticas de sessão da sessão de rastreamento de eventos, que refletem o estado da sessão após a liberação.

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

  • ERROR_BAD_LENGTH

    Uma das seguintes condições é verdadeira:

    • O membro Wnode.BufferSize de Propriedades especifica um tamanho incorreto.
    • As propriedades não têm espaço suficiente alocado para conter uma cópia do nome da sessão e do nome do arquivo de log (se usado).

  • 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_FLUSH.

Essa função pode ser usada com uma sessão na memória (uma sessão iniciada com o sinalizador EVENT_TRACE_BUFFERING_MODE ) para gravar os dados do rastreamento em um arquivo.

Normalmente, você não precisa liberar sessões baseadas em arquivo ou em tempo real porque o ETW liberará automaticamente um buffer quando ele estiver cheio (ou seja, quando ele não tiver espaço para o próximo evento), quando o FlushTimer da sessão de rastreamento expirar ou quando a sessão de rastreamento for fechada.

Não chame FlushTrace de DllMain (pode causar deadlock).

Observação

O cabeçalho evntrace.h define FlushTrace 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 XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho evntrace.h
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

ControlTrace