Función EtwWriteEx (wdm.h)
La función EtwriteEx 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 a 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 produjo 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 del EtwEnableCallback devolución de llamada.
[in] Flags
Reservado. Debe ser cero (0).
[in, optional] ActivityId
Identificador que indica la actividad asociada al evento. El 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. Use este parámetro para vincular los eventos del componente a 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 de la función etwActivityIdControl de.
[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 siguientes valores en caso de error.
Observaciones
La función EtwriteEx es el equivalente en modo kernel de la función EventWriteEx 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 a 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 el 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 etwriteEx en cualquier IRQL. Sin embargo, cuando IRQL es mayor que APC_LEVEL, los datos pasados a la etwrite de, EtwriteEx, EtwriteString, funciones etwriteTransfer no se pueden paginar. 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 al etwrite de, EtwriteEx, etwriteStringy etwriteTransfer deben residir en la memoria del espacio del sistema, independientemente de lo que sea IRQL.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows 7 |
| servidor mínimo admitido | Windows Server 2008 R2 |
| de la plataforma de destino de | Universal |
| encabezado de | wdm.h |
| biblioteca de | NtosKrnl.lib |
| DLL de | NtosKrnl.exe |