Función EventWrite (evntprov.h)
Escribe un evento ETW que usa el identificador de actividad del subproceso actual.
Sintaxis
ULONG EVNTAPI EventWrite(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in] ULONG UserDataCount,
[in, optional] PEVENT_DATA_DESCRIPTOR UserData
);
Parámetros
[in] RegHandle
Identificador de registro del proveedor. El identificador procede de EventRegister. El evento generado usará el ProviderId asociado al identificador.
[in] EventDescriptor
EVENT_DESCRIPTOR con información de eventos (metadatos), incluido el identificador, la versión, el nivel, la palabra clave, el canal, el código de operación y la tarea.
Importante
ProviderId, Level y Keyword son los medios principales para filtrar eventos. Otros tipos de filtrado son posibles, pero tienen una sobrecarga mucho mayor. Asigne siempre una palabra clave y un nivel distinto de cero a todos los eventos.
[in] UserDataCount
Número de estructuras de EVENT_DATA_DESCRIPTOR en UserData. El número máximo es 128.
[in, optional] UserData
Matriz de estructuras userDataCountEVENT_DATA_DESCRIPTOR que describen los datos que se van a incluir en el evento. UserData puede ser NULL si UserDataCount es cero.
Cada EVENT_DATA_DESCRIPTOR describe un bloque de memoria que se incluirá en el evento. Los bloques especificados se concatenan en orden sin relleno ni alineación para formar el contenido del evento. Si usa la descodificación basada en manifiestos, el contenido del evento debe coincidir con el diseño especificado en la plantilla asociada al evento en el manifiesto.
Valor devuelto
Devuelve ERROR_SUCCESS si se ejecuta correctamente o un código de error. Entre los posibles códigos de error se incluyen los siguientes:
- ERROR_INVALID_PARAMETER: uno o varios de los parámetros no son válidos.
- ERROR_INVALID_HANDLE: el identificador de registro del proveedor no es válido.
- ERROR_ARITHMETIC_OVERFLOW: el tamaño del evento es mayor que el máximo permitido (64 KB - encabezado).
- ERROR_MORE_DATA: el tamaño del búfer de sesión es demasiado pequeño para el evento.
- ERROR_NOT_ENOUGH_MEMORY: se produce cuando los búferes rellenados intentan vaciar el disco, pero las E/S de disco no se producen lo suficientemente rápido. Esto sucede cuando el disco es lento y el tráfico de eventos es pesado. Finalmente, no hay más búferes libres (vacíos) y se quita el evento.
- STATUS_LOG_FILE_FULL: el archivo de reproducción en tiempo real está lleno. Los eventos no se registran en la sesión hasta que un consumidor en tiempo real consume los eventos del archivo de reproducción.
El código de error está pensado principalmente para su uso en escenarios de depuración y diagnóstico. La mayoría del código de producción debe seguir ejecutándose y seguir informando de eventos incluso si no se pudo escribir un evento ETW, por lo que las compilaciones de versión normalmente deben omitir el código de error.
Comentarios
La mayoría de los proveedores de eventos no llamarán directamente a EventWrite . En su lugar, la mayoría de los proveedores de eventos se implementan mediante un marco ETW que encapsula las llamadas a EventRegister, EventWrite y EventUnregister. Por ejemplo, puede escribir un manifiesto de evento y, a continuación, usar el compilador de mensajes para generar código de C/C++ para los eventos, o puede usar TraceLogging para evitar la necesidad de un manifiesto.
EventWrite enrutará el evento a las sesiones de seguimiento adecuadas en función del ProviderId (determinado de RegHandle), Level, Keyword y otras características de evento. Si no hay sesiones de seguimiento que graben este evento, esta función no hará nada y devolverá ERROR_SUCCESS.
Para reducir el impacto en el rendimiento de los eventos que no se registran en ninguna sesión de seguimiento, puede llamar a EventEnabled para determinar si alguna sesión de seguimiento está grabando el evento antes de preparar los datos y llamar a EventWrite.
EventWrite establece el identificador de actividad del evento en el identificador de actividad del subproceso actual. EventWrite no incluye un identificador de actividad relacionado en el evento. Para especificar un identificador de actividad diferente o para agregar un identificador de actividad relacionado, use EventWriteTransfer.
EventWrite es equivalente a EventWriteEx con 0 para Filter, 0 para Flags, NULL para ActivityId y NULL para RelatedActivityId.
Requisitos
| Cliente mínimo compatible | Windows Vista [aplicaciones de escritorio | aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | evntprov.h |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |