Edit

Share via

Defining New NTSTATUS Values

  • Article

Drivers can define custom IO_ERR_XXX constants to use as ErrorCode values when logging errors. Pairs of drivers that are written together can also define custom STATUS_XXX values for IRP_MJ_INTERNAL_DEVICE_CONTROL requests.

The following diagram shows the bit fields in a 32-bit NTSTATUS value.

diagram illustrating the bit fields in an ntstatus value.

The Sev field shown in the preceding diagram indicates the severity code, which must be one of the following system-defined values:

STATUS_SEVERITY_SUCCESS
Indicates a successful NTSTATUS value, such as STATUS_SUCCESS, or the value IO_ERR_RETRY_SUCCEEDED in error log packets.

STATUS_SEVERITY_INFORMATIONAL
Indicates an informational NTSTATUS value, such as STATUS_SERIAL_MORE_WRITES.

STATUS_SEVERITY_WARNING
Indicates a warning NTSTATUS value, such as STATUS_DEVICE_PAPER_EMPTY.

STATUS_SEVERITY_ERROR
Indicates an error NTSTATUS value, such as STATUS_INSUFFICIENT_RESOURCES for a FinalStatus value or IO_ERR_CONFIGURATION_ERROR for an ErrorCode value in error log packets.

Most public IO_ERR_XXX constants belong to the STATUS_SEVERITY_ERROR category.

The Facility code specifies the facility that generated the error. For new IO_ERR_XXX values, drivers specify the FACILITY_IO_ERROR_CODE value for Facility. For custom STATUS_XXX values, the meaning of different values for Facility is driver-defined.

The C bit specifies if the value is customer-defined or Microsoft-defined. The bit is set for customer-defined values and clear for Microsoft-defined values.

Drivers can define new IO_ERR_XXX values to identify custom error messages in the system event log. For a description of how to define the NTSTATUS values and the error messages that they identify, see Defining Custom Error Types.

Pairs of drivers can define driver-specific STATUS_XXX values to communicate information about privately defined IRP_MJ_INTERNAL_DEVICE_CONTROL requests from the lower to the higher driver of the pair.

The class driver must map any private STATUS_XXX value to a system-defined NTSTATUS value when it completes an IRP if an existing higher-level driver's IoCompletion routine might be called for that IRP.

For paired display and video miniport drivers, the video port driver does the mapping between public STATUS_XXX values and the Win32-defined constants returned by video miniport drivers. For more information, see Video Miniport Drivers in the Windows 2000 Display Driver Model.

Drivers cannot use custom NTSTATUS values for IRPs that can be received in user mode, because only the system-defined values can be translated into Win32 error codes.