Função ProcessTrace (evntrace.h)

  • Artigo

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

Confira também

BufferCallback

EventCallback

EventRecordCallback

OpenTrace