Função StopTraceA (evntrace.h)
A função StopTrace interrompe a sessão de rastreamento de eventos especificada.
Essa função está obsoleta. A função ControlTrace substitui essa função.
Sintaxe
ULONG WMIAPI StopTraceA(
CONTROLTRACE_ID TraceId,
LPCSTR InstanceName,
PEVENT_TRACE_PROPERTIES Properties
);
Parâmetros
TraceId
InstanceName
Nome da sessão de rastreamento de eventos a ser interrompida 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 EVENT_TRACE_PROPERTIES que recebe as propriedades e estatísticas finais da sessão.
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.
A partir do Windows 10, versão 1703: Para obter um melhor desempenho em cenários de processo cruzado, agora você pode passar a filtragem para StopTrace para agentes privados de todo o sistema. Você precisará passar a nova estrutura de EVENT_TRACE_PROPERTIES_V2 para incluir informações de filtragem. Consulte Configurando e iniciando uma sessão de agente privado para obter mais detalhes.
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. Veja a seguir alguns erros comuns e suas causas.
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_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_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_STOP.
Se LogFileMode contiver EVENT_TRACE_FILE_MODE_PREALLOCATE, StartTrace estenderá o arquivo de log para MaximumFileSize bytes. O arquivo ocupa todo o espaço durante o registro em log, para logs circulares e sequenciais. Quando você interrompe o agente, o arquivo de log é reduzido ao tamanho necessário.
Não chame StopTrace de DllMain (pode causar deadlock).
Observação
O cabeçalho evntrace.h define StopTrace 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 [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 | Sechost.lib no Windows 8.1 e Windows Server 2012 R2; Advapi32.lib no Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |
| DLL | Sechost.dll no Windows 8.1 e no Windows Server 2012 R2; Advapi32.dll no Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP |