Función EtwWrite (wdm.h)
La función Etwrite 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. El 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, etwrite devuelve STATUS_SUCCESS.
Si el puntero al identificador de registro del proveedor de eventos no es válido, etwrite devuelve STATUS_INVALID_HANDLE. El proveedor de eventos debe registrarse antes de llamar a Etwrite. etwrite 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), etwrite devuelve STATUS_INVALID_PARAMETER.
Si se especifica ActivityID, pero no hay suficiente memoria disponible para registrar los datos asociados al evento, etwrite devuelve STATUS_NO_MEMORY.
Si el proveedor no está habilitado para ninguna sesión, etwrite 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.
Observaciones
La función etwrite de es el equivalente en modo kernel de la función EventWrite modo de usuario. 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.
Para poder llamar a 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 de y etwUnregister. Para obtener el mejor rendimiento, puede llamar a la función EtwRegister en la rutina de DriverEntry y la función etwUnregister deDriverUnload.
Si usa el parámetro opcional UserData en la función etwrite de 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 EventDataDescCreate macro 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 etwrite 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.
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 | Valor |
|---|---|
| de la plataforma de destino de | Universal |
| encabezado de | wdm.h (include Wdm.h, Ntddk.h) |
| biblioteca de | NtosKrnl.lib |
| DLL de | NtosKrnl.exe |
| irQL | Cualquier nivel (consulte la sección Comentarios). |