Использование значений NTSTATUS

Внимание

Если вы ищете таблицу сопоставлений значений NTSTATUS с соответствующими кодами ошибок Win32, см. статью NTSTATUS с сопоставлениями кода ошибок Win32.

Многие стандартные подпрограммы драйверов в режиме ядра и средства поддержки драйверов используют тип NTSTATUS для возвращаемых значений. Кроме того, драйверы предоставляют типизированное значение NTSTATUS в IO_STATUS_BLOCK структуре IRP при завершении IRP. Тип NTSTATUS определен в Ntdef.h, а коды состояния, предоставляемые системой, определяются в Ntstatus.h. (Поставщики также могут определять частные коды состояния, хотя они редко нуждаются. Дополнительные сведения см. в разделе "Определение новых значений NTSTATUS".)

Значения NTSTATUS делятся на четыре типа:

• Значения успеха
• Информационные значения
• Warnings
• Значения ошибок

Многочисленные значения назначаются каждому типу. Распространенная ошибка при тестировании успешного возврата из подпрограммы заключается в сравнении возвращаемого значения подпрограммы с STATUS_SUCCESS. Это сравнение проверяет наличие только одного из нескольких значений успешного выполнения.

При тестировании возвращаемого значения следует использовать один из следующих системных макросов (определенных в Ntdef.h):

Макрос	Description
NT_SUCCESS(состояние)	Вычисляется значение TRUE, если возвращаемое значение, указанное через Status, является типом успеха (0 – 0x3FFFFFFF) или информационным типом (0x40000000 — 0x7FFFFFFF).
NT_INFORMATION(состояние)	Вычисляется значение TRUE , если возвращаемое значение, указанное состоянием , является информационным типом (0x40000000 - 0x7FFFFFFF).
NT_WARNING(состояние)	Возвращает значение TRUE если возвращаемое значение, указанное Status, является типом предупреждения (0x80000000 - 0xBFFFFFFF).
NT_ERROR(состояние)	Вычисляется значение TRUE , если возвращаемое значение, указанное состоянием , является типом ошибки (0xC0000000 - 0xFFFFFFFF).

Например, предположим, что драйвер вызывает IoRegisterDeviceInterface для регистрации интерфейса устройства. Если драйвер проверяет возвращаемое значение с помощью макроса NT_SUCCESS, макрос оценивается как TRUE , если подпрограмма возвращает STATUS_SUCCESS, что указывает на отсутствие ошибок или возвращает информационное состояние STATUS_OBJECT_NAME_EXISTS, указывающее, что интерфейс устройства уже зарегистрирован.

Предположим, что драйвер вызывает ZwEnumerateKey для перечисления вложенных ключей указанного раздела реестра. Если макрос NT_SUCCESS оценивается как FALSE, это может быть связано с тем, что подпрограмма возвращает STATUS_INVALID_PARAMETER, которая является кодом ошибки или поскольку подпрограмма возвращает STATUS_NO_MORE_ENTRIES, что является кодом предупреждения.

В последнем примере предположим, что драйвер отправляет IRP, который приводит к тому, что драйвер нижнего уровня считывает информацию с устройства. Если запрашивающий драйвер указывает буфер, который слишком мал для получения любой информации, драйвер нижнего уровня может ответить, возвращая STATUS_BUFFER_TOO_SMALL, что является кодом ошибки. Если первый драйвер задает буфер, который может получать некоторые, но не все запрошенные сведения, драйвер нижнего уровня может реагировать, предоставляя максимально возможные данные, а затем возвращая STATUS_BUFFER_OVERFLOW, что является кодом предупреждения. Если первый драйвер проверяет значение состояния с помощью NT_SUCCESS или NT_ERROR неправильно, это может случайно удалить некоторые полученные сведения.