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

Примечание

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

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

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

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

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

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

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

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