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 |