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

Примечание

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

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

Значения NTSTATUS делятся на четыре типа: значения успеха, информационные значения, предупреждения и значения ошибок.

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

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

NT_SUCCESS(состояние)
Возвращает значение TRUE , если возвращаемое значение, указанное в параметре Status , является типом успешного выполнения (0 – 0x3FFFFFFF) или информационным типом (0x40000000 − 0x7FFFFFFF).

NT_INFORMATION(состояние)
Возвращает значение TRUE , если возвращаемое значение, указанное в параметре Status , является информационным типом (0x40000000 − 0x7FFFFFFF).

NT_WARNING(состояние)
Возвращает значение TRUE , если возвращаемое значение, указанное в параметре Status , является типом предупреждения (0x80000000 − 0xBFFFFFFF).

NT_ERROR(состояние)
Возвращает значение TRUE , если возвращаемое значение, указанное в параметре Status , имеет тип ошибки (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 неправильно, он может случайно удалить часть полученных сведений.