Função FlushTraceW (evntrace.h)
A função FlushTrace faz com que uma sessão de rastreamento de eventos entregue imediatamente eventos 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 FlushTraceW(
CONTROLTRACE_ID TraceId,
[in] LPCWSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties
);
Parâmetros
TraceId
[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 InstanceNamecomo 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 Properties especifica um tamanho incorreto.
- As propriedades não têm espaço suficiente alocado para manter 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 |