Función TraceEvent (evntrace.h)

Un proveedor de eventos basado en RegisterTraceGuids ("clásico") usa la función TraceEvent para enviar un evento estructurado a una sesión de seguimiento de eventos.

Sintaxis

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

Parámetros

[in] TraceHandle

Controle la sesión de seguimiento de eventos que registra el evento. El proveedor obtiene el identificador cuando llama a la función GetTraceLoggerHandle en su implementación de ControlCallback .

[in] EventTrace

Puntero a una estructura de EVENT_TRACE_HEADER . Opcionalmente, los datos específicos del evento se anexan a la estructura. El evento más grande que puede registrar es ligeramente menor que 64K. Debe especificar valores para los siguientes miembros de la estructura EVENT_TRACE_HEADER .

• Tamaño
• Guid o GuidPtr
• Marcas

En función de la complejidad de la información que proporciona el proveedor, también debe considerar la posibilidad de especificar valores para los siguientes miembros.

• Class.Type
• Class.Level

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_INVALID_FLAG_NUMBER

  El miembro Flags de la estructura EVENT_TRACE_HEADER es incorrecto.

• ERROR_INVALID_HANDLE

  TraceHandle no es válido o especifica el identificador de sesión del registrador de kernel nt.

• ERROR_NOT_ENOUGH_MEMORY

  La sesión se quedó sin búferes libres donde escribir. Esto puede ocurrir cuando las tasas de eventos son elevadas porque el subsistema del disco se sobrecarga o el número de búferes es demasiado pequeño. En lugar de bloquear hasta que más búferes estén disponibles, TraceEvent descarta el evento.

  Considere la posibilidad de aumentar el número y el tamaño de los búferes para la sesión, o de reducir el número de eventos escritos o el tamaño de los eventos.

  Windows 2000: No se admite.

• ERROR_OUTOFMEMORY

  El evento se descarta porque, aunque el grupo de búferes no ha alcanzado su tamaño máximo, no hay suficiente memoria disponible para asignar un búfer adicional y no hay ningún búfer disponible para recibir el evento.

• ERROR_INVALID_PARAMETER

  Una de las siguientes condiciones se cumple:

  • TraceHandle es NULL.
  • EventTrace es NULL.
  • El miembro Size de la estructura EVENT_TRACE_HEADER es incorrecto.

• ERROR_MORE_DATA

  Los datos de un único evento no pueden abarcar varios búferes. Un evento de seguimiento se limita al tamaño del búfer de la sesión de seguimiento de eventos menos el tamaño de la estructura EVENT_TRACE_HEADER .

Comentarios

Los proveedores ETW basados en MOF llaman a esta función.

Nota

La mayoría de los desarrolladores no llamarán a esta función. Esta API admite ETW basado en MOF, pero ETW basado en MOF está en desuso en favor de ETW basado en manifiestos. Además, la mayoría de los proveedores basados en MOF usan funciones de contenedor generadas por MC.exe en lugar de llamar directamente a las API de ETW.

Antes de que el proveedor pueda llamar a esta función, el proveedor

• Debe llamar a la función RegisterTraceGuids para registrarse y la clase de seguimiento de eventos.
• Debe estar habilitado. Un controlador llama a la función EnableTrace para habilitar un proveedor.

El evento se escribe en un archivo de registro, se envía a los consumidores de seguimiento de eventos en tiempo real o ambos. El miembro LogFileMode de la estructura EVENT_TRACE_PROPERTIES pasada a StartTrace define dónde se envía el evento.

Los eventos de seguimiento se escriben en el orden en que se producen.

Para realizar un seguimiento de un conjunto de eventos relacionados, use la función TraceEventInstance .

En Windows Vista, debe usar la función EventWrite para registrar eventos.

Ejemplos

Para obtener un ejemplo que use TraceEvent, vea Eventos de seguimiento.

Requisitos

Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	evntrace.h
Library	Advapi32.lib
Archivo DLL	Advapi32.dll

Consulte también

EVENT_TRACE_HEADER

EnableTrace

RegisterTraceGuids

TraceEventInstance