PRB: IoRaiseInformationalHardError Does Not Behave as Expected

The information in this article applies to:

• Microsoft Win32 Device Driver Kit (DDK) for Windows NT, versions 3.51, 4.0

SYMPTOMS

IoRaiseInformationalHardError is currently described in the documentation as:

   VOID
      IoRaiseInformationalHardError(
         IN NTSTATUS  ErrorStatus,
         IN PUNICODE_STRING  String,      /* optional */
         IN PKTHREAD  Thread        /* optional */
         );

CAUSE

IoRaiseInformationalHardError does not behave as expected for driver writers. Many writers attempt to pass in a driver-defined ErrorStatus and/or String that is expected to be displayed in the popup. This is not the case. The API's actual behavior is as follows:

• For any ErrorStatus defined outside of %DDK%\inc\ntstatus.h, the popup's text reads "Unknown Hard Error" regardless of the String parameter.
• For any ErrorStatus defined in ntstatus.h, the popup's text corresponds to the MessageText in ntstatus.h regardless of the String parameter.
• When the Thread parameter is in an application's context, the popup's title reads: "ApplicationName.exe - System Error."
• When the Thread parameter is NULL or in arbitrary system context, the popup's title reads: "System Process - System Error," and the MessageText is written to the Event Log if ErrorStatus is defined in ntstatus.h.

RESOLUTION

Driver writers can use the Event Log APIs to communicate driver-defined event strings to the user. See section 16.6, Error Logging and NTSTATUS Values, in the Kernel-mode Driver Design Guide, and the sample in %DDK%\src\general\errorlog for more information on this technique.

STATUS

This behavior is by design.