Función EventWriteString (evntprov.h)

  • Artículo

Escribe un evento ETW que contiene una cadena como sus datos. Esta función no se debe usar.

Sintaxis

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

Parámetros

[in] RegHandle

Identificador de registro del proveedor. El identificador procede de EventRegister. El evento generado usará el ProviderId asociado al identificador.

[in] Level

Número de 8 bits usado para describir la gravedad o importancia de un evento.

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.

Consulte EVENT_DESCRIPTOR para obtener más información sobre el nivel de evento.

[in] Keyword

Máscara de bits de 64 bits usada para indicar la pertenencia de un evento en un conjunto de categorías de eventos.

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.

Consulte EVENT_DESCRIPTOR para obtener más información sobre la palabra clave event.

[in] String

Cadena terminada en NUL que se va a escribir como los datos del evento.

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

Esta API no es útil y no debe usarse.

  • La mayoría de las herramientas de análisis de ETW no admiten correctamente eventos de solo cadena sin un manifiesto.
  • Sin un manifiesto, la información importante sobre el evento (por ejemplo, el nombre del proveedor, el identificador de evento y el nombre del evento) no está disponible, por lo que los eventos resultantes son difíciles de usar incluso cuando la herramienta de análisis admite eventos de solo cadena.
  • Con un manifiesto, esta función se comporta casi exactamente como el código de un evento basado en manifiestos con un único campo de cadena. Sin embargo, el evento basado en manifiesto es mejor compatible con las herramientas de análisis de seguimiento. Además, el código generado por MC.exe para un evento con un único campo de cadena es más eficaz que la función EventWriteString .

En lugar de usar esta API, tenga en cuenta las siguientes alternativas:

  • Use TraceLoggingProvider.h para escribir eventos compatibles con las herramientas de análisis de ETW, trabajar sin un manifiesto e incluir metadatos como el nombre del proveedor y el nombre del evento.
  • Escribir un manifiesto de instrumentación. Cree un evento simple con un único valor de cadena terminada en NUL. Puede escribir y recopilar eventos incluso sin un manifiesto. Solo necesitará el manifiesto para descodificar el seguimiento recopilado.

EventWriteString escribe un evento con una carga de datos que consta de la cadena especificada. Esta API es casi equivalente al código siguiente:

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

El evento resultante es el mismo que cualquier otro evento generado por EventWrite, excepto que el evento resultante tiene establecido la marca EVENT_HEADER_FLAG_STRING_ONLY (vea EVENT_HEADER para obtener información sobre las marcas de evento).

Tenga en cuenta que el evento se escribe con identificador, versión, código operativo, tarea y canal establecido en 0.

Tenga en cuenta que el evento usa el identificador de actividad del subproceso actual.

Las herramientas de análisis ETW que son conscientes de la marca de EVENT_HEADER_FLAG_STRING_ONLY pueden extraer el valor de cadena incluso cuando el descodificador no puede encontrar ninguna otra información de descodificación para el proveedor de eventos. Sin embargo, sin un manifiesto, las herramientas no podrán determinar el nombre del proveedor del evento.

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

Consulte también

EventWrite

TraceLoggingProvider.h