Использование значений NTSTATUS
Внимание
Если вы ищете таблицу сопоставлений значений NTSTATUS с соответствующими кодами ошибок Win32, см . статью NTSTATUS с сопоставлениями кода ошибок Win32.
Многие стандартные подпрограммы драйверов в режиме ядра и средства поддержки драйверов используют тип NTSTATUS для возвращаемых значений. Кроме того, драйверы предоставляют типизированное значение NTSTATUS в IO_STATUS_BLOCK структуре IRP при завершении IRP. Тип NTSTATUS определен в Ntdef.h, а коды состояния, предоставляемые системой, определяются в Ntstatus.h. (Поставщики также могут определять частные коды состояния, хотя они редко нуждаются. Дополнительные сведения см. в разделе "Определение новых значений NTSTATUS".)
Значения NTSTATUS делятся на четыре типа: значения успешности, информационные значения, предупреждения и значения ошибок.
Многочисленные значения назначаются каждому типу. Распространенная ошибка при тестировании успешного возврата из подпрограммы заключается в сравнении возвращаемого значения подпрограммы с STATUS_SUCCESS. Это сравнение проверяет наличие только одного из нескольких значений успешного выполнения.
При тестировании возвращаемого значения следует использовать один из следующих системных макросов (определенных в Ntdef.h):
| Макрос | Description |
|---|---|
| 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 неправильно, это может случайно удалить некоторые полученные сведения.