IoAllocateErrorLogEntry 函式 (wdm.h)

發行項
03/01/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 的值必須是 sizeof (IO_ERROR_LOG_PACKET) + DumpData 成員的大小 + 任何驅動程式提供的插入字串的組合大小。

驅動程式應該先檢查 EntrySize 的值是否小於 ERROR_LOG_MAXIMUM_SIZE，然後再呼叫 IoAllocateErrorLogEntry。由於 EntrySize 宣告為 UCHAR，而且編譯程式會以無訊息方式截斷任何太大的值，而無法放入 UCHAR 中，例程本身無法可靠地偵測傳遞的值是否太大。

驅動程式不得將 IoAllocateErrorLogEntry 傳回 NULL 視為嚴重錯誤。不論驅動程式是否可以記錄錯誤，驅動程式都必須繼續正常運作。