Función EventWriteTransfer (evntprov.h)
Escribe un evento ETW con un identificador de actividad y un identificador de actividad relacionado opcional.
Sintaxis
ULONG EVNTAPI EventWriteTransfer(
[in] REGHANDLE RegHandle,
[in] PCEVENT_DESCRIPTOR EventDescriptor,
[in, optional] LPCGUID ActivityId,
[in, optional] LPCGUID RelatedActivityId,
[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), incluidos 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 un nivel distinto de cero y una palabra clave a cada evento.
[in, optional] ActivityId
Puntero opcional a un identificador de actividad de 128 bits para este evento. Si no es NULL, EventWriteTransfer usará el valor especificado para el identificador de actividad del evento. Si es NULL, EventWriteTransfer usará el identificador de actividad del subproceso actual.
Las herramientas de procesamiento de seguimiento pueden usar el identificador de actividad del evento para organizar los eventos en grupos denominados actividades. Para obtener más información sobre el identificador de actividad, consulte EventActivityIdControl.
[in, optional] RelatedActivityId
Puntero opcional a un identificador de actividad de 128 bits que es el elemento primario de la actividad de este evento. Si no es NULL, EventWriteTransfer usará el valor especificado para el identificador de actividad relacionado del evento. Si es NULL, el evento no tendrá un identificador de actividad relacionado. Normalmente, el identificador de actividad relacionado se establece en el evento START de la actividad (el primer evento de la actividad, registrado con Opcode = START).
Las herramientas de procesamiento de seguimiento pueden usar el identificador de actividad relacionado del evento para determinar la relación entre las actividades, por ejemplo, la actividad relacionada es el elemento primario de la actividad recién iniciada. Para obtener más información sobre el identificador de actividad relacionado, consulte EventActivityIdControl.
[in] UserDataCount
Número de estructuras de EVENT_DATA_DESCRIPTOR en UserData. El número máximo es 128.
[in, optional] UserData
Matriz de userDataCountEVENT_DATA_DESCRIPTOR estructuras 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 va a 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 notificando 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 EventWriteTransfer . En su lugar, la mayoría de los proveedores de eventos se implementan mediante un marco ETW que encapsula las llamadas a EventRegister, EventWriteTransfer 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.
EventWriteTransfer enrutará el evento a las sesiones de seguimiento adecuadas en función del ProviderId (determinado por 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 EventWriteTransfer.
EventWriteTransfer es equivalente a EventWriteEx con 0 para Filter y 0 para Flags.
Requisitos
| Requisito | Value |
|---|---|
| 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 |