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

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

  • Статья

Записывает событие трассировки событий 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-разрядная битовая маска, используемая для указания членства события в наборе категорий событий.

Важно!

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

Дополнительные сведения о ключевое слово события см. в 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, поэтому сборки выпуска обычно должны игнорировать код ошибки.

Комментарии

Этот API не полезен и не должен использоваться.

  • Большинство средств анализа трассировки событий 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