ReadEventLogA 函数 (winbase.h)

项目
08/27/2023

从指定的事件日志中读取指定数量的条目。函数可用于按时间顺序或反向时间顺序读取日志条目。

语法

BOOL ReadEventLogA(
  [in]  HANDLE hEventLog,
  [in]  DWORD  dwReadFlags,
  [in]  DWORD  dwRecordOffset,
  [out] LPVOID lpBuffer,
  [in]  DWORD  nNumberOfBytesToRead,
  [out] DWORD  *pnBytesRead,
  [out] DWORD  *pnMinNumberOfBytesNeeded
);

参数

[in] hEventLog

要读取的事件日志的句柄。 OpenEventLog 函数返回此句柄。

[in] dwReadFlags

使用以下标志值指示如何读取日志文件。此参数必须包含以下值之一， (标志) 互斥。

值	含义
EVENTLOG_SEEK_READ 0x0002	开始读取 dwRecordOffset 参数中指定的记录。如果函数无法确定日志文件的大小，则此选项可能无法用于大型日志文件。有关详细信息，请参阅知识库文章177199。
EVENTLOG_SEQUENTIAL_READ 0x0001	按顺序读取记录。如果这是第一次读取操作，则EVENTLOG_FORWARDS_READ EVENTLOG_BACKWARDS_READ标志将确定先读取哪个记录。

必须指定以下标志之一，以指示连续读取操作的方向， (标志) 互斥。

值	含义
EVENTLOG_FORWARDS_READ 0x0004	日志按时间顺序读取， (最旧到最新的) 。默认值。
EVENTLOG_BACKWARDS_READ 0x0008	日志按反向时间顺序读取， (最新到最早) 。

[in] dwRecordOffset

读取操作应从其开始的日志条目的记录号。除非 dwReadFlags 包含 EVENTLOG_SEEK_READ 标志，否则将忽略此参数。

[out] lpBuffer

应用程序分配的缓冲区，将接收一个或多个 EVENTLOGRECORD 结构。即使 nNumberOfBytesToRead 参数为零，此参数也不能为 NULL。

此缓冲区的最大大小为 0x7ffff 字节。

[in] nNumberOfBytesToRead

lpBuffer 缓冲区的大小（以字节为单位）。此函数将读取缓冲区中容纳的任意数量的日志条目;函数不会返回部分条目。

[out] pnBytesRead

指向变量的指针，该变量接收函数读取的字节数。

[out] pnMinNumberOfBytesNeeded

指向接收 lpBuffer 缓冲区所需大小的变量的指针。仅当此函数返回零且 GetLastError 返回 ERROR_INSUFFICIENT_BUFFER时，此值才有效。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

当此函数成功返回时，事件日志中的读取位置会根据读取的记录数进行调整。

注意此源的已配置文件名也可能是其他源的已配置文件名， (多个源可以作为子项存在于单个日志) 下。因此，此函数可能会返回由多个源记录的事件。

示例

有关示例，请参阅查询事件信息。

注意

winbase.h 标头将 ReadEventLog 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winbase.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll
API 集	Windows 10版本 10.0.10240 中引入的 ext-ms-win-advapi32-eventlog-ansi-l1-1-0 ()