IoAllocateErrorLogEntry 函数 (wdm.h)

项目
02/29/2024

IoAllocateErrorLogEntry 例程分配错误日志条目，并返回指向调用方用于提供有关 I/O 错误信息的数据包的指针。

语法

PVOID IoAllocateErrorLogEntry(
  [in] PVOID IoObject,
  [in] UCHAR EntrySize
);

参数

[in] IoObject

指向表示发生 I/O 错误的设备的设备对象的指针，或指向表示发现错误的驱动程序的驱动程序对象的指针。

[in] EntrySize

指定要分配的错误日志条目的大小（以字节为单位）。此值不能超过ERROR_LOG_MAXIMUM_SIZE。

警告

EntrySize 是 UCHAR 值。如果指定较大的值，编译器将以无提示方式将该值截断为 (错误的) UCHAR。

返回值

IoAllocateErrorLogEntry 返回指向错误日志条目的指针;如果无法分配日志条目，则返回 NULL 。

注解

驱动程序必须先在数据包中填写有关错误的信息，然后调用 IoWriteErrorLogEntry 将条目发布到错误日志。记录日志条目后，将自动释放错误日志条目缓冲区。可以使用 IoFreeErrorLogEntry 释放不会写入日志的条目缓冲区。

错误日志条目由可变长度 IO_ERROR_LOG_PACKET 结构组成，后跟一个或多个计数为零的 Unicode 字符串。事件查看器将这些字符串插入到它为条目显示的错误消息中。 IO_ERROR_LOG_PACKET 包含一个可变长度成员， 即 DumpData 成员。因此， EntrySize 的值必须为大小 (IO_ERROR_LOG_PACKET) + DumpData 成员的大小 + 驱动程序提供的任何插入字符串的组合大小。

在调用 IoAllocateErrorLogEntry 之前，驱动程序应检查 EntrySize 的值小于 ERROR_LOG_MAXIMUM_SIZE。由于 EntrySize 声明为 UCHAR，并且编译器将以无提示方式截断任何太大而无法放入 UCHAR 的值，因此例程本身无法可靠地检测传递的值是否过大。

驱动程序不得将返回 NULL 的 IoAllocateErrorLogEntry 视为致命错误。驱动程序必须继续正常运行，无论它是否可以记录错误。