Функция EventWriteString (evntprov.h)

Статья
08/23/2023

Записывает событие трассировки событий Windows, содержащее строку в качестве данных. Эту функцию не следует использовать.

Синтаксис

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

Параметры

[in] RegHandle

Дескриптор регистрации поставщика. Дескриптор поступает из EventRegister. Созданное событие будет использовать Идентификатор поставщика, связанный с дескриптором.

[in] Level

8-разрядное число, используемое для описания серьезности или важности события.

Важно!

ProviderId, Level и Keyword являются основными средствами фильтрации событий. Другие виды фильтрации возможны, но имеют гораздо более высокие издержки. Всегда назначайте ненулевой уровень и ключевое слово каждому событию.

Дополнительные сведения об уровне событий см. в разделе EVENT_DESCRIPTOR .

[in] Keyword

64-разрядная битовая маска, используемая для указания членства события в наборе категорий событий.

Важно!

Дополнительные сведения о ключевое слово события см. в EVENT_DESCRIPTOR.

[in] String

Строка с завершением NUL для записи в качестве данных события.

Возвращаемое значение

Возвращает ERROR_SUCCESS в случае успешного выполнения или кода ошибки. Возможные коды ошибок:

ERROR_INVALID_PARAMETER: один или несколько параметров недопустимы.
ERROR_INVALID_HANDLE. Недопустимый дескриптор регистрации поставщика.
ERROR_ARITHMETIC_OVERFLOW: размер события больше допустимого максимума (64 КБ — заголовок).
ERROR_MORE_DATA. Размер буфера сеанса слишком мал для события.
ERROR_NOT_ENOUGH_MEMORY. Происходит, когда заполненные буферы пытаются выполнить запись на диск, но операции ввода-вывода на диске выполняются недостаточно быстро. Это происходит при медленном выполнении диска и интенсивном трафике событий. В конечном итоге отсутствуют свободные (пустые) буферы, и событие удаляется.
STATUS_LOG_FILE_FULL. Файл воспроизведения в режиме реального времени заполнен. События не регистрируются в сеансе, пока потребитель в режиме реального времени не будет использовать события из файла воспроизведения.

Код ошибки в основном предназначен для использования в сценариях отладки и диагностики. Большая часть рабочего кода должна продолжать выполняться и сообщать о событиях, даже если не удалось написать событие трассировки событий Windows, поэтому сборки выпуска обычно должны игнорировать код ошибки.

Большинство средств анализа трассировки событий Windows неправильно поддерживают только строковые события без манифеста.
Без манифеста важные сведения о событии (например, имя поставщика, идентификатор события и имя события) недоступны, поэтому полученные события трудно использовать, даже если средство анализа поддерживает события только для строк.
При использовании манифеста эта функция ведет себя почти точно так же, как код события на основе манифеста с одним строковым полем. Однако события на основе манифеста лучше поддерживаются средствами анализа трассировки. Кроме того, код, созданный MC.exe для события с одним строковым полем, более эффективен, чем функция EventWriteString .

Вместо использования этого API рассмотрите следующие варианты:

Используйте TraceLoggingProvider.h для записи событий, которые хорошо поддерживаются средствами анализа трассировки событий Windows, работы без манифеста и включения метаданных, таких как имя поставщика и имя события.
Написание манифеста инструментирования. Создайте простое событие с одним строковым значением, заканчивающееся NUL. Вы можете записывать и собирать события даже без манифеста. Манифест потребуется только для декодирования собранной трассировки.

EventWriteString записывает событие с полезными данными, состоящими из указанной строки. Этот API почти эквивалентен следующему коду:

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);

Результирующее событие совпадает с любым другим событием, созданным EventWrite , за исключением того, что для результирующего события установлен флаг EVENT_HEADER_FLAG_STRING_ONLY (сведения о флагах событий см. в разделе EVENT_HEADER ).

Обратите внимание, что событие записывается с идентификатором, версией, opcode, задачей и каналом, равным 0.

Обратите внимание, что событие использует идентификатор действия текущего потока.

Средства анализа трассировки событий Windows, которые знают о флаге EVENT_HEADER_FLAG_STRING_ONLY , могут извлекать строковое значение, даже если декодер не может найти другие сведения о декодировании для поставщика событий. Однако без манифеста средства не смогут определить имя поставщика события.

Требования


Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	evntprov.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll

См. также раздел

EventWrite

TraceLoggingProvider.h

Поделиться через