Función TraceEventInstance (evntrace.h)
Un proveedor de eventos basado en RegisterTraceGuids ("clásico") usa la función TraceEventInstance para enviar un evento estructurado a una sesión de seguimiento de eventos con un identificador de instancia.
El evento usa un identificador de instancia para asociar el evento a una transacción. Esta función también se puede usar para realizar un seguimiento de las relaciones jerárquicas entre eventos relacionados.
Sintaxis
ULONG WMIAPI TraceEventInstance(
[in] TRACEHANDLE TraceHandle,
[in] PEVENT_INSTANCE_HEADER EventTrace,
[in] PEVENT_INSTANCE_INFO InstInfo,
[in] PEVENT_INSTANCE_INFO ParentInstInfo
);
Parámetros
[in] TraceHandle
Controle la sesión de seguimiento de eventos que registra la instancia de 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_INSTANCE_HEADER . Opcionalmente, los datos específicos del evento se anexan a la estructura. El evento más grande que puede registrar es 64K. Debe especificar valores para los siguientes miembros de la estructura EVENT_INSTANCE_HEADER .
- Tamaño
- Marcas
- RegHandle
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
Para realizar un seguimiento de las relaciones jerárquicas entre eventos relacionados, establezca también el miembro ParentRegHandle .
[in] InstInfo
Puntero a una estructura de EVENT_INSTANCE_INFO , que contiene el identificador de registro de esta clase de seguimiento de eventos y el identificador de instancia. Use la función CreateTraceInstanceId para inicializar la estructura.
[in] ParentInstInfo
Puntero a una estructura de EVENT_INSTANCE_INFO , que contiene el identificador de registro de la clase de seguimiento de eventos principal y su identificador de instancia. Use la función CreateTraceInstanceId para inicializar la estructura. Establezca en NULL si no está trazando una relación jerárquica.
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_FLAGS
El miembro Flags del EVENT_INSTANCE_HEADER no contiene WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY
No había memoria suficiente para completar la llamada de función. Las causas de este código de error se describen en la siguiente sección Comentarios.
ERROR_INVALID_PARAMETER
Una de las siguientes condiciones se cumple:
- EventTrace es NULL.
- pInstInfo es NULL.
- Los miembros de pInstInfo son NULL.
- TraceHandle es NULL.
- El miembro Size del EVENT_INSTANCE_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.
Windows 2000 y Windows XP: 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_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 de EVENT_INSTANCE_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 llamar a la función CreateTraceInstanceId para crear un identificador de instancia para la clase de seguimiento de eventos registrada.
- 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 eventos no relacionados, use la función TraceEvent .
Windows XP: No funciona correctamente.
Ejemplos
Para obtener un ejemplo de cómo generar conjuntos de eventos relacionados mediante CreateTraceInstanceId y TraceEventInstance, consulte Seguimiento de instancias de eventos.
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 |