Función EtwWrite (wdm.h)
La función EtwWrite es una función de seguimiento para publicar eventos en el código del controlador en modo kernel.
Sintaxis
NTSTATUS EtwWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[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, 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.
[in] UserDataCount
Número de estructuras de EVENT_DATA_DESCRIPTOR en UserData.
[in, optional] UserData
Puntero a la matriz de estructuras de EVENT_DATA_DESCRIPTOR.
Valor devuelto
Si el evento se publicó correctamente, EtwWrite devuelve STATUS_SUCCESS.
Si el puntero al identificador de registro del proveedor de eventos no es válido, EtwWrite devuelve STATUS_INVALID_HANDLE. El proveedor de eventos debe registrarse antes de llamar a EtwWrite . EtwWrite también puede devolver STATUS_INVALID_HANDLE si no puede registrar el evento.
Si el número de estructuras de EVENT_DATA_DESCRIPTOR especificadas en UserDataCount es mayor que el máximo permitido (128), EtwWrite devuelve STATUS_INVALID_PARAMETER.
Si se especifica ActivityID , pero no hay suficiente memoria disponible para registrar los datos asociados al evento, EtwWrite devuelve STATUS_NO_MEMORY.
Si el proveedor no está habilitado para ninguna sesión, EtwWrite devuelve STATUS_SUCCESS y los eventos no se registran.
Los eventos se pueden perder por varias razones; por ejemplo, si la tasa de eventos es demasiado alta o si el tamaño del evento es mayor que el tamaño del búfer. En estos casos, el contador EventsLost , un miembro de la estructura EVENT_TRACE_PROPERTIES del registrador correspondiente, se actualiza con el número de eventos que no se registraron.
Comentarios
La función EtwWrite es el equivalente en modo kernel de la función EventWrite en modo de usuario. 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.
Para poder llamar a la función EtwWrite para publicar un evento, debe registrar el proveedor con EtwRegister. No se debe realizar ninguna llamada de seguimiento que se encuentre fuera del código enlazado por las funciones EtwRegister y EtwUnregister . Para obtener el mejor rendimiento, puede llamar a la función EtwRegister en la rutina DriverEntry y la función EtwUnregister en la rutina DriverUnload .
Si usa el parámetro UserData opcional en la función EtwWrite para registrar datos de eventos adicionales, puede usar la macro EventDataDescCreate para simplificar la creación de las estructuras de EVENT_DATA_DESCRIPTOR. En el ejemplo siguiente se usa la macro EventDataDescCreate para inicializar EVENT_DATA_DESCRIPTOR estructuras con el nombre del dispositivo y su estado. La macro EventDataDescCreate almacena punteros a los datos (es decir, no almacena copias de los datos). Los punteros deben permanecer válidos hasta que se devuelva la llamada a EtwWrite .
Puede llamar a EtwWrite 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.
Ejemplo
//
// Register the provider with ETW in DriverEntry
// Unregister the provider in DriverUnload
//
// Build the EVENT_DATA_DESCRIPTOR structures using
// the EventDataDescCreate macros
if (RegHandle != (REGHANDLE)NULL) {
//
// Log an Event with : DeviceNameLength
// DeviceName
// Status
//
EventDataDescCreate(&EventDataDescriptor[0],
(PVOID)&DeviceName.Length,
sizeof(USHORT));
EventDataDescCreate(&EventDataDescriptor[1],
(PVOID)DeviceName.Buffer,
DeviceName.Length);
EventDataDescCreate(&EventDataDescriptor[2],
(PVOID)&Status,
sizeof(ULONG));
EtwWrite(RegHandle, // Handle from EtwRegister
&StartEvent, // EventDescriptor
NULL, // Activity ID
3, // Number of data items
EventDataDescriptor); // Array of data descriptors
}
//
Requisitos
| Requisito | Value |
|---|---|
| Plataforma de destino | Universal |
| Encabezado | wdm.h (incluya Wdm.h, Ntddk.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | Cualquier nivel (consulte la sección Comentarios). |