Функция ReportEventW (winbase.h)

Статья
11/20/2024

Записывает запись в конце указанного журнала событий.

Синтаксис

BOOL ReportEventW(
  [in] HANDLE  hEventLog,
  [in] WORD    wType,
  [in] WORD    wCategory,
  [in] DWORD   dwEventID,
  [in] PSID    lpUserSid,
  [in] WORD    wNumStrings,
  [in] DWORD   dwDataSize,
  [in] LPCWSTR *lpStrings,
  [in] LPVOID  lpRawData
);

Параметры

[in] hEventLog

Дескриптор журнала событий. Функция RegisterEventSource возвращает этот дескриптор.

По состоянию на Windows XP с пакетом обновления 2 (SP2) этот параметр не может быть дескриптором журнала безопасности . Чтобы записать событие в журнал Security, используйте функцию AuthzReportSecurityEvent.

[in] wType

Тип события для ведения журнала. Этот параметр может быть одним из следующих значений.

Ценность	Значение
EVENTLOG_SUCCESS 0x0000	Информационное событие
EVENTLOG_AUDIT_FAILURE 0x0010	Событие аудита сбоя
EVENTLOG_AUDIT_SUCCESS 0x0008	Событие аудита успешности
EVENTLOG_ERROR_TYPE 0x0001	Событие ошибки
EVENTLOG_INFORMATION_TYPE 0x0004	Информационное событие
EVENTLOG_WARNING_TYPE 0x0002	Событие предупреждения

Дополнительные сведения о типах событий см. в типах событий.

[in] wCategory

Категория событий. Это сведения, относящиеся к источнику; Категория может иметь любое значение. Дополнительные сведения см. в разделе Категории событий.

[in] dwEventID

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

[in] lpUserSid

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

[in] wNumStrings

Количество строк вставки в массиве, на которое указывает параметр lpStrings. Значение нуля указывает, что строки отсутствуют.

[in] dwDataSize

Количество байтов необработанных (двоичных) данных для записи в журнал. Если этот параметр равен нулю, данные о событиях отсутствуют.

[in] lpStrings

Указатель на буфер, содержащий массив строк, завершающих значение NULL, которые объединяются в сообщение, прежде чем средство просмотра событий отображает строку пользователю. Этот параметр должен быть допустимым указателем (или NULL), даже если wNumStrings равно нулю. Каждая строка ограничена 31 839 символами.

До Windows Vista: Каждая строка ограничена 32K символами.

[in] lpRawData

Указатель на буфер, содержащий двоичные данные. Этот параметр должен быть допустимым указателем (или NULL), даже если параметр dwDataSize равен нулю.

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

Если функция выполнена успешно, возвращаемое значение ненулевое, указывающее, что запись была записана в журнал.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError, которая возвращает один из следующих расширенных кодов ошибок.

Код ошибки	Значение
ERROR_INVALID_PARAMETER	Один из параметров недопустим. Эта ошибка возвращается в Windows Server 2003, если данные сообщения, которые нужно регистрировать, слишком большие. Эта ошибка возвращается сервером RPC в Windows Server 2003, если параметр dwDataSize больше 261 991 (0x3ff67).
ERROR_NOT_ENOUGH_MEMORY	Недостаточно ресурсов памяти доступны для завершения операции.
RPC_S_INVALID_BOUND	Границы массива недопустимы. Эта ошибка возвращается, если данные сообщения для ведения журнала слишком большие. В Windows Vista и более поздних версиях эта ошибка возвращается, если параметр dwDataSize превышает 61 440 (0xf000).
RPC_X_BAD_STUB_DATA	Заглушка получила плохие данные. Эта ошибка возвращается в Windows XP, если данные сообщения, которые нужно зарегистрироваться, слишком большие. Эта ошибка возвращается сервером RPC в Windows XP, если параметр dwDataSize больше 262 143 (0x3ffff).
Другие	Используйте FormatMessage, чтобы получить строку сообщения для возвращаемой ошибки.

Замечания

Эта функция используется для регистрации события. Запись записывается в конец настроенного журнала для источника, определяемого параметром hEventLog. Функция ReportEvent добавляет время, длину записи и смещения перед сохранением записи в журнале. Чтобы включить функцию для добавления имени пользователя, необходимо указать идентификатор безопасности пользователя в параметре lpUserSid.

Существуют разные ограничения на размер данных сообщения, которые можно регистрироваться в зависимости от версии Windows, используемой клиентом, где выполняется приложение, и сервером, на котором регистрируется сообщение. Сервер определяется параметром lpUNCServerName, переданным в функцию RegisterEventSource. Различные ошибки возвращаются, когда превышено ограничение размера, зависящее от версии Windows.

Если строка, содержащая %n, где n является целым значением (например, %1), средство просмотра событий обрабатывает его как строку вставки. Так как IPv6-адрес может содержать эту последовательность символов, необходимо указать описатель формата (! S!) для записи сообщения о событии, содержащего IPv6-адрес. Этот описатель сообщает коду форматирования использовать строку буквально и не выполнять дальнейшие расширения (например, "мой IPv6-адрес: %1! S!").

Примеры

Пример см. в разделе Отчетов о событии.

Заметка

Заголовок winbase.h определяет ReportEvent как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll