Función ProcessTrace (evntrace.h)

La función ProcessTrace entrega eventos de una o varias sesiones de procesamiento de seguimiento ETW al consumidor.

Sintaxis

ETW_APP_DECLSPEC_DEPRECATED ULONG WMIAPI ProcessTrace(
  [in] PTRACEHANDLE HandleArray,
  [in] ULONG        HandleCount,
  [in] LPFILETIME   StartTime,
  [in] LPFILETIME   EndTime
);

Parámetros

[in] HandleArray

Puntero a una matriz de identificadores de sesión de procesamiento de seguimiento obtenidos de llamadas anteriores a la función OpenTrace .

La matriz puede contener hasta 64 identificadores para las sesiones de procesamiento de archivos o puede contener un identificador para una sesión de procesamiento en tiempo real. La matriz no puede contener identificadores de sesión de procesamiento de archivos y identificadores de sesión de procesamiento en tiempo real.

[in] HandleCount

Número de elementos de HandleArray.

[in] StartTime

Puntero a una estructura FILETIME opcional que especifica el período de tiempo inicial para el que desea recibir eventos. La función no entrega eventos con marcas de tiempo anteriores a StartTime.

[in] EndTime

Puntero a una estructura FILETIME opcional que especifica el período de tiempo de finalización para el que desea recibir eventos. La función no entrega eventos con marcas de tiempo después de EndTime.

Windows Server 2003: Este valor se omite para la entrega de eventos en tiempo real.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es uno de los códigos de error del sistema. A continuación se muestran algunos errores comunes y sus causas.

• ERROR_BAD_LENGTH

  HandleCount no es válido o el número de identificadores es mayor que 64.

• ERROR_INVALID_HANDLE

  Un elemento de HandleArray no es un identificador de sesión de seguimiento de eventos válido.

• ERROR_INVALID_TIME

  EndTime es menor que StartTime.

• ERROR_INVALID_PARAMETER

  HandleArray es NULL, contiene sesiones de procesamiento de archivos y sesiones de procesamiento en tiempo real o contiene más de una sesión de procesamiento en tiempo real.

• ERROR_NOACCESS

  Se produjo una excepción en una de las funciones de devolución de llamada que recibe los eventos.

• ERROR_CANCELLED

  Indica el procesamiento cancelado por el consumidor devolviendo FALSE en su función BufferCallback .

• ERROR_WMI_INSTANCE_NOT_FOUND

  La sesión de recopilación de seguimiento desde la que intenta consumir eventos en tiempo real no se está ejecutando o no tiene habilitado el modo de seguimiento en tiempo real.

Comentarios

Los consumidores de seguimiento llaman a esta función para procesar los eventos de una o varias sesiones de procesamiento de seguimiento. Esta función se bloquea hasta que finaliza el procesamiento.

Antes de llamar a ProcessTrace, use OpenTrace para abrir identificadores para realizar un seguimiento de las sesiones de procesamiento.

La función ProcessTrace entrega los eventos de las sesiones invocando las funciones de devolución de llamada BufferCallback, EventCallback y EventRecordCallback del consumidor.

La función ProcessTrace intenta entregar eventos en orden en función de la marca de tiempo del evento (es decir, intenta entregar eventos más antiguos a los más recientes). En algunos casos, ProcessTrace puede entregar eventos desordenados.

• Si el reloj usado para las marcas de tiempo del evento se ajusta hacia atrás durante la recopilación de seguimiento, el orden de entrega de los eventos es impredecible. Para evitar este problema, use el reloj QPC en lugar del reloj de hora del sistema al recopilar el seguimiento.
• Si se recopilan varios eventos con la misma marca de tiempo en diferentes CPU, el orden de entrega de los eventos es impredecible.
• Si un evento tiene una marca de tiempo no válida (por ejemplo, debido a daños en los archivos), el orden de entrega de ese evento y otros eventos del seguimiento puede ser impredecible.

La función ProcessTrace bloquea el subproceso hasta que entrega todos los eventos, la función BufferCallback devuelve FALSE o llama a CloseTrace. Además, si el consumidor consume eventos en tiempo real, la función ProcessTrace vuelve después de que el controlador detenga la sesión de seguimiento. (Tenga en cuenta que puede haber un retraso de varios segundos antes de que se devuelva la función).

Windows Server 2003: Solo puede llamar a CloseTrace después de que ProcessTrace se devuelva.

Ejemplos

Para obtener un ejemplo que usa ProcessTrace, consulte Uso de TdhFormatProperty para consumir datos de eventos.

Requisitos

Consulte también

BufferCallback

EventCallback

EventRecordCallback

OpenTrace