Função ProcessTrace (evntrace.h)
A função ProcessTrace fornece eventos de uma ou mais sessões de processamento de rastreamento ETW para o consumidor.
Sintaxe
ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
[in] PTRACEHANDLE HandleArray,
[in] ULONG HandleCount,
[in] LPFILETIME StartTime,
[in] LPFILETIME EndTime
);
Parâmetros
[in] HandleArray
Ponteiro para uma matriz de identificadores de sessão de processamento de rastreamento obtidos de chamadas anteriores para a função OpenTrace .
A matriz pode conter até 64 identificadores para sessões de processamento de arquivos ou pode conter um identificador para uma sessão de processamento em tempo real. A matriz não pode conter identificadores de sessão de processamento de arquivo e identificadores de sessão de processamento em tempo real.
[in] HandleCount
Número de elementos em HandleArray.
[in] StartTime
Ponteiro para uma estrutura FILETIME opcional que especifica o período de tempo inicial para o qual você deseja receber eventos. A função não fornece eventos com carimbos de data/hora antes de StartTime.
[in] EndTime
Ponteiro para uma estrutura FILETIME opcional que especifica o período final para o qual você deseja receber eventos. A função não fornece eventos com carimbos de data/hora após EndTime.
Windows Server 2003: Esse valor é ignorado para entrega de eventos em tempo real.
Valor retornado
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
HandleCount não é válido ou o número de identificadores é maior que 64.
ERROR_INVALID_HANDLE
Um elemento de HandleArray não é um identificador de sessão de rastreamento de eventos válido.
ERROR_INVALID_TIME
EndTime é menor que StartTime.
ERROR_INVALID_PARAMETER
HandleArray é NULL, contém sessões de processamento de arquivo e sessões de processamento em tempo real ou contém mais de uma sessão de processamento em tempo real.
ERROR_NOACCESS
Ocorreu uma exceção em uma das funções de retorno de chamada que recebe os eventos.
ERROR_CANCELLED
Indica que o consumidor cancelou o processamento retornando FALSE em sua função BufferCallback .
ERROR_WMI_INSTANCE_NOT_FOUND
A sessão de coleta de rastreamento da qual você está tentando consumir eventos em tempo real não está em execução ou não tem o modo de rastreamento em tempo real habilitado.
Comentários
Os consumidores de rastreamento chamam essa função para processar os eventos de uma ou mais sessões de processamento de rastreamento. Essa função é bloqueada até que o processamento termine.
Antes de chamar ProcessTrace, use OpenTrace para abrir identificadores para rastrear sessões de processamento.
A função ProcessTrace fornece os eventos das sessões invocando as funções de retorno de chamada BufferCallback, EventCallback e EventRecordCallback do consumidor.
A função ProcessTrace tenta entregar eventos em ordem com base no carimbo de data/hora do evento (ou seja, ele tenta entregar eventos mais antigos ao mais recente). Em determinados casos, o ProcessTrace pode fornecer eventos fora de ordem.
- Se o relógio usado para os carimbos de data/hora do evento for ajustado para trás durante a coleta de rastreamento, a ordem de entrega dos eventos será imprevisível. Para evitar esse problema, use o relógio QPC em vez do relógio de tempo do sistema ao coletar o rastreamento.
- Se vários eventos forem coletados com o mesmo carimbo de data/hora em CPUs diferentes, a ordem de entrega dos eventos será imprevisível.
- Se um evento tiver um carimbo de data/hora inválido (por exemplo, devido a corrupção de arquivo), a ordem de entrega desse evento e outros eventos no rastreamento poderão ser imprevisíveis.
A função ProcessTrace bloqueia o thread até que ele entregue todos os eventos, a função BufferCallback retorne FALSE ou você chame CloseTrace. Além disso, se o consumidor estiver consumindo eventos em tempo real, a função ProcessTrace retornará depois que o controlador interromper a sessão de rastreamento. (Observe que pode haver um atraso de vários segundos antes que a função retorne.)
Windows Server 2003: Você pode chamar CloseTrace somente depois que ProcessTrace retornar.
Exemplos
Para obter um exemplo que usa ProcessTrace, consulte Usando TdhFormatProperty para consumir dados de evento.
Requisitos
| 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 no 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 |