Función EtwWriteEx (wdm.h)
La función EtwWriteEx es una función de seguimiento para publicar eventos que admiten el filtrado en el código del controlador en modo kernel.
Sintaxis
NTSTATUS EtwWriteEx(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG64 Filter,
[in] ULONG Flags,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parámetros
[in] RegHandle
Puntero al identificador de registro del proveedor de eventos, que devuelve la función EtwRegister si el registro del proveedor de eventos se realiza correctamente.
[in] EventDescriptor
Puntero a la estructura EVENT_DESCRIPTOR .
[in] Filter
Identificadores de instancia que identifican la sesión en la que no se escribirá el evento. Es decir, el valor es una máscara de sesiones que se deben excluir del registro (filtrado). Use un or bit a bit para especificar varios identificadores. Establézcalo en cero si no admite filtros o si el evento se está escribiendo en todas las sesiones (no se ha producido ningún error en los filtros). Para obtener información sobre cómo obtener el identificador de una sesión, consulte el parámetro FilterData de la devolución de llamada EtwEnableCallback .
[in] Flags
Reservado. Debe ser cero (0).
[in, optional] ActivityId
Identificador que indica la actividad asociada al evento. ActivityID proporciona una manera de agrupar eventos relacionados y se usa en el seguimiento de un extremo a otro. Si es NULL, ETW obtiene el identificador del almacenamiento local del subproceso. Para obtener más información sobre cómo obtener este identificador, consulte EtwActivityIdControl.
[in, optional] RelatedActivityId
Identificador de actividad del componente anterior. Utilice este parámetro para vincular los eventos del componente con los eventos del componente anterior. Para obtener el identificador de actividad que se estableció para el componente anterior, consulte las descripciones del parámetro ControlCode de la función EtwActivityIdControl .
[in] UserDataCount
Número de estructuras de EVENT_DATA_DESCRIPTOR en UserData. El número máximo es 128.
[in, optional] UserData
Puntero a la matriz de estructuras de EVENT_DATA_DESCRIPTOR. Establezca este parámetro en NULL si UserDataCount es cero. Los datos deben estar en el orden especificado en el manifiesto.
Valor devuelto
Devuelve ERROR_SUCCESS si se ejecuta correctamente o uno de los valores siguientes en caso de error.
Comentarios
La función EtwWriteEx es el equivalente en modo kernel de la función EventWriteEx en modo de usuario. Los datos de eventos escritos con esta función requieren un manifiesto. El manifiesto está incrustado en el proveedor, por lo que el proveedor debe estar disponible para que un consumidor consuma los datos. Para asegurarse de que hay un consumidor para el evento que está publicando, puede preceder la llamada a EtwWrite con una llamada a EtwEventEnabled o EtwProviderEnabled.
Use los parámetros ActivityId y RelatedActivityId cuando desee relacionar eventos en distintos componentes en un escenario de seguimiento de un extremo a otro. Por ejemplo, los componentes A, B y C realizan trabajo en una actividad relacionada y quieren vincular sus eventos para que un consumidor pueda consumir todos los eventos relacionados con esa actividad.
Puede llamar a EtwWriteEx en cualquier IRQL. Sin embargo, cuando IRQL es mayor que APC_LEVEL, los datos pasados a las funciones EtwWrite, EtwWriteEx, EtwWriteString, EtwWriteTransfer no deben ser paginables. Es decir, cualquier rutina en modo kernel que se ejecuta en IRQL mayor que APC_LEVEL no puede acceder a la memoria paginable. Los datos pasados a las funciones Etwwrite, EtwwriteEx, EtwwriteString y EtwwriteTransfer deben residir en la memoria del espacio del sistema, independientemente de cuál sea el IRQL.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 7 |
| Servidor mínimo compatible | Windows Server 2008 R2 |
| Plataforma de destino | Universal |
| Encabezado | wdm.h |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |