Función FlushTraceA (evntrace.h)

La función FlushTrace hace que una sesión de seguimiento de eventos entregue inmediatamente eventos almacenados en búfer para la sesión especificada. De forma predeterminada, una sesión de seguimiento de eventos entregará eventos cuando un búfer esté lleno, flushTimer de la sesión expira o se cierre la sesión.

Esta función está obsoleta. La función ControlTrace sustituye a esta función.

Sintaxis

ULONG WMIAPI FlushTraceA(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parámetros

TraceId

[in] InstanceName

Nombre de la sesión de seguimiento de eventos que se va a vaciar o NULL. Debe especificar InstanceName si TraceHandle es 0.

Para especificar la sesión del registrador de kernel de NT, establezca InstanceName en KERNEL_LOGGER_NAME.

[in, out] Properties

Puntero a una estructura de EVENT_TRACE_PROPERTIES inicializada.

Si usa una estructura recién inicializada, solo tiene que establecer los miembros Wnode.BufferSize, Wnode.Guid, LoggerNameOffset y LogFileNameOffset de la estructura. Puede usar el nombre de sesión máximo (1024 caracteres) y las longitudes máximas de nombre de archivo de registro (1024 caracteres) para calcular el tamaño y los desplazamientos del búfer si no se conocen.

En la salida, la estructura recibe la configuración de la propiedad y las estadísticas de sesión de la sesión de seguimiento de eventos, que reflejan el estado de la sesión después del vaciado.

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. En la tabla siguiente se incluyen algunos errores comunes y sus causas.

• ERROR_INVALID_PARAMETER

  Una de las siguientes condiciones se cumple:

  • Las propiedades son NULL.
  • InstanceName y TraceHandle son NULL.
  • InstanceName es NULL y TraceHandle no es un identificador válido.

• ERROR_BAD_LENGTH

  Una de las siguientes condiciones se cumple:

  • El miembro Wnode.BufferSize de Properties especifica un tamaño incorrecto.
  • Las propiedades no tienen espacio suficiente asignado para contener una copia del nombre de sesión y el nombre del archivo de registro (si se usa).

• ERROR_ACCESS_DENIED

  Solo los usuarios con privilegios administrativos, los usuarios del grupo Usuarios del registro de rendimiento y los servicios que se ejecutan como LocalSystem, LocalService, NetworkService pueden controlar las sesiones de seguimiento de eventos. Para conceder a un usuario restringido la capacidad de controlar las sesiones de seguimiento, agréguelas al grupo Usuarios del registro de rendimiento.

  Windows XP y Windows 2000: Cualquier persona puede controlar una sesión de seguimiento.

Comentarios

Los controladores de seguimiento de eventos llaman a esta función.

Esta función está obsoleta. En su lugar, use ControlTrace con ControlCode establecido en EVENT_TRACE_CONTROL_FLUSH.

Esta función se puede usar con una sesión en memoria (una sesión iniciada con la marca EVENT_TRACE_BUFFERING_MODE ) para escribir los datos del seguimiento en un archivo.

Normalmente no es necesario vaciar las sesiones basadas en archivos o en tiempo real porque ETW vaciará automáticamente un búfer cuando esté lleno (es decir, cuando no tenga espacio para el evento siguiente), cuando expire el FlushTimer de la sesión de seguimiento o cuando se cierre la sesión de seguimiento.

No llame a FlushTrace desde DllMain (puede provocar interbloqueo).

Requisitos

Consulte también

ControlTrace