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] PROCESSTRACE_HANDLE *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 arquivos e identificadores de sessão de processamento em tempo real.

[in] HandleCount

Número de elementos no 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 do StartTime.

[in] EndTime

Ponteiro para uma estrutura FILETIME opcional que especifica o período de tempo final para o qual você deseja receber eventos. A função não fornece eventos com carimbos de data/hora após o EndTime.

Windows Server 2003: Esse valor é ignorado para entrega de evento em tempo real.

Valor de retorno

Se a função for bem-sucedida, 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.

Observações

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 à corrupção de arquivos), a ordem de entrega desse evento e outros eventos no rastreamento podem ser imprevisíveis.

A função ProcessTrace bloqueia o thread até que ele entregue todos os eventos, a função BufferCallback retorna FALSE ou você chama 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 do retorno da função.)

Windows Server 2003: Você pode chamar CloseTrace somente após o retorno do ProcessTrace .

Exemplos

Para obter um exemplo que usa ProcessTrace, consulte Usando TdhFormatProperty para consumir dados de evento.

Requirements

Consulte também

BufferCallback

EventCallback

EventRecordCallback

OpenTrace