reportEventA 函数 (winbase.h)

  • 项目

在指定事件日志的末尾写入一个条目。

语法

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

参数

[in] hEventLog

事件日志的句柄。 RegisterEventSource 函数返回此句柄。

从具有 SP2 的 Windows XP 开始，此参数不能是 安全 日志的句柄。 若要将事件写入 安全 日志，请使用 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 之前： 每个字符串限制为 32,000 个字符。

[in] lpRawData

指向包含二进制数据的缓冲区的指针。 此参数必须是 (或 NULL) 的有效指针，即使 dwDataSize 参数为零也是如此。

返回值

如果函数成功，则返回值为非零值，表示条目已写入日志。

如果函数失败，则返回值为零。 若要获取扩展错误信息，请调用 GetLastError，这将返回以下扩展错误代码之一。

错误代码 含义
ERROR_INVALID_PARAMETER
 其中一个参数无效。

如果要记录的消息数据太大，则会在 Windows Server 2003 上返回此错误。 如果 dwDataSize 参数大于 261,991 (0x3ff67) ，则 Windows Server 2003 上的 RPC 服务器将返回此错误。
ERROR_NOT_ENOUGH_MEMORY
 内存资源不足，无法完成操作。
RPC_S_INVALID_BOUND
 数组绑定无效。

如果要记录的消息数据太大，则返回此错误。 在 Windows Vista 及更高版本中，如果 dwDataSize 参数大于 61,440 (0xf000) ，则返回此错误。
RPC_X_BAD_STUB_DATA
 占位程序接收到错误数据。

如果要记录的消息数据太大，则会在 Windows XP 上返回此错误。 如果 dwDataSize 参数大于 262,143 (0x3ffff) ，则 Windows XP 上的 RPC 服务器将返回此错误。
其他
 使用 FormatMessage 获取返回错误的消息字符串。

注解

此函数用于记录事件。 该条目将写入 到由 hEventLog 参数标识的源的配置日志的末尾。 ReportEvent 函数在将条目存储在日志中之前添加时间、条目长度和偏移量。 若要启用函数以添加用户名，必须在 lpUserSid 参数中提供用户的 SID。

根据运行应用程序的客户端和记录消息的服务器所使用的 Windows 版本，可以记录的消息数据的大小限制不同。 服务器由传递给 RegisterEventSource 函数的 lpUNCServerName 参数确定。 当超出大小限制（取决于 Windows 的版本）时，将返回不同的错误。

如果记录的字符串包含 %n，其中 n 是整数值 (例如 %1) ，则事件查看器将其视为插入字符串。 由于 IPv6 地址可以包含此字符序列，因此必须提供格式说明符 (！S！) 记录包含 IPv6 地址的事件消息。 此说明符告知格式设置代码按字面意思使用字符串，不执行任何进一步的扩展 (例如，“我的 IPv6 地址为：%1！S!") 。

示例

有关示例，请参阅 报告事件。

注意

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

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 winbase.h (包括 Windows.h)
Library Advapi32.lib
DLL Advapi32.dll

另请参阅

ClearEventLog

CloseEventLog

事件日志文件格式

事件日志记录函数

OpenEventLog

ReadEventLog

RegisterEventSource